API reference

Suppressions API

Reference for adding, listing, retrieving and removing suppressed email addresses, one at a time or in batches.

The suppressions API manages your team's list of addresses that Sooner will not send to. The list is shared by every project in the team. Every endpoint needs a full_access key. For the concepts, see Suppressions.

The suppression object

JSON

{
  "object": "suppression",
  "id": "sup_Ym91bmNlZEBleGFtcGxlLmNvbQ",
  "email": "bounced@example.com",
  "origin": "bounce",
  "source_id": "01jcz8w3f2x9k4m7n6p5q2r1s0",
  "created_at": "2026-11-14T10:30:00.000Z"
}

origin is bounce, complaint or manual. source_id is the ID of the email that caused a bounce or complaint, and null otherwise. The id is sup_ followed by the lowercase address encoded in base64url, so wherever a path takes an ID you can use the email address instead. List items omit object.

Add a suppression

POST/suppressions

Field	Type	Required	Description
`email`	string	Yes	A valid address, 3 to 320 characters. Stored in lowercase.

Shell

curl -X POST https://api.sooner.dev/suppressions \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "bounced@example.com" }'

JSON

{ "object": "suppression", "id": "sup_Ym91bmNlZEBleGFtcGxlLmNvbQ" }

Adding an address that is already suppressed succeeds and keeps the original entry. Notable errors: validation_error for an invalid address.

Add suppressions in a batch

POST/suppressions/batch/add

Field	Type	Required	Description
`emails`	string[]	Yes	1 to 1,000 addresses. Invalid addresses are skipped.

Shell

curl -X POST https://api.sooner.dev/suppressions/batch/add \
  -H "Authorization: Bearer $SOONER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "emails": ["a@example.com", "b@example.com"] }'

JSON

{
  "data": [
    { "object": "suppression", "id": "sup_YUBleGFtcGxlLmNvbQ", "email": "a@example.com" },
    { "object": "suppression", "id": "sup_YkBleGFtcGxlLmNvbQ", "email": "b@example.com" }
  ]
}

Remove suppressions in a batch

POST/suppressions/batch/remove

The body is the same as for batch add. The response lists only the addresses that were on the list.

JSON

{
  "data": [
    { "object": "suppression", "id": "sup_YUBleGFtcGxlLmNvbQ", "email": "a@example.com", "deleted": true }
  ]
}

List suppressions

GET/suppressions

Parameter	Type	Required	Description
`limit`	integer	No	1 to 100, default 20.
`after`	string	No	The `id` of the last item of the previous page. An email address also works.
`origin`	string	No	`bounce`, `complaint` or `manual`.

Shell

curl "https://api.sooner.dev/suppressions?origin=bounce&limit=50" \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{
  "object": "list",
  "data": [
    {
      "id": "sup_Ym91bmNlZEBleGFtcGxlLmNvbQ",
      "email": "bounced@example.com",
      "origin": "bounce",
      "source_id": "01jcz8w3f2x9k4m7n6p5q2r1s0",
      "created_at": "2026-11-14T10:30:00.000Z"
    }
  ],
  "has_more": false
}

Do not rely on a particular order. Page with has_more and after until the list is exhausted. With an origin filter, a page can contain fewer items than limit while has_more is still true, so keep paging until has_more is false. See Pagination.

Retrieve a suppression

GET/suppressions/{idOrEmail}

Returns one suppression by ID or email address.

Shell

curl https://api.sooner.dev/suppressions/bounced@example.com \
  -H "Authorization: Bearer $SOONER_API_KEY"

The response is the suppression object. Notable errors: not_found.

Remove a suppression

DELETE/suppressions/{idOrEmail}

Removes an address so that Sooner can send to it again.

Shell

curl -X DELETE https://api.sooner.dev/suppressions/bounced@example.com \
  -H "Authorization: Bearer $SOONER_API_KEY"

JSON

{ "object": "suppression", "id": "sup_Ym91bmNlZEBleGFtcGxlLmNvbQ", "deleted": true }

Notable errors: not_found.