Tracking bounces

You can use EmailEngine to track bounced emails on an IMAP account. In fact it is quite easy to do as all the heavy-lifting is already done by EmailEngine in the background.

This post is going to be short as tracking bounced emails with EmailEngine is actually quite easy.

EmailEngine provides an easy to use REST API over IMAP and SMTP accounts. Whenever you list emails in the "Sent Mail" folder on such an IMAP account and the resulting list includes an email that was bounced then the bounce information is included as part of the message details. You also get a reference to the original bounce email in case you want to inspect it.

Step 1. List sent emails

List emails normally. We are using INBOX.Sent folder which is a common Sent Mail box in Courier.

$ curl -X "GET" \
  "http://127.0.0.1:3000/v1/account/example/messages?path=INBOX.Sent&page=0&pageSize=20"

Step 2. Look for the bounce info

If a message was detected as bounced, there should be a bounces property in the message details. There is a separate entry for every bounced recipient.

{
  "total": 363,
  "page": 0,
  "pages": 19,
  "messages": [
    {
      "id": "AAAAAgAAAWw",
      "uid": 364,
      "date": "2021-08-05T13:30:58.000Z",
      ...
      "bounces": [
        {
          "message": "AAAAAQAABQ0",
          "recipient": "user@example.com",
          "action": "failed",
          "response": {
            "message": "550 5.1.1 No such user",
            "status": "5.1.1"
          },
          "date": "2021-08-05T13:31:00.838Z"
        }
      ]
    }
  ]
}

Bounce information includes the recipient that failed (hhhhh@ethereal.email), SMTP server response (550 5.1.1 No such user) if available or a general error message and the bounce email ID (AAAAAQAABQ0). If you'd like then you could use that ID to fetch the contents of the original bounce response.

How does it work?

EmailEngine checks all incoming emails in the IMAP account and if an email looks like a bounce then EmailEngine parses bounce information out of it and tries to match it with an email in the Sent Mail folder.

Well, that's about it. As I stated in the beginning, this was going to be a short post.