Addresses that send.dev will not send to because they bounced, complained, or unsubscribed, and how to release one
When an email hard-bounces or the recipient reports it as spam, the address is added to your suppression list. Any later request that includes a suppressed address in to, cc, or bcc is rejected with 400 validation_error before anything is sent. This protects your sending reputation: repeatedly mailing addresses that bounce or complain is the fastest way to end up in the spam folder for everyone.
Recipients who use an unsubscribe link land on the same list with reason: "unsubscribe", but are enforced more gently: only marketing mail to them is rejected (400 recipient_unsubscribed), and transactional mail still goes through.
Suppression lists are per account. An address suppressed for you is not suppressed for other send.dev customers.
| Field | Type | Description |
|---|---|---|
email | string | The suppressed address. |
reason | string | bounce, complaint, or unsubscribe. |
status | string | suppressed, unsuppressed, or permanent (see below). |
bounceType | string | For bounces: Permanent, Transient, or Undetermined. Absent otherwise. |
listId | string | For unsubscribes: the listId from the email the recipient opted out of, if you set one. |
createdAt | number | Unix time in milliseconds when the address was first suppressed. |
lastEventAt | number | Unix time in milliseconds of the most recent bounce, complaint, or unsubscribe. Also the pagination cursor. |
status | Meaning |
|---|---|
suppressed | Active. Sends to this address are rejected (for unsubscribe, only marketing sends). |
unsuppressed | You released it and it has not bounced since. Sends are allowed. |
permanent | It bounced again after being released, or bounced too many times. It cannot be released again. |
/v1/send/suppressionsList suppressed addresses, most recent event first, with cursor pagination.
limitinteger50cursorintegerreasonstringbouncecomplaintunsubscribestatusstringsuppressedunsuppressedpermanentcurl "https://api.do.dev/v1/send/suppressions?reason=bounce&limit=50" \
-H "Authorization: Bearer $SEND_API_KEY"{
"suppressions": [
{
"email": "gone@example.net",
"reason": "bounce",
"status": "suppressed",
"bounceType": "Permanent",
"createdAt": 1757000004100,
"lastEventAt": 1757000004100
}
],
"nextCursor": null
}nextCursor is null on the last page. Otherwise pass it back as cursor to get the next page. An invalid reason, status, or limit returns 400 validation_error.
/v1/send/suppressions/{email}Return the suppression record for one address. URL-encode the address.
curl "https://api.do.dev/v1/send/suppressions/gone%40example.net" \
-H "Authorization: Bearer $SEND_API_KEY"/v1/send/suppressions/{email}/unsuppressRelease an address so you can send to it again. Also removes it from the underlying SES suppression list.
Use this when you know the bounce was transient or the address has been fixed, for example a customer corrected a typo in their profile. Each address can be released a limited number of times; if it bounces again after release, it becomes permanent.
curl -X POST "https://api.do.dev/v1/send/suppressions/gone%40example.net/unsuppress" \
-H "Authorization: Bearer $SEND_API_KEY"{
"success": true,
"email": "gone@example.net",
"unsuppressCount": 1,
"remainingAttempts": 1,
"sesRemoved": true,
"message": "Email unsuppressed. You have 1 attempt(s) remaining if this email bounces again."
}A complaint suppression means the recipient clicked "report spam" in their mail client. Releasing a complaint suppression is technically allowed, but you should do so only if the person has explicitly asked you to resume mailing them. Complaint rates above a fraction of a percent are what get sending domains blocked by mailbox providers, and also what trips send.dev's own reputation safeguards.
An unsubscribe suppression means the recipient used the link or one-click header on an email you sent with unsubscribe support. GET /v1/send/suppressions?reason=unsubscribe lists them, with listId when you set one. Unlike bounces and complaints, an unsubscribe blocks only category: "marketing" sends unless your account has "block all" enabled. How the link is added, what the recipient sees, and the send.email.unsubscribed webhook event are covered on Unsubscribe.