Bounces

EmailEngine regularly scans incoming mail for bounce responses. Whenever a bounce email is detected, EmailEngine sends a webhook notification about that bounce. Additionally, when listing emails and a specific message has generated bounce responses, this information is included in the message details as a bounce array.

EmailEngine can not use VERP addresses. It sends emails via regular channels and not directly by itself, so it can only detect bounces if these responses include any standard bounce information. If it's a super custom, human-readable message without any metadata markers, then EmailEngine is, unfortunately, unable to detect that bounce. The majority of email servers use standard bounce responses that EmailEngine can process.

Whenever EmailEngine detects a new incoming email, it checks if that email might be a bounce response. EmailEngine sends a webhook with the messageBounce event type if it turns out to be the case.

Unfortunately, EmailEngine can not immediately determine the initial message that the bounce was sent as a reply to, so there is no "id" field in the payload. Instead, you have to rely on the included messageId field to match that bounce to a message on your system.

Example bounce webhook payload looks like the following. Beware, though, that some fields might be missing from some webhooks depending on how EmailEngine can parse information out from the bounce.

{
  "account": "account_id",
  "date": "2021-11-28T10:17:29.728Z",
  "event": "messageBounce",
  "data": {
    "bounceMessage": "AAAAAQAABWw",
    "recipient": "failed.recipient@example.com",
    "action": "failed",
    "response": {
      "source": "smtp",
      "message": "550 5.1.1 <failed.recipient@example.com>: Recipient address rejected: User unknown in relay recipient table",
      "status": "5.1.1"
    },
    "mta": "mx.example.com",
    "queueId": "BFC608226A",
    "messageId": "<4dbe4a40f37e9c2ba5b25912bc7c8997@example.com>"
  }
}

When listing messages in the Sent Mail folder, EmailEngine checks for existing bounces for the listed messages and, if found, includes these in the message entry as a bounces array.

Example listing entry with bounce information looks like the following (it's the same message that received the bounce that was used in the webhooks section above):

{
  "id": "AAAAAgAAAZ0",
  "uid": 413,
  "date": "2021-11-28T10:17:27.000Z",
  "size": 839,
  "subject": "Example message",
  "from": {
    "name": "Sender Name",
    "address": "sender@example.com"
  },
  "to": [
    {
      "name": "",
      "address": "failed.recipient@example.com"
    }
  ],
  "messageId": "<4dbe4a40f37e9c2ba5b25912bc7c8997@example.com>",
  "bounces": [
    {
      "message": "AAAAAQAABWw",
      "recipient": "failed.recipient@example.com",
      "action": "failed",
      "response": {
        "message": "550 5.1.1 <failed.recipient@example.com>: Recipient address rejected: User unknown in relay recipient table",
        "status": "5.1.1"
      },
      "date": "2021-11-28T10:17:29.722Z"
    }
  ]
}

If you want to retrieve the actual contents of the bounce, then you can use the data.bounceMessage value from the webhook payload or bounces[].message value from the message listing to fetch the bounce as a regular message. So in the following example, we will be fetching the contents for AAAAAQAABWw listed as the bounce in the examples above.

$ curl "http://localhost:3000/v1/account/ekiri/message/AAAAAQAABWw?textType=*" \
    -H 'Authorization: Bearer d2d438e2a965...'

And the resulting response:

{
  "id": "AAAAAQAABWw",
  "uid": 1388,
  "date": "2021-11-28T10:17:28.000Z",
  "unseen": true,
  "size": 3611,
  "subject": "Undelivered Mail Returned to Sender",
  "from": {
    "name": "Mail Delivery System",
    "address": "MAILER-DAEMON@smtp.example.com"
  },
  "to": [
    {
      "name": "",
      "address": "sender@example.com"
    }
  ],
  "attachments": [
    {
      "id": "AAAAAQAABWwy",
      "contentType": "message/delivery-status",
      "encodedSize": 480,
      "filename": false,
      "embedded": false,
      "inline": false
    },
    {
      "id": "AAAAAQAABWwz",
      "contentType": "message/rfc822",
      "encodedSize": 1437,
      "filename": false,
      "embedded": false,
      "inline": false
    }
  ],
  "messageId": "<20211128101728.144CB82458@smtp.example.com>",
  "text": {
    "plain": "This is the mail system at host smtp.example.com.\n\nI'm sorry to have to inform...",
    "html": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\">\n<html><body style=...",
    "hasMore": false
  }
}