Email Suppression
The Vonage Messages API Email channel includes an automatic suppression feature that is enabled by default for all customers. Suppression ensures that email addresses identified as invalid or complaint-prone are added to the suppression list and are never delivered to again. Any blocked delivery is reported as a delivery event rejected with error code 2003, keeping your sending reputation intact and providing accurate status updates for every recipient.
Why Suppression Matters
Sending emails to invalid or complaint-prone addresses damages your sender reputation with ISPs and email providers. A degraded reputation leads to legitimate emails being marked as spam or blocked outright.
The suppression feature protects against this by:
- Preventing delivery attempts to known-bad addresses before they reach ISPs.
- Automatically recording new bad addresses as they are discovered through delivery feedback.
- Ensuring you still receive accurate delivery status for suppressed recipients, rather than a silent failure.
How Suppression Works
Suppression operates in two directions: checking existing suppressions before a send, and adding new addresses to the suppression list based on delivery feedback.
Checking Suppression Before Sending
Every time an email send request is received, all recipients (To, CC, and BCC) are checked against the suppression list before the email is submitted to the provider. This happens automatically with no account configuration required.
There are three possible outcomes:
Scenario A — No recipients are suppressed
All recipients are clear. The email is sent normally and you receive a provider message ID confirming submission.
Scenario B — Some recipients are suppressed (partial suppression)
One or more recipients are on the suppression list, but at least one is clear.
- The suppressed recipients are removed from the delivery.
- The email is sent to the remaining active recipients.
- A suppression event is published for each blocked recipient — rejected with error code 2003 — so you see an accurate delivery status for every recipient, including those who were not sent to.
- You receive the same provider message ID that covers both the sent and suppressed recipients.
Scenario C — All recipients are suppressed
Every recipient across To, CC, and BCC is on the suppression list.
- The email is not sent.
- A suppression event is published for each recipient — rejected with error code 2003.
- You receive a valid provider message ID, indistinguishable from a real send, so your systems can track the message normally.
Adding Addresses to the Suppression List
The email provider sends delivery feedback events (bounces and complaints) back to the Vonage email engine. These events are processed to keep the suppression list up to date.
The type of suppression list an address is added to depends on the event received:
| Event type | Suppression scope | Added to suppression list |
|---|---|---|
| Hard bounce | Global | Yes |
| Complaint / SPAM report | Per account + identity | Yes |
| Other complaints (virus detection, not-spam corrections, DKIM failures) | N/A | No |
Suppression Types Reference
The following table maps provider delivery feedback events to Vonage Messages API error codes and indicates whether the event results in a suppression.
| Bounce type | Vonage reason code | Description | Status | Error code | Added to suppression list |
|---|---|---|---|---|---|
| Hard bounce | RECIPIENT_BLOCKED |
The address is on the platform's suppression list | Rejected | 2003 | Yes (global) |
| Hard bounce | RECIPIENT_MISSING |
Email address does not exist | Rejected | 1170 | Yes (global) |
| Hard bounce | ACCOUNT_BLOCKED |
The address is on this account's suppression list | Rejected | 2003 | Yes (global) |
| Soft bounce | MAILBOX_FULL |
Recipient's mailbox is temporarily full | Rejected | 1180 | No |
| Soft bounce | CONTENT_TOO_LARGE |
The message was too large to deliver | Rejected | 2002 | No |
| Soft bounce | ATTACHMENT_REJECTED |
Attachment was rejected by the receiving server | Rejected | 1382 | No |
| Soft bounce | GATEWAY_TIMEOUT |
Delivery timed out waiting for the receiving server | Rejected | 1230 | No |
| Soft bounce | CONTENT_REJECTED |
Content was rejected by the receiving server | Rejected | 1282 | No |
| Hard bounce | UNKNOWN |
Unclassified bounce | Rejected | 1330 | Yes (global) |
| Complaint | USER_SPAM_REPORT |
Recipient marked the email as spam | Not sent | N/A | Yes (per account + identity) |
| Complaint | OTHER_FEEDBACK |
Generic complaint feedback | Rejected | — | Yes (per account + identity) |
| Complaint | FRAUD_ALERT |
Email flagged as potential fraud | Rejected | 2001 | No |
| Complaint | AUTH_FAILURE |
DKIM / email authentication issue | Rejected | 1484 | No |
| Complaint | NOT_SPAM_CORRECTION |
Recipient corrected a spam misclassification | N/A | N/A | No |
| Complaint | VIRUS_DETECTED |
Email flagged for containing a virus | Rejected | 1282 | No |
Note: Vonage always sends rejected events to your webhook with error code 2003 for every suppressed email send.
Delivery Status for Suppressed Recipients
When a recipient is suppressed, the email engine publishes a synthetic bounce or complaint event that mirrors the format of a real provider event. This means:
- Downstream systems (for example, the email connector and webhooks) receive a well-formed status update for every recipient, whether they were actually sent to or not.
- You can track the full outcome of every message without any special handling for suppressed cases.