01
How addresses get suppressed#
A hard bounce or a spam complaint suppresses the address permanently. Soft bounces (a full mailbox, a temporary failure) suppress it for 24 hours once there have been 3 in 7 days. You can add addresses yourself, for example people who unsubscribed elsewhere. Sends to a suppressed address drop that recipient and emit email.suppressed; the rest of the email still goes out. Suppressions belong to your organization; add domain_id to scope one to a single sending domain.
02
List and search#
GET /v0/suppressions returns your entries newest first, with email, reason, source (bounce, complaint, manual, unsubscribe or import), domain_id, expires_at and created_at. Filter with q (part of an address), source and domain_id; page with limit (up to 100) and cursor. Requires an account-scoped, full-access key and the Owner or Admin role. Sending keys can't read or change the list.
curl "https://botinbox.dev/v0/suppressions?q=example.com&limit=50" -H "Authorization: Bearer $BOTINBOX_API_KEY"03
Add and remove#
POST /v0/suppressions with email or emails (up to 1,000) and an optional reason and domain_id. DELETE /v0/suppressions/:id_or_email removes an entry, so sends to that address resume.
curl https://botinbox.dev/v0/suppressions -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" \
-H "Content-Type: application/json" -d '{"emails":["ada@example.com"],"reason":"unsubscribed"}'
curl https://botinbox.dev/v0/suppressions/ada@example.com -X DELETE -H "Authorization: Bearer $BOTINBOX_API_KEY"04
Import a list#
Moving from another provider? POST a CSV with Content-Type: text/csv: either a header row with an email column, or one address per line. Up to 100,000 addresses per request; existing entries are skipped and invalid lines are reported. Add ?domain_id= to scope the import to one domain.
curl https://botinbox.dev/v0/suppressions -X POST -H "Authorization: Bearer $BOTINBOX_API_KEY" \
-H "Content-Type: text/csv" --data-binary @suppressions.csv
# 201 {"object":"suppression_import","total":48211,"added":48190,"existing":21,"invalid":[]}