# Email webhooks

> Get a mail.received webhook when a message arrives in a mailbox your app reads, instead of polling.

Source: https://veldhost.eu/docs/email-webhooks

Last verified: 2026-11-16

Instead of checking a mailbox every minute, your app can be told when mail arrives. veldhost sends a `mail.received` webhook for every message delivered into a mailbox that has an [Email API key](https://veldhost.eu/docs/email-api-keys) allowed to read it, usually within a minute or two.

## Set it up

1. Make sure the mailbox has an Email API key with **Read mail** or **Change mail**.
2. Add a webhook as described in [Webhooks, Slack and Teams](https://veldhost.eu/docs/webhooks-and-integrations), and tick **Email received (Email API)**.

The webhook is for the whole account: it receives `mail.received` for every mailbox on the account that has such a key.

## What arrives

A signed delivery, like every veldhost webhook, whose `data` is:

```json
{
  "mailbox": "orders@example.com",
  "folder": "INBOX",
  "message_id": "<CAF3x…@mail.example.org>",
  "received_at": "2026-12-01T10:00:00Z"
}
```

It says where a message arrived, never what is in it: no sender, subject or content. `folder` is where the mailbox's filters put it. `message_id` is the message's own `Message-ID` header, or `null` when it had none.

Your app then fetches the message with its own key:

- over the [Email HTTP API](https://veldhost.eu/docs/email-http-api): `GET …/mail-api/messages?folder=INBOX&message_id=<the id>`;
- or over IMAP, searching the folder for the `Message-ID` header ([Read email from your app](https://veldhost.eu/docs/read-email-from-your-app)).

Verify the signature and handle retries exactly as for other webhooks ([Webhooks, Slack and Teams](https://veldhost.eu/docs/webhooks-and-integrations)). A message delivered into two folders (by a filter that copies) sends one webhook per folder.

Each `mail.received` that reaches your endpoint counts as one webhook in your [Email API usage](https://veldhost.eu/docs/email-api-pricing).

## Related

- [Email HTTP API](https://veldhost.eu/docs/email-http-api)
- [Email API keys](https://veldhost.eu/docs/email-api-keys)
- [Webhooks, Slack and Teams](https://veldhost.eu/docs/webhooks-and-integrations)