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
• Populate the Feedback webhook URL with the location of your webhook
• Optionally add headers to send along with the notification

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