Skip to content
couryo
Guide pages

Developer guideEvents

Suppression

Couryo's suppression list protects your reputation. Reasons, streams, and how to list, add and remove addresses through the API.

View as Markdown

The suppression list holds addresses Couryo will no longer send to. It protects your reputation: insisting on an address that does not exist, or on someone who complained, drags down delivery of all your email.

Reasons#

reason When it is added Applies to
hard_bounce the address does not exist (5.1.x) all streams
complaint the recipient marked the email as spam all streams
unsubscribe the recipient unsubscribed only the stream they unsubscribed from (usually marketing)
manual you added it the stream you choose

A marketing unsubscribe never blocks transactional email: someone who left the newsletter still gets the password reset.

What happens when sending#

If some recipients are suppressed, the email goes to the others and the timeline gets a suppressed event for each skipped address. If every recipient is suppressed, the send is refused with 422 recipient_suppressed, and param points to the first one (to[0]). In a batch, only the affected item is refused.

Temporary bounces (4.x.x) also lead to suppression when the same address bounces on 3 different days.

List#

cURL
curl "https://api.couryo.com/v1/suppressions?limit=25" \
  -H "Authorization: Bearer $COURYO_API_KEY"
Response
{
  "data": [
    { "email": "maria@company.com", "reason": "hard_bounce", "stream": "all", "created_at": "2026-10-07T18:31:04Z" }
  ],
  "has_more": false
}

Add#

cURL
curl https://api.couryo.com/v1/suppressions \
  -H "Authorization: Bearer $COURYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "do-not-send@example.com", "stream": "marketing" }'

Remove#

cURL
curl -X DELETE https://api.couryo.com/v1/suppressions/maria@company.com \
  -H "Authorization: Bearer $COURYO_API_KEY"

The address leaves every stream (204). Remove an address only when you are sure the problem is solved (for example, the person confirmed the address works again).

Scopes and filters#

  • Listing needs the read scope; adding and removing, admin.
  • The list accepts q (part of the address), reason and limit (default 100), with starting_after for the next page.
  • Added addresses always get the manual reason; stream can be transactional, marketing or all (default). An address already on the list returns 409 already_suppressed.