Webhook events
The one event Mail sends, message.received, with every field of its body and how delivery is retried.
reference~2 minVerified v0.216.0
Mail sends one event, message.received, for each new message in a mailbox that has a webhook. Set the webhook with mail_webhook_set; see Mail webhooks for the setup. Each request is signed: see Webhook signing.
The event is a nudge. The body carries identifiers, never the message text. The agent reads the message with mail_thread.
The request
POST to your address, with these headers.
| Header | Value |
|---|---|
content-type | application/json |
x-mail-signature | t=<unix seconds>,v1=<hex> |
user-agent | SuperAgentMail-Webhook/1 |
message.received
{
"type": "message.received",
"mailboxId": "…",
"threadId": "…",
"messageId": "…",
"from": "ada@example.com",
"subject": "Quarterly report",
"auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "dmarcAligned": true },
"injection": { "score": 0, "reasons": [] }
}| Field | Type | Meaning |
|---|---|---|
type | string | Always message.received. |
mailboxId | string | The mailbox the message arrived in. |
threadId | string | The thread it joined, for mail_thread. |
messageId | string | The new message. |
from | string | The sender's address. |
subject | string | The subject line. |
auth | object | spf, dkim and dmarc, each pass, fail, softfail, neutral, none, temperror, permerror or unknown; and dmarcAligned, true when DMARC passed for the very domain shown in From. |
injection | object | score from 0 to 1 and the reasons behind it. See Screened mail. |
When no event is sent
- Machine mail sends no event.
- A screened message sends none until a person releases it. Releasing it queues the event that was held back.
- Mail sent by the agent itself is not an event.
Delivery and retries
A 2xx answer counts as delivered. A 3xx or 4xx answer other than 408 or 429 is final and is not retried. A 5xx answer, 408, 429, a timeout or a network error is retried, up to five times.
Before each delivery Mail checks the address again. It must be https on port 443 with no credentials and a public host name. Redirects are not followed, and a delivery times out after 5 seconds. An address that is no longer safe is dropped without a retry.
A retry sends the same body, so make the receiver safe to run twice: the messageId identifies the message.