Suppressions
Manage bounced, complained, unsubscribed, and manually blocked email addresses.
Manage email addresses that should not receive messages to protect your sender reputation.
What are Suppressions?
Suppressions are blocked addresses. When an address is suppressed, future emails to it are prevented from sending.
| Reason | How it gets added | What it blocks |
|---|---|---|
bounce | Automatically, when an email permanently fails (invalid address) | All email |
complaint | Automatically, when a recipient marks an email as spam | All email |
unsubscribe | Automatically, when a recipient opts out via the unsubscribe link | Campaigns and sequences only |
manual | By you, from the dashboard or the API | All email |
"All email" includes transactional sends through POST /email/send. Unsubscribes only stop marketing mail, so a recipient who opts out of your newsletter still gets password resets and receipts.
Why Suppressions Matter
High bounce and complaint rates result in:
- Emails going to spam folders
- Temporary sending blocks
- Permanent blacklisting
Best Practice: Keep bounce rate under 2% and complaint rate under 0.1%.
How It Works
Step 1: Automatic Detection
When an email bounces, generates a complaint, or someone unsubscribes, the address is automatically suppressed.
Step 2: Sending Blocked
Future sends to suppressed addresses are blocked at the API level before delivery is attempted.
Step 3: Review & Manage
View all suppressed addresses in your dashboard. Add addresses you never want to email, or remove addresses suppressed in error.
Adding Suppressions
Add addresses yourself to block them proactively, for example a customer who asked not to be contacted, a role address like abuse@, or a bounce list exported from your previous email provider.
From the Dashboard
- Go to Suppressions in the sidebar
- Click Add Suppressions
- Paste addresses (one per line, or separated by commas), or upload a CSV
- Pick a reason and click Suppress
For CSV files, Transmit uses the column named email or address if there is one. Otherwise it takes the first cell in each row that contains an email address. Invalid addresses are skipped and listed before you submit.
Moving from another provider? Import its bounce list with the reason Bounced (imported) and its complaint list with Complained (imported), so your history carries over and those addresses never get mail from Transmit.
From the API
Add a single address. reason is optional and defaults to manual.
curl -X POST https://api.xmit.sh/api/suppressions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "reason": "manual"}'Returns 201 with { "id": "sup_xxx", "email": "user@example.com", "reason": "manual" }, or 409 if the address is already suppressed.
Add up to 500 addresses in one request. One reason applies to the whole request.
curl -X POST https://api.xmit.sh/api/suppressions/bulk \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"emails": ["a@example.com", "b@example.com"], "reason": "bounce"}'{ "added": 2, "alreadySuppressed": 0, "invalid": [] }Addresses that are already suppressed keep their existing reason. Invalid addresses are returned in invalid and do not fail the request.
| Field | Type | Description |
|---|---|---|
email / emails | string / string[] | Address(es) to suppress. Stored lowercased. |
reason | string | manual (default), unsubscribe, bounce, or complaint |
source | string | Optional label for where the entry came from, up to 100 characters. Defaults to api. |
Other Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/suppressions?q=&limit=&offset= | List suppressions, newest first. q searches by email. Returns totalCount. |
GET | /api/suppressions/check/:email | Check whether an address is suppressed |
DELETE | /api/suppressions/:idOrEmail | Remove a suppression by its ID or email |
Removing Suppressions
- Go to Suppressions in the sidebar
- Search for the address
- Click Remove
Safe to Remove
- User confirmed email is valid
- Temporary inbox issue resolved
- User re-subscribed intentionally
Risky to Remove
- Hard bounce (invalid address)
- Spam complaint
- Unknown or unverified request
Related Features
- Email Validation - Validate before sending
- Lists & Contacts - Organize your audience