Suppressions

Overview

What suppression is

A suppression is a single email address on a do-not-send list, keyed by the address itself (not a contact). When an address is suppressed, PristineSend refuses to send to it on both paths:

• Transactional — POST /send and /send/batch reject a suppressed recipient with 403 recipient_suppressed. In a batch this surfaces as a per-item recipient_suppressed error (that item fails; the rest still send) rather than a whole-request 403.
• Campaigns and automations — suppressed addresses are skipped, so they are never enqueued.

Addresses land on the list from several sources:

The source matters when you remove a row: hard_bounce and complaint suppressions are protected and require force=true to delete (see Remove a suppression).

The suppression object

Each entry in the list has this shape:

List suppressions

Returns a cursor-paginated list of suppressed addresses, newest first, in the same { data, has_more, next_cursor } shape as the other list endpoints. Pass next_cursor back as the cursor parameter to fetch the next page.

Query parameters

Check one address: pass ?email= to look up a single address instead of paging the whole list — the fastest way to answer “is this recipient suppressed?” before a send. It returns the one matching entry (or an empty data array if the address is clear). This is the same check the MCP check_suppression tool runs.

Response

"color:#ff7b72">import { PristineSend } "color:#ff7b72">from "pristinesend"

"color:#ff7b72">const ps = "color:#ff7b72">new PristineSend(process.env.PRISTINESEND_API_KEY!)

// The returned page auto-paginates — iterate across every page transparently.
for "color:#ff7b72">await ("color:#ff7b72">const entry of "color:#ff7b72">await ps.suppressions.list({ limit: 100 })) {
  console.log(entry.email, entry.reason, entry.source)
}

Add a suppression

Adds an address to the do-not-send list with source: "api". The email need not be an existing contact — you can suppress any address. The call is idempotent: re-POSTing an address that is already suppressed is a 200 no-op success, not a conflict. Returns 200 with the suppression object.

Request body

Response

"color:#ff7b72">import { PristineSend } "color:#ff7b72">from "pristinesend"

"color:#ff7b72">const ps = "color:#ff7b72">new PristineSend(process.env.PRISTINESEND_API_KEY!)

// Idempotent: re-adding the same address is a no-op success, not an error.
"color:#ff7b72">const entry = "color:#ff7b72">await ps.suppressions.create({
  email: "optout@example.com",
  reason: "User asked to be removed",
})
console.log("Suppressed:", entry.email, entry.source)

Remove a suppression

Removes the suppression for the given email, letting mail to that address resume. Send the address in the JSON body ({ "email": "…" }) — recommended, since a raw @ in the URL is rejected by the edge with a 404 before it reaches the API. You may instead pass ?email= in the query, but the @ must be percent-encoded as %40. Returns 204 No Content on success, or 404 not_found if the address is not suppressed.

Parameters (body or query)

Response

"color:#ff7b72">import { PristineSend, ConflictError } "color:#ff7b72">from "pristinesend"

"color:#ff7b72">const ps = "color:#ff7b72">new PristineSend(process.env.PRISTINESEND_API_KEY!)

// The SDK sends the address in the body, so "@" never hits the URL. Pass
// force: true to lift a hard_bounce- or complaint-sourced suppression.
try {
  "color:#ff7b72">await ps.suppressions.delete({ email: "bounced@example.com", force: true })
  // Resolves on 204 No Content — mail to this address resumes.
} catch (err) {
  if (err instanceof ConflictError) {
    // Bounced/complained — retry with force: true only if you really mean to.
  }
  throw err
}

Errors

All errors use the standard envelope. The codes specific to this resource:

Separately, recipient_suppressed (403) is raised by the send endpoints — not this one — when you try to mail an address on this list. See the full Error codes reference for the canonical envelope and the complete list.