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…"}]
}'
fromdefaults to the mailbox; it may be the mailbox or one of its aliases.to,ccandbcctogether hold at most 25 addresses. Givetext,htmlor both.attachmentsare 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-Keywithin 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
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 |