# Email HTTP API

> Send, read and organise one mailbox's mail over HTTPS with its Email API key, without SMTP or IMAP.

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

Last verified: 2026-11-16

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

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

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

```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}'
```

To page through a folder, pass the previous answer's `next_before` as `before`. To find the message a [`mail.received` webhook](https://veldhost.eu/docs/email-webhooks) 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 |

## Related

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