> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mailchannels.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handling soft-bounced events

> Learn about the best practices for responding to soft-bounced webhook events.

## 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](/email-api/hard-bounced-events) 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](https://blog.mailchannels.com/understanding-smtp-response-codes/).

## 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

```json theme={null}
{
    "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>"
}
```