Email HTTP API

Laatst gecontroleerd

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…"}]
  }'
  • from is standaard de mailbox; het mag de mailbox zijn of een van zijn aliassen.
  • to, cc en bcc bevatten samen maximaal 25 adressen. Geef text, html of allebei.
  • attachments zijn 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

Email

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

Gerelateerd

Kom je er niet uit? Neem contact op met support — antwoord binnen één werkdag.