Webhook event · Delivery

failed

Sent when we give up on an email after its retries run out.

i

Delivered as a signed POST to your webhook URL. See Setup & Events for how to verify the signature.

Payload

// Rate-limit cycles ran out
{
  "event": "failed",
  "emailId": "3f2a1b4c-8e9d-4f7a-b2c3-1a2b3c4d5e6f",
  "timestamp": "2026-10-23T04:32:10.000Z",
  "data": {
    "recipientEmail": "user@example.com",
    "fromAddress": "hello@yourdomain.com",
    "reason": "Max retries (4) exceeded: 421 4.7.28 Our system has detected an unusual rate of mail from your IP"
  }
}
!

You may also get bounced. When temporary errors, connection failures or greylisting run out of retries, the email is also logged as a bounce and a bounced event is sent. When the rate-limit cycles run out, only failed is sent.

i

Control how long we keep trying. Set retryRateLimited, retryUnavailable and retryUnavailableSeconds per email.

Delivery options →

Field reference

  • event

    Fixed value: "failed".

  • emailId

    ID of the email, the same one returned by POST /send.

  • timestamp

    When the event happened (ISO 8601, UTC).

  • data.recipientEmail

    Recipient email address.

  • data.fromAddress

    Sender email address.

  • data.reason

    Why we gave up. "Max retries (N) exceeded" means the rate-limit cycles ran out; otherwise it is the last answer from the receiving server.

  • data.notSent

    Only present (true) when the email was never sent because of your account: no credits left, a blocked or restricted account, a sender domain on Spamhaus or without DKIM, or an invalid From. It is not a bounce. The log shows status not_sent and data.reason has the exact cause.