Bounces and suppressions

Bounces

An email bounces when the recipient's mail server refuses it for good: the address or its domain doesn't exist, or the server rejects the email permanently. The recipient's status becomes bounced, you get an email.bounced webhook, and the address goes on your suppression list.

A bounce can also arrive later. Some servers accept an email first and send a bounce message afterwards, so a delivered recipient can still become bounced.

Temporary problems, such as a full mailbox or a busy server, aren't bounces. We keep trying for up to 24 hours. If the email still isn't accepted, the recipient's status becomes failed with the reason expired, and the address is not suppressed.

Complaints

A complaint means the recipient marked your email as spam. The recipient's status becomes complained, you get an email.complained webhook, and the address goes on your suppression list.

We only hear about complaints from mailbox providers that report them to senders, and not all of them do. So a low complaint count doesn't prove that nobody minds your email.

Sending to a suppressed address

You don't have to filter your recipients yourself. When you send to an address on your suppression list, the request still succeeds and the other recipients get the email as usual. The suppressed address is skipped:

• its status becomes failed, with a failed event whose reason is suppressed,
• you get an email.failed webhook,
• it doesn't count towards your monthly allowance.

{
  "type": "email.failed",
  "created_at": "2026-10-09T09:14:03Z",
  "data": {
    "email_id": "em_01JA2Q8ZK4T9W6",
    "recipient": "old-address@example.com",
    "from": "Acme <hello@acme.com>",
    "subject": "Your order has shipped",
    "tags": [{ "name": "category", "value": "shipping" }],
    "reason": "suppressed",
    "message": "The address is on your suppression list."
  }
}

Your suppression list

Each Email API plan has one suppression list, shared by all of its sending domains. Addresses are compared without regard to case, and they stay on the list until you remove them. To see the list:

curl https://services.my-beast.com/mail/api/email/v1/suppressions \
  -H "Authorization: Bearer $MYBEAST_API_KEY"

Each entry says why the address is there (bounced or complained) and which email caused it. See the API reference for every field.

Removing an address

Remove an address only when you know it works again and its owner wants your email. For example:

• the recipient tells you their mailbox exists again, after it bounced,
• someone who marked your email as spam asks to receive it again.

curl -X DELETE https://services.my-beast.com/mail/api/email/v1/suppressions/old-address%40example.com \
  -H "Authorization: Bearer $MYBEAST_API_KEY"

Keeping bounces low

• Confirm new addresses, for example with a link in a welcome email, before you rely on them.
• Listen for email.bounced and email.complained webhooks, and mark those addresses in your own database too.
• Only send to people who asked for your email. Never use bought or rented lists.
• For email people can opt out of, add a List-Unsubscribe header and honour unsubscribes within 7 days.