Suppressions

#

Addresses this account will not send to. A hard bounce (a 5.x.x code from the receiving server) or a spam complaint puts an address here on its own, before your next send, so nothing in your integration has to understand a bounce. A soft bounce (4.x.x: a full mailbox, a server having a bad hour) does not. An outcome under a sub-account lists the address on the sub-account and on its parent, and a sub-account’s sends are checked against both lists.

Add an address yourself when someone asks you to stop, with a note for whoever reads the list later. Adding is an upsert: asking twice is not an error, and an address the system already caught becomes a manual entry carrying your note. Removal is a separate, deliberate call rather than a flag on the send, because the list protects the sending reputation every customer shares. reason is bounce, complaint or manual; detail is the receiving server’s words or your own.

GET /api/v1/suppressions

List suppressed addresses. Scope suppressions:read.

Newest first. Hard bounces and complaints arrive here on their own; a manual entry is one you added. An outcome recorded under a sub-account lists the address on the sub-account and on its parent.

curl
curl "https://barua.tz/api/v1/suppressions?address=juma%40example.co.tz" \
-H "Authorization: Bearer $BARUA_API_KEY"
response 200
{
"data": [
{
"id": "3a4b5c6d-7e8f-4901-a2b3-c4d5e6f70819",
"address": "juma@example.co.tz",
"reason": "bounce",
"detail": "550 5.1.1 The email account that you tried to reach does not exist",
"createdAt": "2026-09-24T08:15:41.000Z"
}
],
"nextCursor": null
}
  • 422 invalid_requestThe body or query failed validation. The message names the first field that failed.
  • 422 invalid_cursorcursor is not one this list issued: pass back the nextCursor it gave you, unchanged.

POST /api/v1/suppressions

Add an address by hand. Scope suppressions:write.

An upsert: asking twice is not an error, and an address the system already caught becomes a manual entry carrying your note.

curl
curl https://barua.tz/api/v1/suppressions \
-H "Authorization: Bearer $BARUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": "juma@example.co.tz",
"detail": "Asked on WhatsApp on 12 September to stop receiving statements."
}'
response 201
{
"id": "3a4b5c6d-7e8f-4901-a2b3-c4d5e6f70819",
"address": "juma@example.co.tz",
"reason": "manual",
"detail": "Asked on WhatsApp on 12 September to stop receiving statements.",
"createdAt": "2026-09-24T08:15:41.000Z"
}
  • 400 invalid_jsonThe request body could not be parsed as JSON.
  • 422 invalid_requestThe body or query failed validation. The message names the first field that failed.

DELETE /api/v1/suppressions

Remove an address from the list. Scope suppressions:write.

A deliberate call rather than a flag on the send: the list protects the sending reputation every customer shares, so sending anyway is a decision someone makes.

curl
curl -X DELETE "https://barua.tz/api/v1/suppressions?address=juma%40example.co.tz" \
-H "Authorization: Bearer $BARUA_API_KEY"
response 204
No body (204)
  • 404 suppression_not_foundThe address is not on this account's suppression list.
  • 422 invalid_requestThe body or query failed validation. The message names the first field that failed.

Something unclear or wrong? That is a bug in these docs. Write to support@barua.tz.