Suppressions Reference

Every endpoint for bounces, spam reports, global unsubscribes, and suppression groups. For the guide-level walk-through, see Suppressions; for the conceptual overview, Suppressions (concept).

Base paths:

• /v3/suppression/bounces — hard/soft bounce list
• /v3/suppression/spam_reports — spam complaints
• /v3/asm/suppressions/global — global unsubscribes
• /v3/asm/groups — suppression groups and their per-group lists

Required permission: suppressions.read for reads, suppressions.write for writes.

Bounces#

GET /v3/suppression/bounces#

List bounces.

Query parameters:

Response (200):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "bounces": [
    {
      "email": "invalid@example.com",
      "created": 1714060800,
      "reason": "550 5.1.1 User unknown",
      "bounce_type": "hard",
      "status": "5.1.1"
    }
  ],
  "total": 152
}

GET /v3/suppression/bounces/{email}#

Get a specific bounce record.

Response (200): [BounceResponse] (may be multiple entries if the address bounced more than once).

Errors: 404 if not in the list.

POST /v3/suppression/bounces#

Add a bounce manually.

Request body:

Response (201): the created record.

POST /v3/suppression/bounces/import#

Bulk import from CSV. Columns: email, reason (optional).

Content-Type: text/csv.

Response (200):

1
2
3
4
5
6
7

{
  "imported": 1482,
  "skipped": 12,
  "errors": [
    {"row": 44, "email": "not-an-email", "error": "Invalid email format"}
  ]
}

DELETE /v3/suppression/bounces/{email}#

Remove a bounce. Future sends to this address are allowed again.

Response (204): no body.

DELETE /v3/suppression/bounces#

Bulk delete.

Query parameters:

Response (204): no body.

Spam reports#

Endpoints mirror bounces.

GET /v3/suppression/spam_reports#

Response (200):

1
2
3
4
5
6

{
  "spam_reports": [
    {"email": "abuser@example.com", "created": 1714060800, "source": "feedback_loop"}
  ],
  "total": 20
}

GET /v3/suppression/spam_reports/{email}#

Get a specific report.

POST /v3/suppression/spam_reports#

Add manually. Body: {email, source}.

POST /v3/suppression/spam_reports/import#

Bulk import. CSV columns: email, source (optional).

DELETE /v3/suppression/spam_reports/{email}#

Remove a report.

Global unsubscribes#

GET /v3/asm/suppressions/global#

List all addresses globally unsubscribed from this tenant's mail.

Query parameters: limit, offset, start_time, end_time.

Response (200):

1

{"recipient_emails": ["user@example.com"], "total": 1}

GET /v3/asm/suppressions/global/{email}#

Check whether a specific address is globally unsubscribed.

Response (200): {"recipient_email": "user@example.com"} if yes, 404 if no.

POST /v3/asm/suppressions/global#

Add addresses to the global unsubscribe list.

Request body:

1

{"recipient_emails": ["user@example.com", "other@example.com"]}

Response (201): {"recipient_emails": [...]} — the addresses that were added.

POST /v3/asm/suppressions/global/import#

Bulk import. CSV column: email.

DELETE /v3/asm/suppressions/global/{email}#

Remove from global unsubscribe list (re-subscribe).

Suppression groups#

GET /v3/asm/groups#

List all groups.

Response (200):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "suppression_groups": [
    {
      "id": 123,
      "name": "Newsletter",
      "description": "Our weekly digest",
      "is_default": false,
      "unsubscribes": 42,
      "created_at": "2026-04-23T10:00:00Z"
    }
  ]
}

POST /v3/asm/groups#

Create a group.

Request body:

Response (201): the created group.

GET /v3/asm/groups/{group_id}#

Get a single group.

PATCH /v3/asm/groups/{group_id}#

Update a group's fields.

DELETE /v3/asm/groups/{group_id}#

Delete a group and all its suppressions.

Response (204): no body.

GET /v3/asm/groups/{group_id}/suppressions#

List addresses suppressed in a group.

Query parameters: page, page_size.

Response (200):

1

{"recipient_emails": ["opted-out@example.com"], "total": 1}

POST /v3/asm/groups/{group_id}/suppressions#

Add addresses to a group.

Request body:

1

{"recipient_emails": ["opt-out@example.com"]}

Response (201): {"recipient_emails": [...]}.

DELETE /v3/asm/groups/{group_id}/suppressions/{email}#

Remove from a group (re-subscribe).

Response (204): no body.

Bounce types#

Related#

• Suppressions (guide)
• Suppressions (concept)
• Bounce Handling
• Feedback Loops