Star
API reference

Suppressions and unsubscribe

A suppressed address is never contacted again on that channel, whatever the priority. Unsubscribes, spam complaints and hard bounces add addresses automatically.

List suppressions

GET/v1/suppressions

Auth: Project key, or the admin key or a session with x-project-id.

Newest first. source is the provider channel, api or unsubscribe-link. taskId is set when a provider webhook added it.

Query parameters

NameTypeDefaultDescription
limitnumber1001 to 500.
channelstringOnly this channel.
reasonstringunsubscribed, complained, bounced or manual.
targetstringSubstring of the address.

Responses

{
  "suppressions": [
    {
      "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b",
      "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "channel": "email",
      "target": "[email protected]",
      "reason": "unsubscribed",
      "source": "unsubscribe-link",
      "taskId": null,
      "createdAt": "2026-11-16T18:22:41.007Z"
    },
    {
      "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b9c",
      "projectId": "b2a4c1d0-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "channel": "email",
      "target": "[email protected]",
      "reason": "bounced",
      "source": "email",
      "taskId": "7e0d3f2a-1b4c-4d5e-8f60-7a8b9c0d1e2f:41a9e6b2-3c4d-4e5f-9a6b-7c8d9e0f1a2b",
      "createdAt": "2026-11-15T07:02:13.590Z"
    }
  ]
}
{
  "suppressions": []
}
Common errors (401, 400, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl "http://localhost:3000/v1/suppressions?target=alice" -H "Authorization: Bearer $NK_KEY"
const { suppressions } = await notifkit.listSuppressions({ target: "alice" });

Suppress an address

POST/v1/suppressions

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

For opt-outs a provider can't see, like a reply asking to be removed. Emails are stored lower-cased. Suppressing an address twice keeps the first reason, and still answers 201 with the reason you sent.

Body

FieldTypeRequiredDescription
channelstringyes
targetstringyesThe address.
reasonstringnoDefault manual.

Responses

{
  "channel": "email",
  "target": "[email protected]",
  "reason": "manual"
}
{
  "error": "validation_error",
  "issues": [
    {
      "path": "reason",
      "message": "Invalid option: expected one of \"unsubscribed\"|\"complained\"|\"bounced\"|\"manual\""
    }
  ]
}
Common errors (401, 400, 403, 429, 413, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "forbidden",
  "message": "API key is read-only"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "malformed_json",
  "message": "malformed_json"
}
{
  "error": "payload_too_large",
  "message": "payload_too_large"
}
{
  "error": "internal_error"
}

Example

curl -X POST http://localhost:3000/v1/suppressions \
  -H "Authorization: Bearer $NK_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "email", "target": "[email protected]" }'
await notifkit.createSuppression({ channel: "email", target: "[email protected]" });

Remove a suppression

DELETE/v1/suppressions/{channel}/{target}

Auth: Project key with the admin role, or the admin key or a writable session with x-project-id.

Re-enables sending to the address. Only do this when the person asks. Answers 204 even when nothing matched.

Path parameters

NameTypeDescription
channelstring
targetstringURL-encoded address.

Responses

204 No Content Removed, or there was nothing to remove. No body.

Common errors (401, 400, 403, 429, 500)
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
{
  "error": "bad_request",
  "message": "x-project-id header or projectId query param required when using admin token"
}
{
  "error": "forbidden",
  "message": "API key is read-only"
}
{
  "error": "too_many_requests",
  "message": "Project rate limit exceeded (max 600 req/min)"
}
{
  "error": "internal_error"
}

Example

curl -X DELETE "http://localhost:3000/v1/suppressions/email/alice%40example.com" -H "Authorization: Bearer $NK_KEY"
await notifkit.deleteSuppression("email", "[email protected]");

Unsubscribe page

GET/v1/unsubscribe

Auth: None.

The page behind the unsubscribe link in an email. It only shows a confirm button, because mail scanners open every link. Links are added to email whose template has a topic, when PUBLIC_URL and UNSUBSCRIBE_SECRET are set. Responses are HTML pages, shown here by title and text.

Query parameters

NameTypeDefaultDescription
tokenstringSigned token from the link.

Responses

Unsubscribe
Stop sending marketing messages to [email protected]?
[Unsubscribe]
Unsubscribe
Stop sending all messages to [email protected]?
[Unsubscribe]
This link is not valid
It may have been altered in transit, or this server may have been reconfigured since the message was sent. Replying to the message and asking to be removed will still work.
{
  "error": "too_many_requests"
}
Common errors (500)
{
  "error": "internal_error"
}

Unsubscribe

POST/v1/unsubscribe

Auth: None.

Applies the opt-out. Serves the page's button and RFC 8058 one-click unsubscribe from mail clients, and ignores any body. If the template had topics, the user is opted out of those topics only. Otherwise, or if the user no longer exists, the address is suppressed.

Query parameters

NameTypeDefaultDescription
tokenstringSigned token from the link.

Responses

You're unsubscribed
We've stopped sending these messages to [email protected]. It may take a few minutes to take effect for mail already on its way.
You're unsubscribed
We've stopped sending messages to [email protected]. It may take a few minutes to take effect for mail already on its way.
This link is not valid
It may have been altered in transit, or this server may have been reconfigured since the message was sent.
{
  "error": "too_many_requests"
}
Something went wrong
We could not record that just now. Please try again in a moment.
Common errors (500)
{
  "error": "internal_error"
}