# Email HTTP API

> Verstuur, lees en orden de mail van één mailbox via HTTPS met een Email API-sleutel, zonder SMTP of IMAP.

Source: https://veldhost.eu/nl/docs/email-http-api

Last verified: 2026-11-16

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](https://veldhost.eu/docs/email-api-keys) 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

```bash
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](https://veldhost.eu/docs/email-api-pricing).

## 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.

```bash
# 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](https://veldhost.eu/docs/email-webhooks) 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

- [Email API-sleutels](https://veldhost.eu/docs/email-api-keys)
- [Email-webhooks](https://veldhost.eu/docs/email-webhooks)
- [Prijzen van de Email API](https://veldhost.eu/docs/email-api-pricing)