API referenceTopics

Topics

The categories contacts subscribe to. A broadcast scoped to a topic reaches only the contacts opted in to it, and the hosted preference page is where they choose.

How a topic decides

Each contact has an effective subscription to every topic: their own choice where one was recorded, and the topic's default_subscription otherwise. A broadcast with a topic_id goes only to contacts whose effective subscription is opt_in.
default_subscription is fixed at creation. Changing it would silently flip everyone who never chose, so the API refuses rather than asking you to be careful.
A public topic is listed on every contact's preference page. A private one appears only for contacts already opted in — for a list people join somewhere else and should be able to leave here.
A global unsubscribe wins over every topic: a contact with unsubscribed: true receives nothing, whatever their choices say.

Every choice — from the API, an import, the preference page or a one-click unsubscribe — writes a consent record with its source, time and, where there was one, the IP address and user agent. Records are kept for three years and survive the contact's erasure with a hash of the address, which is what lets an opt-out be proven later.

Endpoints

Create a topic

POST /topics

A category contacts subscribe to, with a default for those who never chose.

Body

namestringRequired
Up to 50 characters, unique among live topics.
default_subscriptionstringRequired
opt_in or opt_out: what a contact with no explicit choice is treated as. Fixed after creation.
descriptionstring
Up to 200 characters, shown on the preference page.
visibilitystring
public lists the topic on every contact's preference page; private (the default) only for contacts already opted in.

Request

curl -X POST "https://api.rasket.com/topics" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Product updates",
  "description": "What shipped this month.",
  "default_subscription": "opt_in",
  "visibility": "public"
}'

const response = await fetch("https://api.rasket.com/topics", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Product updates",
    description: "What shipped this month.",
    default_subscription: "opt_in",
    visibility: "public"
  }),
});

const { id } = await response.json();

import os

import requests

response = requests.post(
    "https://api.rasket.com/topics",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "name": "Product updates",
    "description": "What shipped this month.",
    "default_subscription": "opt_in",
    "visibility": "public"
  },
)

id = response.json()["id"]

Response 201

{
  "object": "topic",
  "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17"
}

A live topic with the same name is 422 invalid_parameter.
A broadcast scoped to a topic goes only to contacts whose effective subscription to it is opt_in.

List topics

GET /topics

Every live topic, newest first.

Query parameters

limitinteger
How many items to return, 1–100. Defaults to 20.
afterstring
Return the page that follows this item ID. Mutually exclusive with before.
beforestring
Return the page that precedes this item ID. Mutually exclusive with after.

Request

curl -X GET "https://api.rasket.com/topics" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/topics", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const data = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/topics",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

print(response.json())

Response 200

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
      "name": "Product updates",
      "description": "What shipped this month.",
      "default_subscription": "opt_in",
      "visibility": "public",
      "created_at": "2026-09-08T22:22:17.595Z"
    }
  ]
}

Retrieve a topic

GET /topics/{id}

One topic by ID.

Path parameters

idstringRequired
The topic's ID.

Request

curl -X GET "https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const { id } = await response.json();

import os

import requests

response = requests.get(
    "https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

id = response.json()["id"]

Response 200

{
  "object": "topic",
  "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
  "name": "Product updates",
  "description": "What shipped this month.",
  "default_subscription": "opt_in",
  "visibility": "public",
  "created_at": "2026-09-08T22:22:17.595Z"
}

Update a topic

PATCH /topics/{id}

Change the name, description or visibility.

Path parameters

idstringRequired
The topic's ID.

Body

namestring
Up to 50 characters.
descriptionstring | null
null clears it.
visibilitystring
public or private.

Request

curl -X PATCH "https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0" \
  -H "Content-Type: application/json" \
  -d '{
  "visibility": "private"
}'

const response = await fetch("https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    visibility: "private"
  }),
});

const { id } = await response.json();

import os

import requests

response = requests.patch(
    "https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
    json={
    "visibility": "private"
  },
)

id = response.json()["id"]

Response 200

{
  "object": "topic",
  "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17"
}

default_subscription cannot change: a body that carries it is 422 invalid_parameter. Changing it would silently resubscribe or unsubscribe everyone who never chose.

Delete a topic

DELETE /topics/{id}

Retire the topic and free its name.

Path parameters

idstringRequired
The topic's ID.

Request

curl -X DELETE "https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17" \
  -H "Authorization: Bearer $RASKET_API_KEY" \
  -H "User-Agent: acme-billing/1.0"

const response = await fetch("https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.RASKET_API_KEY}`,
    "User-Agent": "acme-billing/1.0",
  },
});

const { id } = await response.json();

import os

import requests

response = requests.delete(
    "https://api.rasket.com/topics/0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
    headers={
        "Authorization": f"Bearer {os.environ['RASKET_API_KEY']}",
        "User-Agent": "acme-billing/1.0",
    },
)

id = response.json()["id"]

Response 200

{
  "object": "topic",
  "id": "0199d2f1-4c4e-7a20-9c31-6f2b8a0e5d17",
  "deleted": true
}

The topic is 404 from that moment. Emails and consent records that name it keep doing so.

How a topic decides

Consent

Endpoints

POST /topics

Body

Request

Response 201

GET /topics

Query parameters

Request

Response 200

GET /topics/{id}

Path parameters

Request

Response 200

PATCH /topics/{id}

Path parameters

Body

Request

Response 200

DELETE /topics/{id}

Path parameters

Request

Response 200