Bounces

Built-in Bounce Detection

EmailEngine automatically scans incoming emails for bounce responses. When a bounce is detected, EmailEngine sends a webhook notification. Additionally, when listing emails, any bounce information associated with a specific message is included in the message details as a bounces array.

Note: EmailEngine does not use VERP addresses. Since EmailEngine sends emails via standard channels and not directly, it can only detect bounces that include standard bounce information. Custom, human-readable messages without metadata markers may not be detected. Fortunately, the majority of email servers use standard bounce formats that EmailEngine can process.

Bounce Webhooks

When EmailEngine detects an incoming email, it checks to see if the email is a bounce response. If so, it sends a webhook with the event type messageBounce.

Because EmailEngine cannot immediately identify the original message that triggered the bounce, the webhook payload does not include a "id" field. Instead, the messageId field is provided to help you match the bounce to a message in your system.

An example of a bounce webhook payload:

{
  "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>"
  }
}

Note that some fields might be missing depending on how much information EmailEngine can extract from the bounce response.

Bounces in Message Listings

When listing messages in the Sent Mail folder, EmailEngine checks for bounces associated with each listed message. If a bounce is detected, it is included in the message entry as a bounces array.

Here’s an example message listing that includes bounce information:

{
  "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"
    }
  ]
}

Retrieving Bounce Content

To retrieve the actual contents of a bounce message, you can use the data.bounceMessage value from the webhook payload or the bounces[].message value from the message listing.

For example, to fetch the bounce content for AAAAAQAABWw, use the following curl command:

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

The response will return the full content of the bounce message:

{
  "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
  }
}

Bounce Types

There are various reasons why an email might bounce. EmailEngine identifies these types of bounces.

SoWkIImgAStDuN8iA53GjLDmpKtCp77DIy_CIxLIi4a5yUoua0H1Qe9zGm8GaY0UXavJ0mC5nzAIZDIyaipan9BC_3m5Dw1qQWgwMK1hWKRbfXON9wQdkgJcP9Qb5bMw5XNb5w5OYs51Nhv2RdvHga9HQabHPcenNcCXDjjnEQJcfG2z2W00.png

messageFailed

The SMTP server did not accept the email for delivery.

file.png

messageBounce

The email was accepted by the SMTP server but was later rejected by the recipient's mail server (MX server).