Suppressions API

Keep your own system and SendMero's suppression list in step: add an address the moment someone unsubscribes, and read the list back whenever you need it.

Read The suppression list first to see what a suppressed address is. Everything below uses the same API key as sending:

Authorization: Bearer YOUR_API_KEY

The key identifies your workspace. Base URL: https://api.sendmero.com/v1/suppressions.

Add addresses

POST /v1/suppressions adds one address or up to 1,000 in a single call.

curl --request POST 'https://api.sendmero.com/v1/suppressions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "emails": ["jane@example.com", "john@example.com"],
    "reason": "unsubscribe",
    "note": "Unsubscribed on our preferences page"
  }'

Field	Required	Meaning
emails	Yes	A list of 1 to 1,000 addresses.
reason	No	manual (default), unsubscribe, hard_bounce or complaint. The same reason applies to every address in the call.
note	No	Up to 500 characters, kept with the entry.

Response (200):

{
  "added": 1,
  "already_suppressed": 0,
  "invalid": 0,
  "duplicate": 1,
  "failed": 0,
  "results": [
    { "email": "jane@example.com", "status": "added" },
    { "email": "jane@example.com", "status": "duplicate" }
  ]
}

Each address gets one status:

Status	Meaning
added	The address is now suppressed.
already_suppressed	It was already on the list; it is left as it is.
invalid	Not a usable email address.
duplicate	The same address appeared earlier in this call.
failed	It could not be saved. Send it again.

The call is safe to repeat: addresses that are already suppressed are not changed. An added address is blocked from the next message that SendMero processes.

List addresses

GET /v1/suppressions returns one page, most recently seen first.

curl 'https://api.sendmero.com/v1/suppressions?reason=hard_bounce&limit=100' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Query parameter	Meaning
search	Part of an address.
reason	hard_bounce, complaint, unsubscribe or manual.
source	event, import, api, dashboard, unsubscribe_link or crm_sync.
from, to	A last-seen window, as dates such as 2026-10-01T00:00:00Z.
limit	Page size, 1 to 200 (default 50).
cursor	The next_cursor of the previous page.

{
  "data": [
    {
      "email": "jane@example.com",
      "applies_to": "workspace",
      "group": "",
      "reason": "hard_bounce",
      "reasons": ["hard_bounce"],
      "source": "event",
      "details": "550 5.1.1 The email account does not exist",
      "first_seen": "2026-10-17T05:54:58.722Z",
      "last_seen": "2026-10-17T05:54:58.722Z"
    }
  ],
  "next_cursor": "eyJ..."
}

applies_to is workspace (all mail) or group (an unsubscribe that applies to one sending domain, named in group). next_cursor is null on the last page. Pass it unchanged as cursor to get the next page.

Get one address

GET /v1/suppressions/{email} returns the entry above for one address, or 404 not_found when it is not suppressed. URL-encode the address, for example jane%40example.com.

Remove an address

DELETE /v1/suppressions/{email} lets SendMero send to the address again.

curl --request DELETE 'https://api.sendmero.com/v1/suppressions/jane%40example.com?note=Resubscribed' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Query parameter	Meaning
note	Why you removed it. Kept in your audit log.
confirm_opt_in=true	Required for an unsubscribed address: it confirms the recipient opted in again.

Response: { "removed_reasons": ["manual"] }.

Spam complaints cannot be removed through the API. An owner or admin can remove them in the dashboard.

Errors

Errors use the standard format.

Status	error.code	Meaning
400	invalid_request	A parameter or the emails list is missing or not valid.
400	invalid_json	The body is not valid JSON.
400	invalid_reason	reason is not one of the four values.
400	invalid_note	note is longer than 500 characters.
400	too_many_addresses	More than 1,000 addresses in one call.
400	invalid_address	The address in the path is not a valid email address.
400	opt_in_required	Removing an unsubscribed address needs confirm_opt_in=true.
401	missing_api_key, invalid_api_key	The key is missing, wrong, revoked or expired.
403	complaint_removal_forbidden	Spam complaints cannot be removed with the API.
404	not_found	The address is not on the list.
405	method_not_allowed	The method is not supported on that path.
413	payload_too_large	The request body is too large.
429	rate_limit_exceeded, busy	Too many requests. Wait for Retry-After and try again.
503	service_unavailable	Try again shortly.

Limits

Suppression calls have their own limit of 1,000 requests per 10 seconds per workspace. They do not use up your sending limit. To add many addresses, send them in batches of up to 1,000 rather than one call per address.