Suppressions — Reference

List suppressions

get /v1/suppressions

curl TypeScript

curl -X GET "https://api.clement.so/v1/suppressions" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.suppressions.list();

Query parameters

limit integer
starting_after string
ending_before string
email string
reason string

Response200

OK

Property	Type	Description
`object` required	enum (1)	`"list"`
`data` required	array<Suppression>
`has_more` required	boolean
`next_cursor` required	string \| null
`prev_cursor` required	string \| null

Example response

{
  "object": "list",
  "data": [
    {
      "id": "sup_01HZ8X3J9K7P2QV6R5N4M3T2L8",
      "object": "suppression",
      "mode": "live",
      "email": "alice@example.com",
      "reason": "unsubscribe",
      "source_send_id": "snd_01HZ8X3J9K7P2QV6R5N4M3T2L4",
      "created_at": "2026-04-30T08:14:22Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string",
  "prev_cursor": "string"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Add an email to the suppression list

post /v1/suppressions

Idempotent on email — re-POSTing the same email returns the existing row (200) rather than 201.

curl TypeScript

curl -X POST "https://api.clement.so/v1/suppressions" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "email": "alice@example.com",
      "reason": "unsubscribe"
    }'

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.suppressions.create({
  "email": "alice@example.com",
  "reason": "unsubscribe"
});

Request body

Property	Type	Description
`email` required	string (email)
`reason`	enum (3)	`"unsubscribe""hard_bounce""manual"`

Response200

Existing

Property	Type	Description
`id` required	string
`object` required	enum (1)	`"suppression"`
`mode` required	enum (2)	`"live""test"`
`email` required	string (email)
`reason` required	enum (3)	`"unsubscribe""hard_bounce""manual"`
`source_send_id` required	string \| null
`created_at` required	string (date-time)

Example response

{
  "id": "sup_01HZ8X3J9K7P2QV6R5N4M3T2L8",
  "object": "suppression",
  "mode": "live",
  "email": "alice@example.com",
  "reason": "unsubscribe",
  "source_send_id": "snd_01HZ8X3J9K7P2QV6R5N4M3T2L4",
  "created_at": "2026-04-30T08:14:22Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Add up to 1,000 suppressions in one call

post /v1/suppressions/batch

curl TypeScript

curl -X POST "https://api.clement.so/v1/suppressions/batch" \
  -H "Authorization: Bearer $CLEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
      "suppressions": [
        {
          "email": "alice@example.com",
          "reason": "unsubscribe"
        }
      ]
    }'

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.suppressions.batch([
  {
    "email": "alice@example.com",
    "reason": "unsubscribe"
  }
]);

Request body

Property	Type	Description
`suppressions` required	array<SuppressionCreate>

Response200

Result

Property Type Description

object required

enum (1)

"batch_result"

created required array<Suppression>

errors required

array<object>

Show properties

Property Type Description

index required integer

email required string

error required

object

Show properties

Property	Type	Description
`type` required	string
`code` required	string
`message` required	string

Example response

{
  "object": "batch_result",
  "created": [
    {
      "id": "sup_01HZ8X3J9K7P2QV6R5N4M3T2L8",
      "object": "suppression",
      "mode": "live",
      "email": "alice@example.com",
      "reason": "unsubscribe",
      "source_send_id": "snd_01HZ8X3J9K7P2QV6R5N4M3T2L4",
      "created_at": "2026-04-30T08:14:22Z"
    }
  ],
  "errors": [
    {
      "index": 0,
      "email": "alice@example.com",
      "error": {
        "type": "string",
        "code": "string",
        "message": "string"
      }
    }
  ]
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Retrieve a suppression

get /v1/suppressions/{id}

curl TypeScript

curl -X GET "https://api.clement.so/v1/suppressions/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.suppressions.retrieve("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Response200

OK

Property	Type	Description
`id` required	string
`object` required	enum (1)	`"suppression"`
`mode` required	enum (2)	`"live""test"`
`email` required	string (email)
`reason` required	enum (3)	`"unsubscribe""hard_bounce""manual"`
`source_send_id` required	string \| null
`created_at` required	string (date-time)

Example response

{
  "id": "sup_01HZ8X3J9K7P2QV6R5N4M3T2L8",
  "object": "suppression",
  "mode": "live",
  "email": "alice@example.com",
  "reason": "unsubscribe",
  "source_send_id": "snd_01HZ8X3J9K7P2QV6R5N4M3T2L4",
  "created_at": "2026-04-30T08:14:22Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.

Remove a suppression

delete /v1/suppressions/{id}

Admin-scope required (recipient comes off the global block list and may receive future sends).

curl TypeScript

curl -X DELETE "https://api.clement.so/v1/suppressions/obj_01HZ8X3J9K7P2QV6R5N4M3T2L1" \
  -H "Authorization: Bearer $CLEMENT_API_KEY"

import { Clement } from "@clement/sdk";

const c = new Clement({ apiKey: process.env.CLEMENT_API_KEY! });
const result = await c.suppressions.delete("obj_01HZ8X3J9K7P2QV6R5N4M3T2L1");

Path parameters

id string required

Response200

Deleted

Property	Type	Description
`id` required	string
`object` required	enum (1)	`"suppression"`
`mode` required	enum (2)	`"live""test"`
`email` required	string (email)
`reason` required	enum (3)	`"unsubscribe""hard_bounce""manual"`
`source_send_id` required	string \| null
`created_at` required	string (date-time)

Example response

{
  "id": "sup_01HZ8X3J9K7P2QV6R5N4M3T2L8",
  "object": "suppression",
  "mode": "live",
  "email": "alice@example.com",
  "reason": "unsubscribe",
  "source_send_id": "snd_01HZ8X3J9K7P2QV6R5N4M3T2L4",
  "created_at": "2026-04-30T08:14:22Z"
}

Errors

400 Invalid request
401 Authentication failed
403 Insufficient scope
404 Not found
409 Conflict
422 Validation failed
429 Rate limited

See Errors for the full envelope and per-code reference.