What Is the Difference Between a Hard and Soft Bounce?
A hard bounce is a permanent rejection for that delivery attempt, such as an invalid mailbox. A soft bounce is a temporary delivery problem, such as a busy server. Read the server’s full reply and the SMTP error reference, because the same broad code can have several causes.
The response to Create Message is an acceptance response with per-recipient
queued, scheduled or error entries. It is not the final delivery state. Check each recipient even when the HTTP request succeeds.
Why Was My Email Suppressed?
A suppression blocks sending to an address for the matching sending domain, or for the applicable account domains. Look up the address and sending domain with List Suppressions or the suppression CLI. Read its reason and expiry instead of assuming every suppression came from a hard bounce. AhaSend can create suppressions from delivery problems or spam complaints. Your application can also create one for an unsubscribe or an internal blocklist. Reasons are readable strings, including caller-supplied text; do not treat them as a fixed enum.Suppression Duration
API-created suppressions do not inherit a default expiry from their reason. Keep unsubscribes and complaints in your own durable recipient preferences too; an expiry must not silently restore permission to send unwanted mail.
When Should I Remove a Suppression?
Remove a suppression only after resolving its cause and confirming that sending is appropriate. For an invalid mailbox, ask the user to correct or verify the address. A complaint or unsubscribe is not a reason to try a different sender domain. Use Delete Suppression for the specific address and domain; clearing the whole list can restart unwanted mail.How Should My Webhook Handler Update State?
Verify the signature, save thewebhook-id delivery header to detect duplicate deliveries, and record the message ID, event type and timestamp. Acknowledge verified unknown event types with 2xx. Keep the event history so a late bounce or repeated notification does not erase useful earlier evidence.
A delivery attempt’s classification is an open string. Values can change as classification improves; keep the original SMTP response and do not reject an entire webhook because a new classification appears. Distinguish webhook delivery retries from the email’s own schedule and expiry.
Test each branch with the sandbox outcomes and local webhook testing. Use the bounce report API to find patterns by recipient domain before changing volume.