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 allowed to read it, usually within a minute or two.
Set it up
- Make sure the mailbox has an Email API key with Read mail or Change mail.
- Add a webhook as described in Webhooks, Slack and Teams, 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:
{
"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:
GET …/mail-api/messages?folder=INBOX&message_id=<the id>; - or over IMAP, searching the folder for the
Message-IDheader (Read email from your app).
Verify the signature and handle retries exactly as for other webhooks (Webhooks, Slack and Teams). 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.