Hard bounce vs soft bounce: what each one means and what to do

A hard bounce is a permanent email delivery failure. A soft bounce is temporary, so a later attempt may work. Check the bounce reason before you retry or stop sending to the address.

What is a hard bounce?

A typo or a closed account can leave you sending to an address that no longer exists. The receiving server can reject it with a reply like this:

550 5.1.1 user unknown

Code 5.1.1 means the mailbox does not exist. Sending the same message again will not fix that address.

Other 5.X.X failures can involve authentication, message content, or a receiving server's policy. The address may still be valid. RFC 3463 says a permanent failure needs a change to the message or destination. Read the full error before you decide what to fix.

What is a soft bounce?

A full mailbox, a busy server, or a temporary sending limit can cause a soft bounce. The server may accept the message later. A temporary error alone does not confirm that the address is valid.

The 4.X.X codes describe temporary failures. For example, 4.2.2 means the mailbox is full. RFC 3463 says a later send may succeed once the temporary problem clears.

Hard bounce vs soft bounce: key differences

	Hard bounce	Soft bounce
SMTP class	5.X.X	4.X.X
Example	5.1.1 mailbox does not exist	4.2.2 mailbox full
Will a later send work?	Not without fixing the cause	It may, once the temporary problem clears
What to do	Stop automatic retries and read the error	Check existing retries, then apply your retry limit

What to do after each bounce

After a hard bounce, stop automatic retries and read the error. If the mailbox does not exist, add the address to your suppression list. Ask the person for a correct address through another channel if you still need to reach them.

If the error names an authentication or policy problem, fix that cause before sending again. Do not switch senders to get around a block. If your sending service suppresses the address, resolve the cause before removing that suppression.

After a soft bounce, check whether your sending service still plans to retry the message. If it does, let those attempts finish before you submit another copy. Then track these details for each address:

• The latest bounce reason.
• The number of messages that failed in a row.
• The time since the first failure.

Set a limit for repeated failures and a time window that fits your sending frequency. For example, an app could pause sends after three consecutive soft bounces within seven days. This is an example policy, not a universal email rule. Use your sending service's retry guidance to choose your own limit.

Gmail's sender guidelines suggest unsubscribing recipients after multiple bounced messages. If many messages bounce at once, reduce your sending volume while you check the cause. A bad import or a broken form can fill a list with invalid addresses quickly.

What is an email suppression list?

An email suppression list holds the addresses you must not send to. Your sending system checks it before every send and blocks a match.

Three events usually add an address:

• a hard bounce;
• a spam complaint (the recipient clicked "Report spam");
• an unsubscribe.

Keep this list in one place so every part of your app uses the same exclusions. Add addresses automatically when these events arrive. A manual update can miss an opt-out or let another message through first.

How the List-Unsubscribe header enables one-click unsubscribe

A spam complaint means someone marked your message as spam. Gmail and Yahoo ask bulk senders to keep the spam rate below 0.3%. Gmail recommends staying below 0.1%.

Give people an easy way to unsubscribe instead of reporting spam. Gmail requires one-click unsubscribe for marketing and subscription messages from bulk senders. Its bulk sender rules cover about 5,000 or more messages a day to personal Gmail accounts. These messages also need a visible unsubscribe link in the body. Yahoo's sender requirements also cover easy unsubscribe and require senders to honor requests within two days.

RFC 8058 defines one-click unsubscribe with two headers:

List-Unsubscribe: <https://example.com/unsubscribe?token=abc123>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

The message needs a valid DKIM signature that covers both headers. The mail app can then offer an Unsubscribe button. When the recipient clicks it, the mail provider sends a POST to that URL. Your server records the opt-out without asking the recipient to open a page.

Test the POST with the body List-Unsubscribe=One-Click, not only a browser visit to the link. A page that loads correctly does not prove the one-click request works.

How Hail handles bounces

Hail automatically blocks future sends to addresses that hard bounce or report your email as spam. This applies to email you send through its API or an agent. The email delivery docs explain how suppression works.

• A hard bounce or a spam complaint adds the recipient to your organization's suppression list. A soft bounce is recorded as an event only.
• An email to exactly one recipient carries both one-click unsubscribe headers. An unsubscribe adds the address to the list. Messages with multiple recipients carry neither header.
• The next send to a suppressed address returns 403 and names the reason:

{ "detail": "recipient 'bob@example.com' is suppressed (hard_bounce)" }

The reasons are hard_bounce, spam_complaint, and recipient_unsubscribed. One suppressed address in to, cc, or bcc blocks the whole send.

Subscribe to the email.bounced webhook to receive bounce events in your app. Read data.detail.hard to distinguish hard bounces from soft bounces. The data.detail.diagnostic_code field carries the server's reply, such as smtp; 550 5.1.1 user unknown. Record the reason and event time to track repeated soft bounces.

List suppressed addresses with the first command below. Remove an address only after you resolve its suppression reason. For an unsubscribe, first confirm that the person wants mail again.

hail email suppressions list
hail email suppressions delete bob@example.com

Bounce handling checklist

• Stop automatic retries after a hard bounce and check the cause.
• Suppress invalid addresses and fix authentication or policy errors before sending again.
• Track soft bounces and pause sends when your failure limit is reached.
• Add spam complaints and unsubscribes to the same suppression list.
• Check the suppression list before every send, in code, not by hand.
• Send List-Unsubscribe and List-Unsubscribe-Post, and test the POST.
• Watch your spam rate in Google Postmaster Tools.
• When many messages bounce at once, slow down and look for a bad import.

Check your domain with the email deliverability checker. Read the DMARC policy guide if the error points to authentication. Then send a test email through the API to an inbox you control and read its events.