Email suppressions API
Email Suppressions API for Recipient State
NoticeAPI turns hard bounces, spam complaints, provider suppressions, and manual blocks into recipient state your app can see. Future sends fail before provider handoff with recipient_suppressed.
POST /api/v1/suppressions
Authorization: Bearer ntc_...
Content-Type: application/json
{
"email": "[email protected]",
"reason": "support request"
}
200 OK
{
"suppression": {
"email": "[email protected]",
"source": "manual"
}
}
GET /api/v1/suppressions
[email protected]
DELETE /api/v1/suppressions
[email protected]Event-created records
Bounces, provider suppressions, quarantines, and spam complaints can create account-level suppression records.
REST list, add, remove
Audit addresses, add manual blocks, or clear a suppression after support confirms the recipient is safe to contact.
409 before handoff
Suppressed recipients return recipient_suppressed instead of creating provider traffic you already know should stop.
Broadcasts skip bad recipients
Broadcast fan-out checks suppressions per contact; unsubscribed contacts stay out through audience state.
Recipient state
A bad outcome should change the next send.
The suppression API keeps that loop visible: provider events create records, send attempts fail fast, and removals stay deliberate.
Bad outcome arrives
Provider bounces, suppressions, quarantines, and spam signals can become suppression records.
Record is visible
Your app can list account records or filter by email through /api/v1/suppressions.
recipient_suppressed
Future sends fail before provider handoff so the same bad address is not retried.
Unsuppress carefully
Remove a suppression only when the mailbox is fixed or the recipient has clearly asked to receive email again.
How it works
From bad outcome to a cleaner next send.
Capture the bad outcome
Provider statuses such as Bounced, Suppressed, Quarantined, and FilteredSpam can become suppression records.
Add manual blocks
Use POST /api/v1/suppressions for support requests, deleted users, or addresses your product should not contact.
Fail before provider handoff
REST and batch sends return recipient_suppressed with the blocked address instead of retrying the same recipient.
Remove only after review
DELETE the record only when the mailbox is fixed or the recipient has clearly asked to receive email again.
Trust
No bypass, no mystery list.
Suppressions are account-level recipient state. NoticeAPI enforces them before sending; removal should be a support or re-opt-in decision, not a way around bounces or opt-outs.
Implementation links
Build with the shipped docs.
FAQ
Questions developers ask before switching email.
Can I bypass a suppression for a transactional send?
No. Suppressions are enforced before provider handoff. Remove the record only after a real mailbox fix, support review, or recipient request.
What creates an automatic suppression?
Provider delivery statuses such as Bounced, Suppressed, Quarantined, and FilteredSpam can create suppression records. Manual API blocks are stored as manual records.
Are simulated bounces suppressed?
No. Simulator bounces are repeatable test outcomes and do not suppress the simulator address.
When should I remove a suppression?
Only when you have a clear reason, such as a recipient fixing their mailbox or asking to receive email again.
Start in the sandbox, then send from a verified domain.
Free includes simulator testing and 3,000 emails per month. Real sending on Free needs operator activation plus a verified domain; Pro adds more volume, domains, contacts, automation runs, REST attachments, and visible usage billing.