Skip to main content

​
What is a soft-bounced event?

A soft-bounced event is generated when a recipient’s server temporarily rejects an email (returning a 4xx SMTP status code). The event data includes the specific reason for the bounce, for example, if there’s a connection timeout or a full mailbox. MailChannels will automatically retry delivery for soft-bounced messages for up to six hours, or until the message is successfully delivered. If the message cannot be delivered within this retry window, it is treated as a permanent failure and won’t be retried. You will receive a hard-bounced event for the message if this happens. Note that you may receive multiple soft-bounced events for a single message. The retry period may change in the future.

​
What to do if you receive a soft-bounced event

If you receive a soft-bounced event, you most likely don’t need to take any action, as MailChannels will automatically retry delivery for soft-bounced messages. However, you can investigate the reason for the bounce using the status code and reason fields. For more in-depth information on SMTP response codes and their meanings, see our SMTP response code documentation.

​
Fields for soft-bounced events

  • email: Sender email address.
  • customer_handle: Your account ID.
  • timestamp: Unix timestamp of the event.
  • event: The type of event, soft-bounced in this case.
  • recipients: List of recipient email addresses that couldn’t receive the message.
  • status: The SMTP status code received for the soft bounce.
  • reason: A human-readable explanation of why the message bounced.
  • campaign_id (optional): The campaign ID associated with the message, if applicable.
  • request_id (optional): A unique identifier generated to track the original HTTP request. This will be blank if the message is sent via SMTP instead of the API.
  • smtp_id: A unique identifier used to track the message, matching the Message-Id header.

​
Example soft-bounced event

{
    "email": "sender@example.com",
    "customer_handle": "examplecorp",
    "timestamp": 1700000000,
    "event": "soft-bounced",
    "recipients": [
        "recipient@example.net",
        "recipient2@example.net"
    ],
    "status": "421",
    "reason": "Service not available",
    "campaign_id": "spring-sale-2026",
    "request_id": "4b06083a23724f279c8d11a370e641f8",
    "smtp_id": "<c8d0c0e8412a4e9e9687814d9a7c67da@example.com>"
}