Skip to content
AI Inbx
Esc
↑↓navigate↵open⌘Jpreview

email.bounced

Delivery to one or more recipients failed; a dead address is suppressed.

POSTemail.bouncedWebhook
Header parameters
AIInbx-Signaturestringrequired

t=<unix seconds>,v1=<hmac>: an HMAC-SHA256 of the timestamp and the raw body, with one v1 per secret while a rotation's grace period runs.

AIInbx-Event-IDstringrequired

The event id, id in the body.

Request body
requiredapplication/json
idstringrequired

The event, evt_…. Stable across retries and replays: deduplicate on it.

matches ^[a-z]+_[0-9a-f]{32}$
typestringrequired
created_atstring<date-time>required

When the event happened.

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
space_idstring | nullrequired

Which space a resource is in. Null is the workspace itself — what every resource of a workspace that has no spaces says.

Show properties
Any of:
string
string
null
null
dataobjectrequired
Show properties
email_idstringrequired

The email, eml_…. Retrieve it for bodies and headers.

matches ^[a-z]+_[0-9a-f]{32}$
message_idstringrequired

The RFC Message-ID, without angle brackets.

thread_idstringrequired

The conversation it belongs to.

matches ^[a-z]+_[0-9a-f]{32}$
domain_idstring | nullrequired

The domain the message went through: received on or sent from. Null when it went through a mailbox.

Show properties
Any of:
string
string
null
null
mailbox_idstring | nullrequired

The mailbox the message went through: synced from or sent with. Null when it went through a domain.

Show properties
Any of:
string
string
null
null
suppression_keystring | nullrequired

The suppression list the send named, when it named one.

Show properties
Any of:
string
string
null
null
recipientsstring<email>[]required

Which recipients bounced: the message did not reach them, and nothing will try again.

bouncesobject[]

One entry per address in recipients, in the same order: why it bounced, and whether it was suppressed. Absent from an event recorded before this field existed, which GET /events and a replay still return as it was.

Show properties
Array of object
addressstring<email>required
matches ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
causestringrequired

Why the mail did not arrive. bad_address: the address does not exist or no longer takes mail. mailbox_full: it exists and is over its quota. sender_auth: the receiving side would not take it as from the sending domain — DMARC, SPF or DKIM failed — which is fixed in the domain's DNS records. blocked: refused by the receiving side's policy — a blocklist, the sender's reputation, a recipient that only takes mail from some senders. content: the message itself — its content, an attachment, its size. expired: retried until the provider gave up. routing: no route to the recipient, a loop. unknown: none of these could be read from what was said. More causes may be added; treat one you do not know as unknown.

Allowed:bad_addressmailbox_fullsender_authblockedcontentexpiredroutingunknown
suppressedbooleanrequired

True when the address is dead and went on the workspace's * suppression list, so the next send to it never leaves. Only a hard bounce of a bad_address, or one nothing explains, is. Not SES refusing the send off its own suppression list: that reports bad_address without suppressing.

permanentbooleanrequired

True when the provider classed the bounce as hard — it gave up for good, as SES's Permanent or a 5.x status says. False for a soft one, which the provider also stopped retrying. Not whether the address is dead: a hard bounce can be a blocklist or the sender's own DMARC. Read bounces for that.

reasonstringrequired

The provider's classification: Permanent/General from SES, the status (5.1.1) from a delivery report.

Responses
2XX

Acknowledges the delivery. Anything else, or no answer within 10 seconds, is retried; a Retry-After header is honoured over the standard backoff.

Payload
{
  "id": "string",
  "type": "email.bounced",
  "created_at": "2019-08-24T14:15:22Z",
  "space_id": "string",
  "data": {
    "email_id": "string",
    "message_id": "string",
    "thread_id": "string",
    "domain_id": "string",
    "mailbox_id": "string",
    "suppression_key": "string",
    "recipients": [
      "user@example.com"
    ],
    "bounces": [
      {
        "address": "user@example.com",
        "cause": "bad_address",
        "suppressed": true
      }
    ],
    "permanent": true,
    "reason": "string"
  }
}
Response
Acknowledges the delivery. Anything else, or no answer within 10 seconds, is retried; a `Retry-After` header is honoured over the standard backoff.