Suppressions
A suppression is a recipient address Shipmail refuses to send to. Addresses land on the list automatically when a message to them permanently bounces, keeps soft-bouncing or is reported as spam. The list belongs to your organization, so one team's bounces never affect another's. Each entry has a scope: most block every send, and a complaint blocks only the kind of email it was about.
The list protects your sending reputation. Mailbox providers track how much of your mail hits dead addresses or gets reported as spam. Sending again to an address that already rejected you is the fastest way to get your domain filtered, and blocking the second try costs far less than recovering from that.
Last updated
The suppression object
{
"object": "suppression",
"email_address": "user@example.com",
"reason": "hard_bounce",
"scope": "all",
"expires_at": null,
"created_at": "2026-05-13T10:00:00.000Z",
"source": "suppression"
}| Field | Type | Description |
|---|---|---|
| email_address | string | Suppressed recipient email address. |
| reason | string | One of hard_bounce, soft_bounce, complaint, manual, or unsubscribe for a newsletter opt-out. |
| scope | string | all blocks every send. marketing blocks newsletters, transactional email from application senders and mailbox email sent from a mailbox. |
| expires_at | string or null | When the entry stops blocking sends. Null when it is permanent. |
| created_at | string | ISO 8601 timestamp. |
| source | string | suppression, an address-health entry, or newsletter_optout, a reader who unsubscribed from your newsletters. |
| newsletter_id | string or null | Opt-outs only. The newsletter the reader unsubscribed from, when known. |
| test_send | boolean | Opt-outs only. True when the reader unsubscribed from a test send. |
How addresses get suppressed
Shipmail adds suppressions on its own when AWS SES reports a bounce or a complaint for a message you sent. A delivery delay or a single soft bounce adds nothing, so one full mailbox or a temporarily unreachable server will not cost you a recipient.
hard_bouncemeans SES reported a permanent bounce. The address does not exist or the receiving server refuses it outright. Scopeall, permanent.soft_bouncemeans the address soft-bounced 3 times in 14 days because its mailbox was full or its server failed temporarily. Shipmail pauses it for 30 days, soexpires_atis set, and sends resume on their own after that. If it reaches 3 soft bounces again after a pause has ended, the second entry is permanent. Bounces caused by the message itself (too large, content or attachment rejected) never count. Scopeall.complaintmeans the recipient marked your message as spam. Their provider told SES, and SES told Shipmail. Treat these as permanent. A complaint stops only the kind of email it was about. About a newsletter it has scopemarketing, about an application sender's emailtransactional, and about email sent from a mailboxmailbox. So a person who reported a newsletter still gets receipts and password resets, and one who reported a cold email from a mailbox still gets your sign-in links.manualmeans someone added the address deliberately, throughPOST /v1/suppressionsor by importing a suppression list into an audience. An import uses scopeall; the API takes the scope you pass.
Addresses are normalized to lowercase and trimmed before they are stored and before every check, so User@Example.com and user@example.com are the same entry. An address has one entry. A new event never narrows it: an event that blocks every send widens a marketing entry to all, so do complaints about two different kinds of email, and a permanent event ends a pause by making it permanent. An expired entry blocks nothing and the next event replaces it with a new created_at.
What a blocked send returns
Every send path checks the list first: the messages API, the inbox, assistant replies, automation sends and newsletters. Newsletters honour every active entry; every other send honours only all entries. If any recipient across to, cc, or bcc is blocked, the whole send is rejected before it reaches SES and no partial delivery happens.
{
"error": {
"type": "validation_error",
"message": "The following recipients are on your suppression list: user@example.com. Remove them from the suppression list to send again.",
"details": [
{
"field": "recipients",
"message": "user@example.com is suppressed because of a hard bounce.",
"code": "recipient_suppressed"
}
]
}
}Match on details[].code === "recipient_suppressed" rather than the message string, and use the field value to point the user at the offending recipient input. Blocked attempts are recorded, so they still appear in your delivery history with a suppressed status.
A transactional sender with Refuse temporary email addresses turned on refuses a send to a throwaway email domain in the same shape, with details[].code set to recipient_disposable. That check also runs in test mode.
Sends made with mode: "test" skip the check, so you can test the send path without building a suppression list first.
List suppressions
/v1/suppressionsScope: suppressions:read. Supports pagination with cursor and limit. Pass scope=all, scope=marketing, scope=transactional or scope=mailbox to list one scope, and reason (hard_bounce, complaint, manual, soft_bounce or unsubscribe) to list one reason. Expired entries stay in the list with their expires_at until an event replaces them or you remove them.
The list also holds organization-wide newsletter opt-outs, so it shows everyone no newsletter of yours will reach, in any audience. A reader who unsubscribes from one audience through a newsletter's link is not listed: they are unsubscribed in that audience and still get your others. An opt-out has source: "newsletter_optout", reason: "unsubscribe", scope: "marketing" and no expiry. Both kinds come newest first in one list. A cursor from before opt-outs were listed is rejected with 422; start again without it.
{
"data": [
{
"object": "suppression",
"email_address": "user@example.com",
"reason": "hard_bounce",
"scope": "all",
"expires_at": null,
"created_at": "2026-05-13T10:00:00.000Z",
"source": "suppression"
},
{
"object": "suppression",
"email_address": "reader@example.com",
"reason": "complaint",
"scope": "marketing",
"expires_at": null,
"created_at": "2026-05-12T09:00:00.000Z",
"source": "suppression"
},
{
"object": "suppression",
"email_address": "former-reader@example.com",
"reason": "unsubscribe",
"scope": "marketing",
"expires_at": null,
"created_at": "2026-05-11T09:00:00.000Z",
"source": "newsletter_optout",
"newsletter_id": "nws_abc123",
"test_send": false
}
],
"pagination": {
"next_cursor": null,
"has_more": false,
"limit": 25
}
}Add a suppression
/v1/suppressionsScope: suppressions:write. Adds a manual entry, for example when someone asks you by reply to stop writing to them. Pass scope: "marketing" to stop newsletters only; the default is all.
{
"email": "person@example.com",
"scope": "all"
}Returns 201 with the new entry, with source: "suppression". If an active entry already covers the address, it returns 200 with that entry and applies the rules above: all widens a marketing entry, an active soft-bounce pause becomes a permanent manual entry, and a permanent entry stays as it is. An expired entry is replaced and returns 201. Sending the same request twice changes nothing the second time. An invalid address or scope returns 400. Additions are written to your audit log.
Remove a suppression
/v1/suppressions/:emailScope: suppressions:write. Removes a suppressed address after you have confirmed that sending is safe again.
It removes only the address-health entry. A newsletter opt-out is the reader's consent, so it stays until you lift it with fresh consent, as described in Lift a newsletter opt-out.
- Only a suppression:
204. - A suppression and an opt-out: the suppression is removed and the answer is
200with the body below, because newsletters stay blocked. - Only an opt-out:
409witherror.type: "conflict"and a detail withcode: "consent_opt_out"on theemailfield. - Neither:
404.
{
"object": "suppression_removal",
"email_address": "user@example.com",
"removed": true,
"newsletter_optout_remains": true,
"message": "The suppression was removed. The address still has a newsletter opt-out, so newsletters stay blocked until the reader is resubscribed with fresh consent."
}The email is taken from the path, so URL-encode it: DELETE /v1/suppressions/user%40example.com. Removals are written to your audit log with the reason the address was originally suppressed.
Remove several suppressions
/v1/suppressions/batch-removeScope: suppressions:write. Removes up to 500 addresses in one call. Each address is trimmed and lowercased, duplicates count once, and each one is removed exactly as the single remove does it, with its own audit log entry.
curl -X POST https://shipmail.to/api/v1/suppressions/batch-remove \
-H "Authorization: Bearer sm_live_..." \
-H "Content-Type: application/json" \
-d '{"emails": ["user@example.com", "reader@example.com"]}'Returns 200 with one result per address, in the order you sent them. newsletter_optout_remains is true when the address has a newsletter opt-out, which is never removed here.
{
"results": [
{
"email_address": "user@example.com",
"outcome": "removed",
"newsletter_optout_remains": false
},
{
"email_address": "reader@example.com",
"outcome": "skipped_consent_opt_out",
"newsletter_optout_remains": true
}
]
}removed: the suppression was removed.not_found: the address had neither a suppression nor an opt-out.skipped_consent_opt_out: the address only has a newsletter opt-out. Lift it with fresh consent instead.failed: something went wrong on that address. The others still ran, so retry only the failed ones.
An empty list, more than 500 addresses or an invalid address returns 422 and removes nothing.
Lift a newsletter opt-out
/v1/newsletter-opt-outs/:email/resubscribeScope: audiences:write. Lifts the organization-wide newsletter opt-out of an address once the reader has opted in again, including an address that is in no audience. Send consent_source, where and how they opted in, as a subscriber resubscribe does. Shipmail keeps it with the time and the opt-out it replaced, and writes the lift to your audit log.
POST /v1/newsletter-opt-outs/reader%40example.com/resubscribe
{ "consent_source": "Replied to ask to rejoin, 9 November 2026" }
{
"object": "newsletter_opt_out_lift",
"email_address": "reader@example.com",
"consent_source": "Replied to ask to rejoin, 9 November 2026",
"consent_attested_at": "2026-11-09T10:00:00.000Z",
"opted_out_at": "2026-10-01T08:00:00.000Z",
"newsletter_id": "nws_abc123"
}- Audience statuses do not change. A subscriber who unsubscribed stays unsubscribed in that audience; resubscribe them there with
POST /v1/audiences/:id/subscribers/:subscriber_id/resubscribe. That resubscribe also lifts the opt-out, but for that audience only: the subscriber becomes unsubscribed in each other audience where they were still subscribed. - A bounce, complaint or manual suppression that blocks newsletters answers
409. Remove it first. - An address without an opt-out answers
404. A key limited to some audiences gets403, because the opt-out covers every audience.
When removal is safe
Removing a suppression tells Shipmail the address is worth trying again. If you are wrong about that, your domain reputation pays for it.
- Safe: the recipient told you through another channel that the mailbox is working again, or the bounce came from a typo you have since corrected at the source. Fix the stored address too, or the next send will suppress it again.
- Safe: a
manualentry added by mistake. A newsletter opt-out is not removed here: lift it with fresh consent once the reader opts in again. - Usually unnecessary: a
soft_bounceentry that has not expired yet. It lifts on its own after 30 days. - Not safe: a
complaintentry. Someone marked your mail as spam. Sending again invites a second complaint, and complaint rate is the metric providers punish hardest. - Not safe: clearing the list in bulk to raise your recipient count. Permanent bounces do not heal on their own, and a batch re-send to known-dead addresses is the clearest possible signal that you do not clean your list.
If you are unsure, leave the address suppressed. A missed message to one recipient is recoverable; a filtered domain affects everyone you write to.
Check before you send
When a person is typing recipients, checking up front gives a better error than a rejected send. Page through the list once and cache it instead of calling per recipient.
// For a transactional send. A newsletter would read "all" and "marketing".
const blocking = new Set(["all", "transactional"]);
const suppressed = new Set();
const now = Date.now();
for await (const entry of shipmail.suppressions.listAutoPaginating({ limit: 100 })) {
if (!blocking.has(entry.scope)) continue;
if (entry.expires_at && Date.parse(entry.expires_at) <= now) continue;
suppressed.add(entry.email_address);
}
const blocked = recipients.filter((r) => suppressed.has(r.toLowerCase().trim()));
if (blocked.length > 0) {
throw new Error(`Cannot send to: ${blocked.join(", ")}`);
}This only gets you a clearer error. The send endpoint checks the list again anyway, so a stale cache cannot let a suppressed message through.