Deliverability
Bounces, complaints and suppressions
Why some addresses stop receiving your email, and how to manage the list.
NeedsAny accountTest keys work as soon as you sign up. Nothing is delivered.
When an address bounces hard or its owner marks your email as spam, we add it to your suppression list and stop sending to it. Sending to a suppressed address skips that recipient and records an email.suppressed event; the rest of the email still goes.
| Reason | Added when | Covers |
|---|---|---|
bounce | A hard bounce (the address doesn't exist), or repeated soft bounces | Every stream |
complaint | The recipient marked your email as spam | Every stream |
unsubscribe | The recipient unsubscribed | The marketing stream |
manual | You added it | The stream you chose, or every stream |
invalid | The address can't receive email | Every stream |
Manage the list
// Is an address suppressed?
const { data } = await pm.suppressions.list({ address: "ada@example.com" });
// Stop sending to an address
await pm.suppressions.create({ address: "ada@example.com" });
// Allow it again (not for complaints)
await pm.suppressions.remove(data[0].id);Complaint suppressions can't be removed through the API: the person said they didn't want your email. Contact support if you believe it was a mistake.
Keep your own records in step
Listen for email.bounced and email.complained webhooks and mark the address in your own database, so your app stops trying to email it:
if (event.type === "email.bounced" && event.data.bounce.type === "hard") await db.user.update({ where: { email: event.data.to! }, data: { emailInvalid: true } });
if (event.type === "email.complained") await db.user.update({ where: { email: event.data.to! }, data: { marketingOptIn: false } });Was this page helpful?