Skip to content

Feedback webhooks

You can choose to have bounce, complaint, and unsubscription notifications delivered via a webhook. This allows you to easily integrate these notifications into your app or service.

Data is delivered as JSON via HTTP POST requests.

Configuring the webhook

  • Open the mail identity you wish to configure
  • Choose Webhook as the Feedback notification type
  • Populate the Feedback webhook URL with the location of your webhook
  • Optionally add headers to send along with the notification

Webhook setup screenshot

Webhook data

Bounces

{
   "notification_type": "bounce",
   "bounce": {
       "reason": "The email account that you tried to reach is over quota",
       "bounce_type": "Soft bounce - Mailbox full",
       "body": "Content-Type: multipart\/report; ...",
       "message_id": "<[email protected]>",
       "envelope_sender_id": "FEDCABC9-8765-4321-0FED-CBA987654321.1",
       "recipient": "[email protected]",
       "original_recipient": "[email protected]",
       "reputation_score": false
   }
}
Field Description
reason When available, the reason provided by the destination mail server
bounce_type Bounces are categorised for convenience. Full list of bounce types and meanings
body The raw bounce data
message_id The ID of the original message
envelope_sender_id The 'user' part of the MAIL FROM address used to send the email. This uniquely identifies the email.
recipient The recipient that generated the bounce. If the mail was automatically forwarded by the original recipient to another address and that forward failed, a bounce may be returned to us, but for the forwarded recipient
original_recipient The original recipient of the message
reputation_score If true, this bounce affects your reputation, and you should consider removing the recipient from your lists

Complaints

{
    "notification_type": "complaint",
    "complaint": {
        "description": "This is an example Abuse Report for an email message received from domain example.com, IP 1.2.3.4, on Wed, 07 Sep 2022 19:04:19 +0000.",
        "report": "Feedback-Type: abuse...",
        "original": "...",
        "message_id": "<[email protected]>",
        "envelope_sender_id": "FEDCABC9-8765-4321-0FED-CBA987654321.1",
        "subject": "Example Abuse Report",
        "received_date": "2022-09-07T14:04:19.426Z",
        "original_recipient": "[email protected]",
        "reputation_score": true
    }
}
Field Description
description The received report description
report The original RFC 5965 message/feedback-report abuse report
original If the abuse report contains the original email, it's included here
message_id The ID of the original message
envelope_sender_id The 'user' part of the MAIL FROM address used to send the email. This uniquely identifies the email.
subject The subject we received the abuse report with
received_date The date we received the abuse report
original_recipient The original recipient of the message
reputation_score If true, this affects your reputation, and you should consider removing the recipient from your lists

Unsubscribe requests

{
  "notification_type": "unsubscribe",
  "unsubscribe": {
    "message_id": "<[email protected]>",
    "envelope_sender_id": "FEDCABC9-8765-4321-0FED-CBA987654321.1",
    "subject": "Hello world",
    "received_date": "2023-11-28T10:17:01.442Z",
    "original_recipient": "[email protected]",
    "list_id": "<testing.123.example.com>"
  }
}
Field Description
message_id The ID of the original message
envelope_sender_id The 'user' part of the MAIL FROM address used to send the email. This uniquely identifies the email.
subject The subject sent with the original message
received_date The date the unsubscription request was received
original_recipient The original message recipient
list_id Any List-Id header value that was supplied when the message was originally sent