Skip to main content

Bounce Insights Introduction

· 7 min read
Caleb Lucas

In the world of digital communication, understanding why an email or SMS fails to reach its intended recipient is crucial. The bounce reason, indicating the cause behind the non-delivery, serves as a diagnostic tool, unravelling potential issues such as invalid addresses, server problems, or content-related concerns. By delving into these bounce reasons, you can enhance your delivery rates, maintain a healthy email sender reputation, and ensure that your messages reach the right inbox, fostering effective communication.

Our latest feature development addresses these concerns:

Whenever an email, SMS bounces, i.e. a message could not be successfully delivered to your customers mailbox, mobile devices, we provide you with the reason for this. The failures could be occuring:

  • on the recipients side; from the corresponding email or mobile provider.
  • during the message preparation; in our own system.

In either case, we enrich the MESSAGE_NOT_DELIVERED with error codes to help you understand what went wrong.


What to expect?

At the moment, when a message fails to deliver for any reason, a webhook for MESSAGE_NOT_DELIVERED, with the following payload is sent:

{
"type": "MESSAGE_NOT_DELIVERED",
"date": "2018-08-24T11:32:23Z",
"eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
"source": "ESCALATION",

"claim": {
"id": 54321,
"merchantId": 1,
"referenceNumber": "REF-123",
"customerNumber": "12345",

"communication": {
"channel": "SMS",
"reference": "a6590eb9-497a-4a7f-b5df-xxxxxxxxxxxx"
}
}
}

In order to enable insights into the failure, we're enhancing the MESSAGE_NOT_DELIVERED event with new fields:

{
"type": "MESSAGE_NOT_DELIVERED",
"date": "2018-08-24T11:32:23Z",
"eventId": "a1daaeb5-7a71-4df1-9278-c635110e3033",
"source": "ESCALATION",

"claim": {
"id": 54321,
"merchantId": 1,
"referenceNumber": "REF-123",
"customerNumber": "12345",

"communication": {
"channel": "SMS/EMAIL",
"reference": "a6590eb9-497a-4a7f-b5df-xxxxxxxxxxxx",
"recipients": [
// array of recipient - email, sms or postal adress objects
],
"error": {
"type": "<error type>",
"reasonCode": "<error reason>",
"details": {
"message": "some message",
"smtpCode": 200, //Email Only. More codes: https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes
...
}
},
}
}
}

What each of the new fields mean

We introduce recipients and error fields on the claim.communication object.

FieldDescription
recipientsThe intended recipients of the message. This is array of either email addresses, phone numbers or a postal address objects
errorAn object containing information on the issue that occurred when we tried to send the message

Let's look at each of the fields in the error object:

Error Type - type

This field is used to group different types of errors. It helps you understand what kind of failure happened on a higher level.

The list of error types to expect are:

CONTACT_ERROR

Bad contact data (ex. invalid email/phone number/postal address)

RENDER_ERROR

Errors indicating that we encountered some issues when we tried to render the message’s content. For example:

  • Missing data to resolve placeholders
  • Error resolving text snippets
  • Missing attachment, etc.

SEND_ERROR

This error type occurs when there are failures during message handover to provider (SES, IDM, etc). It could also contain bounces occurring after handover to the provider - for example, a non-existent email address.

CONFIGURATION_ERROR

Configuration issues that need to be fixed before a message can be sent. For example:

  • Missing communication provider configuration
  • Missing merchant details

Error Reason Code - reasonCode

This field expands on the error type field. It aims to be an API friendly enumeration while delving into the cause of the failure. Now, let’s look at the set of reason codes to expect for each error type.

CONTACT_ERROR

Reason CodeDescription
INVALID_MOBILE_NUMBERthe recipient’s mobile number is invalid
INVALID_EMAIL_ADDRESSthe recipient’s email address is invalid
INVALID_POSTAL_ADDRESSthe recipient postal address is invalid

RENDER_ERROR

Reason CodeDescription
PLACEHOLDER_ERRORMissing data to resolve the placeholders in the message content
SNIPPET_ERRORError resolving snippets in the template.
QRBILL_ERRORError when rendering the QRBill component.
QR_EPC_ERRORError when rendering the QREpc component.
ATTACHMENTS_ERRORError when processing attachments.

SEND_ERROR

For EMAIL:

For emails, SEND_ERRORs are bounces. There are 2 possible kinds of bounces - Permanent and Transient. Permanent bounces will not be retried, while Transient bounces will.

Permanent bounces:

Permanent bounces are in a terminal state. The email address has been determined to be unreachable. Here are the delivery failure codes:

Reason Code (for emails)Description
BOUNCE_PERMANENT_GENERALThe recipient's email provider sent a hard bounce message, but didn't specify the reason for the hard bounce
BOUNCE_PERMANENT_ON_SUPPRESSION_LISTThe email address in our internal suppression list due to a previous message that bounced

Transient bounces:

Transient bounces are temporary. There will be subsequent attempts to deliver the email to the recipient.

Reason Code (for emails)Description
BOUNCE_TRANSIENT_MBX_FULLThe recipient’s mailbox is full. If the recipient adds storage or clears emails from their account, the email server may accept during a retry
BOUNCE_TRANSIENT_MESSAGE_TOO_LARGEThe recipient's email provider replied with a bounce message because the message sent was too large.
BOUNCE_TRANSIENT_CONTENT_REJECTEDThe recipient's email provider sent a bounce message because the message sent contained content that the provider doesn't allow.
BOUNCE_TRANSIENT_ATTACHMENT_REJECTEDThe recipient's email provider sent a bounce message because the message contained an unacceptable attachment.

For SMS:

Reason codes for SMS are essentially message delivery failure codes:

Reason Code (for sms)Description
SMS_REJECTEDMessage was rejected by the recipient’s service provider
SMS_NOT_DELIVEREDMessage could not be delivered. For example due to a non-existing mobile number
SMS_EXPIREDMessage could not be delivered by the recipient’s service provider in time (for example, due to out of coverage, switched off etc.)

Reason codes shared accross all channels:

Reason CodeDescription
INVALID_CLAIMThis could result due to invalid data in the claim. For example - the country code / country fields are invalid and a letter couldn’t be rendered
DEADLINE_EXCEEDEDThis error indicates that the dedicated timeframe for sending a message has elapsed
PROVIDER_ERRORThis is an error for when the message sending provider is unavailable

CONFIGURATION_ERROR

Reason CodeDescription
COMMUNICATION_PROVIDER_NOT_CONFIGUREDThe communication provider configuration is missing for the intended channel
INVALID_SENDER_ERRORIndicates that there are values missing in the merchant address on behalf of which the message is being sent

Error Details - details

The details field is optional. The following error types include the details field:

CONTACT_ERROR

{
"details": {
"invalidValues": {
"phone": "<bad phone>"
}
}
}

``

RENDER_ERROR

{
"details": {
"snippets": ["snippet-slug"], // only for SNIPPET_ERROR
"placeholders": ["somePlaceholder"] // for PLACEHOLDER_ERROR | QRBILL_ERROR | QR_EPC_ERROR
}
}

SEND_ERROR

{
"details": {
"message": "some error occured",
"smtpCode": "200" // Email only, see more: https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes
}
}