Suppressions

Block sends to addresses that bounced, complained, or were added manually. Suppressions are tenant-local to your Ranla account.

Base URL: https://api.ranla.ai

Authentication

Authorization: Bearer rnl_…

Requires a full-scope API key (or dashboard session). Sending-scoped keys cannot manage suppressions.

Behavior

• Emails are stored normalized lowercase.
• Hard bounces, permanent SMTP delivery failures (e.g. invalid mailbox / 5xx), and complaint-like events auto-add suppressions (source: bounce / complaint).
• Managed unsubscribe links add suppressions with source: unsubscribe.
• POST /emails checks to / cc / bcc before sending. If any recipient is suppressed, the API returns 422 with code: validation_error, details.suppressed, and emits email.suppressed (a suppressed email record is created).

List

GET /suppressions

Query: limit, cursor, optional email.

{
  "data": [
    {
      "id": "…",
      "email": "[email protected]",
      "reason": "550 user unknown",
      "source": "bounce",
      "created_at": "2026-07-26T12:00:00.000Z",
      "updated_at": "2026-07-26T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Add

POST /suppressions

{ "email": "[email protected]", "reason": "manual opt-out" }

source is set to api. Upserts on (account, email).

Remove

DELETE /suppressions/{id}

or

DELETE /[email protected]

{ "ok": true }

SDK

import { Ranla } from '@supersend/ranla'

const client = new Ranla(process.env.RANLA_API_KEY!)

await client.suppressions.create({ email: '[email protected]', reason: 'opt-out' })
const { data } = await client.suppressions.list()
await client.suppressions.remove('[email protected]')

CLI

supersendtx suppressions list
supersendtx suppressions add --email [email protected] --reason "opt-out"
supersendtx suppressions remove --email [email protected]

OpenAPI

openapi/supersendtx.yaml