How Do I Troubleshoot Email Bounces and Suppression in Piano Email Manager?

Key Concepts

Bounce Types

Soft Bounce (Temporary Failure)

Common causes:

• Recipient mailbox is full or temporarily inactive.

• Recipient mail server is temporarily down, unreachable, or rate-limiting.

• Temporary policy or filtering decisions (sometimes content-related).

Behavior: The provider may retry delivery for a period (commonly up to approximately 72 hours). If the temporary issue persists, the event may eventually become a permanent failure.

Hard Bounce (Permanent Failure)

Common causes:

• Invalid recipient address or mailbox does not exist.

• Non-existent domain.

• Permanent rejection (including strict policy, authentication failures, or blocks).

Behavior: The message is not retried. The address is typically placed on the Amazon SES suppression list, preventing future delivery attempts until the suppression is removed.

How Amazon SES Suppression Works

Piano uses Amazon SES for the majority of transactional email sends (e.g., login codes, password resets, invitations, and notifications). When SES determines a permanent delivery failure, the recipient address can be placed on the SES account-level suppression list.

What this means:

• Once suppressed, all future emails to that address will not deliver until the address is removed from the suppression list.

• Suppression can also occur due to spam complaints, depending on provider behavior and account configuration.

If you believe an address is valid and suppression is incorrect (e.g., an employee mailbox was temporarily deprovisioned and later restored), the address must be removed from the SES suppression list to resume delivery. See this section for details.

Where to View Bounce Information

Aggregate Reporting in Email Manager

In the Piano Dashboard, navigate to Reports → Email Reporting to view aggregate metrics including:

• Delivered

• Opened

• Clicked

• Soft bounced

• Hard bounced

Limitations:

• The UI is generally aggregate and may not provide recipient-level lists of bounced addresses.

• Detailed bounce reasons are recorded by the underlying provider (Amazon SES), but they may not be exposed directly in the Dashboard.

Recipient-Level Checks (API)

There is no general "list all bounced users" API endpoint. However, you can query per user and filter statuses using:

• /publisher/user/email/list (filter by user uid) - API Documentation

This is useful when you already know the affected user and want to confirm whether sending attempts exist and what status they reached.

Getting Recipient-Level Hard Bounce Lists

If you need a list of individual hard-bounced addresses for transactional emails sent via Email Manager:

• The standard reporting UI is typically aggregate only.

• A custom export may be required (by template and date range), coordinated through your Piano contacts. This may involve additional arrangements.

Troubleshooting Email Manager Delivery Issues

Verify Sender and Template Configuration

Before investigating bounce-specific issues, confirm that the sending configuration is correct:

• The relevant Email Manager template is active and correctly assigned.

• The Master layout and template include a valid From address.

• The From address domain (or sender identity) is verified in Amazon SES.

Check Whether the Recipient Is Suppressed

If a user never receives any transactional emails (login codes, password resets, notifications), the address may be suppressed in Amazon SES.

Signs that an address may be suppressed:

• The user reports receiving no emails at all (not just missing a single email).

• Email Reporting shows the message as hard bounced or not delivered.

Remove an Address from SES Suppression

If you have confirmed that the address is valid and should receive transactional emails again:

1. Correct the underlying cause (e.g., typo in address, invalid domain, mailbox that was temporarily deprovisioned).

2. Request removal from the SES suppression list via Piano Support. Suppression list removal is not available as self-service in the Piano Dashboard.

Address Soft Bounces and Deferrals

Soft bounces and deferrals are usually recipient-side issues and often resolve within approximately 72 hours.

Recommended actions:

• Ask the recipient to check their spam/junk folder and mark the message as Not Spam.

• Ask the recipient (or their IT team) to allowlist your sending domain and address. In some corporate environments, allowlisting sending IPs may also be necessary.

• Avoid resending immediately — this can create duplicate deliveries if the deferred message is eventually delivered successfully.

Content and Security-Gateway Rejections

Some corporate email gateways reject messages containing certain elements (e.g., tracking links) or flagged content. If you see content-related transient rejections:

• Simplify the email content (remove problematic links or elements).

• Test sending again after making changes.

When to Contact Piano Support

Contact Piano Support when you need:

• Removal of an address from the SES suppression list.

• Help confirming backend bounce reasons not shown in the Email Manager UI.

• A custom export of recipient-level hard bounce data (by template and date range).

• Investigation of widespread deliverability issues (domain blocks, IP reputation problems, authentication misconfiguration).

When escalating, include:

• Email template name type (e.g., login code, password reset)

• Approximate send time

• Recipient address(es) affected

• Any available status information from Email Reporting

• Any bounce or error text the recipient's IT team can provide (full email headers are especially useful)

Last updated: June 26, 2026