Troubleshooting the email channel

Verify that logging is turned on to assist in identifying the cause of failure. For more information on logging, see Monitoring and logging and Email events.

Rendering issues

• When using an email template, a rendering failure occurs when message variables are missing, formatted incorrectly, or when there is a mismatch between message variables and endpoint data causing emails to fail during sending.

• To identify rendering failures, review the Amazon SES CloudWatch metric RenderingFailure during the time frame that the campaign ran. Rendering failures appear in the Amazon Pinpoint event logs as _email.rendering_failure events.

• To resolve the issue, verify that all message variables have a corresponding endpoint attribute present and are in the correct format. For more information, see Adding personalized content to message templates.

• Configure default values for all message variables in the template to avoid rendering failures when an attribute is missing for an endpoint.

• Test running the campaign without the template to confirm whether endpoints can successfully receive messages. This action can help confirm that the issue is related to template variables.

Bounce status

Solution for soft bounce

• A soft bounce occurs because of a temporary failure and will appear under the _email.softbounce event type in the logs. Amazon Pinpoint handles soft bounces by attempting to redeliver the soft bounced emails for a specified period of time.

• A soft bounce can occur in the following scenarios:

  • The recipient mailbox is full.

  • The recipient mailbox is temporarily unavailable.

  • The server limits are exceeded.

  • The server is overloaded.

• The specific error codes related to soft bounces are 421, 450, 451, or 452. For the descriptions of these error codes, see Simple Mail Transfer Protocol (SMTP) Enhanced Status Codes Registry. The smtp_response in the logs provide the error code for the bounce event.

Solution for hard bounce

• A hard bounce is a persistent delivery failure that appears under the _email.hardbounce event type in the logs. These failures aren't retried.

• A hard bounce can occur in the following scenarios:

  • The email address doesn’t exist.

  • The domain name doesn’t exist.

  • The recipient’s email server has blocked the emails.

  • The email address is on the account suppression list.

• Monitor the number of hard bounces in your project and remove hard-bouncing email addresses from your recipient lists. Hard bounces can negatively impact your sending reputation and the deliverability of your email message. For more information, review the best practices on Bounces.