Email webhooks

Last verified

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

  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, 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:

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.

Stuck? Contact support — replies within one business day.