Suppressions

A suppression is an address your account will not send to. Sending to one is rejected before anything leaves, which protects your sending reputation and keeps you from mailing people who bounced or complained.

How addresses get suppressed

Suppressions are per account. Test-mode sends never add suppressions, and simulator addresses on the sandbox domain are never suppressed in either mode, so bounced@ and complained@ can be used as often as you like.

An address erased with POST /v1/recipients/erase stays on the list as a manual entry with email_address: null. It still blocks sends.

Listing, adding and removing need the suppressions:manage scope. Adding and removing also need a live key: a test key gets 403 forbidden.

What happens on send

A request with a suppressed recipient anywhere in to, cc or bcc returns 422 recipient_suppressed and nothing is sent, not even to the other recipients.

{
  "error": {
    "code": "recipient_suppressed",
    "message": "Recipient suppressed: old@example.com. Previous bounce or complaint. Remove the address from suppressions to send again.",
    "details": { "suppressed": ["old@example.com"] }
  }
}

List

curl "https://api.avelto.dev/v1/suppressions?limit=100" \
  -H "Authorization: Bearer av_live_..."

{
  "data": [
    {
      "id": "3e5f7a9b-1c2d-4e6f-8a0b-2c4d6e8f0a1b",
      "email_address": "old@example.com",
      "reason": "bounce",
      "created_at": "2026-09-10T08:30:00.000Z"
    }
  ],
  "next_cursor": null
}

Cursor-paginated like the email and delivery lists: pass next_cursor back as cursor.

Add

Add an address when someone unsubscribes or asks not to be contacted. Addresses are stored lower-cased. Returns 201 with the suppression object. Adding one that is already suppressed returns 409 conflict.

curl -X POST https://api.avelto.dev/v1/suppressions \
  -H "Authorization: Bearer av_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "unsubscribed@example.com"
  }'

Remove

Remove an address to send to it again, for instance after a bounce caused by a full mailbox that has since been cleared. URL-encode the address (@ becomes %40).

curl -X DELETE https://api.avelto.dev/v1/suppressions/unsubscribed%40example.com \
  -H "Authorization: Bearer av_live_..."

Returns 204; an address that is not on the list is 404 not_found. Removing a bounced or complained address does not prevent it from being suppressed again the next time it bounces or complains.