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 (string) or postal adress (object)
],
"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.
| Field | Description |
|---|---|
recipients | The intended recipients of the message. This is array of either email addresses, a phone number or a postal address |
error | An 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 Code | Description |
|---|---|
INVALID_MOBILE_NUMBER | the recipient’s mobile number is invalid |
INVALID_EMAIL_ADDRESS | the recipient’s email address is invalid |
INVALID_POSTAL_ADDRESS | the recipient postal address is invalid |
RENDER_ERROR
| Reason Code | Description |
|---|---|
PLACEHOLDER_ERROR | Missing data to resolve the placeholders in the message content |
SNIPPET_ERROR | Error resolving snippets in the template. |
QRBILL_ERROR | Error when rendering the QRBill component. |
INTERNAL_ERROR | Failure when building the message content. |
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_GENERAL | The recipient's email provider sent a hard bounce message, but didn't specify the reason for the hard bounce |
BOUNCE_PERMANENT_ON_SUPPRESSION_LIST | The 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_FULL | The 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_LARGE | The recipient's email provider replied with a bounce message because the message sent was too large. |
BOUNCE_TRANSIENT_CONTENT_REJECTED | The recipient's email provider sent a bounce message because the message sent contained content that the provider doesn't allow. |
BOUNCE_TRANSIENT_ATTACHMENT_REJECTED | The 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_REJECTED | Message was rejected by the recipient’s service provider |
SMS_NOT_DELIVERED | Message could not be delivered. For example due to a non-existing mobile number |
SMS_EXPIRED | Message 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 Code | Description |
|---|---|
INVALID_CLAIM | This 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_EXCEEDED | This error indicates that the dedicated timeframe for sending a message has elapsed |
PROVIDER_ERROR | This is an error for when the message sending provider is unavailable |
CONFIGURATION_ERROR
| Reason Code | Description |
|---|---|
COMMUNICATION_PROVIDER_NOT_CONFIGURED | The communication provider configuration is missing for the intended channel |
INVALID_SENDER_ERROR | Indicates 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
},
}
SEND_ERROR
{
"details": {
"message": "some error occured",
"smtpCode": "200", // Email only, see more: https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes
},
}