De Email HTTP API doet voor één mailbox wat SMTP en IMAP doen, maar dan via gewone HTTPS en JSON: handig voor serverless functies, low-codetools en alles wat geen mailverbinding kan openen. MAIL_API staat hieronder voor https://manage.veldhost.eu/api/v1 gevolgd door /mail-api.
Authenticatie
Stuur de Email API-sleutel van de mailbox mee als bearer-token:
Authorization: Bearer vmk_…
De sleutel bepaalt alles: welke mailbox, of hij mag versturen, lezen, of lezen en wijzigen, en vanaf welke adressen. API-tokens (mpc_…) werken hier niet, en een Email API-sleutel werkt nergens anders.
Een bericht versturen
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…"}]
}'
fromis standaard de mailbox; het mag de mailbox zijn of een van zijn aliassen.to,ccenbccbevatten samen maximaal 25 adressen. Geeftext,htmlof allebei.attachmentszijn base64, samen maximaal 10 MB.- Je mag maar een paar headers zelf zetten:
List-Unsubscribe,List-Unsubscribe-Post,X-Entity-Ref-ID,Auto-Submitted,Precedence,In-Reply-To,References. - Stuur je binnen 24 uur dezelfde
Idempotency-Key, dan geeft de API het eerste antwoord terug in plaats van opnieuw te versturen.
Een 202 betekent dat onze mailserver het bericht heeft aangenomen om af te leveren. Het wordt ondertekend voor je domein en telt mee voor de verzendlimieten van de mailbox en voor je gebruik van de Email API.
Mail lezen en wijzigen
Je wijst een bericht aan met folder (standaard INBOX) en zijn uid. Lezen markeert een bericht nooit als gelezen. Voor wijzigen heb je een sleutel nodig die Change mail mag.
# 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}'
Om door een map te bladeren, geef je next_before uit het vorige antwoord mee als before. Zoek je het bericht waarover een mail.received-webhook je vertelde, vraag de lijst dan op met message_id=.
Endpoints
Domains with veldhost email: their mailboxes, verification and the DNS records they still need.
| Methode | Pad | Wat het doet | 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 | Ja |
POST |
/mail/{domain}/verify |
Check the verification record now (dns scope); veldhost also checks every 15 minutes | Ja |
Fouten
Fouten gebruiken de gewone envelop van de API, met een eigen reason van de Email API:
| Status | error.reason |
Betekenis |
|---|---|---|
| 401 | invalid_key |
Geen sleutel, of een foute, ingetrokken of verlopen sleutel |
| 403 | scope |
De sleutel mag dit niet (versturen, lezen of wijzigen) |
| 403 | address_not_allowed |
Je adres staat niet in Allowed from van de sleutel |
| 402 | usage_cap_reached |
De uitgavenlimiet van het account heeft versturen gepauzeerd; lezen werkt nog |
| 403 | refused_by_mail_server |
De mailserver weigerde de sleutel (bijvoorbeeld een geblokkeerde mailbox) |
| 422 | invalid_message, rejected |
Er klopt iets niet aan het bericht, of de mailserver weigerde het (de reden staat erbij) |
| 429 | rate_limited, try_later |
Doe het rustiger aan, of probeer het later opnieuw |