Email HTTP API

Last verified

The Email HTTP API does what SMTP and IMAP do for one mailbox, over plain HTTPS and JSON: handy for serverless functions, low-code tools and anything that cannot open a mail connection. MAIL_API below stands for https://manage.veldhost.eu/api/v1 followed by /mail-api.

Authentication

Send the mailbox's Email API key as a bearer token:

Authorization: Bearer vmk_…

The key decides everything: which mailbox, whether it may send, read, or read and change, and from which addresses. API tokens (mpc_…) do not work here, and an Email API key works nowhere else.

Send a message

curl -X POST "MAIL_API/send" \
  -H "Authorization: Bearer $EMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "from": {"email": "noreply@example.com", "name": "Example Shop"},
    "to": ["customer@example.org"],
    "subject": "Your order 1042",
    "text": "Thank you for your order.",
    "html": "<p>Thank you for your order.</p>",
    "attachments": [{"filename": "invoice.pdf", "content_type": "application/pdf", "content": "JVBERi0xLjQK…"}]
  }'
  • from defaults to the mailbox; it may be the mailbox or one of its aliases.
  • to, cc and bcc together hold at most 25 addresses. Give text, html or both.
  • attachments are base64, at most 10 MB together.
  • Only a few headers may be set: List-Unsubscribe, List-Unsubscribe-Post, X-Entity-Ref-ID, Auto-Submitted, Precedence, In-Reply-To, References.
  • With the same Idempotency-Key within 24 hours, the API returns the first answer instead of sending again.

A 202 means our mail server accepted the message for delivery. It is signed for your domain and counts towards the mailbox's sending limits and your Email API usage.

Read and change mail

Messages are addressed by folder (default INBOX) and their uid. Reading never marks a message as read. Changing needs a key that may Change mail.

# the newest unread messages
curl "MAIL_API/messages?unseen=true&limit=20" -H "Authorization: Bearer $EMAIL_API_KEY"
# one message with its text, html and attachment list
curl "MAIL_API/messages/4711" -H "Authorization: Bearer $EMAIL_API_KEY"
# mark it read
curl -X PATCH "MAIL_API/messages/4711" -H "Authorization: Bearer $EMAIL_API_KEY" \
  -H "Content-Type: application/json" -d '{"seen": true}'

To page through a folder, pass the previous answer's next_before as before. To find the message a mail.received webhook told you about, list with message_id=.

Endpoints

Email

Domains with veldhost email: their mailboxes, verification and the DNS records they still need.

Method Path What it does Idempotency-Key
GET /mail Domains with veldhost email and their mailboxes (read scope)
GET /mail/{domain} One email domain: its mailboxes, verification and the DNS records it still needs
GET /mail/mailboxes/{address}/api-keys The Email API keys of one mailbox you manage (read scope): access (send, read, write), allowed addresses, expiry, last use, whether sending is paused at the spend cap. Never a key itself; new keys are made in the portal (create_url)
DELETE /mail/mailboxes/{address}/api-keys/{id} Revoke one Email API key at once (manage scope): apps using it stop sending and reading with it Yes
POST /mail/{domain}/verify Check the verification record now (dns scope); veldhost also checks every 15 minutes Yes

Errors

Errors use the API's usual envelope, with the Email API's own reason:

Status error.reason Meaning
401 invalid_key No key, or a wrong, revoked or expired one
403 scope The key may not do this (send, read or change)
403 address_not_allowed Your address is not in the key's Allowed from
402 usage_cap_reached The account's spend cap paused sending; reading still works
403 refused_by_mail_server The mail server refused the key (for example a locked mailbox)
422 invalid_message, rejected Something is wrong with the message, or the mail server refused it (the reason is included)
429 rate_limited, try_later Slow down, or retry later

Stuck? Contact support — replies within one business day.