Delete a topic

Remove a topic, and every subscription recorded against it.

DELETE /v1/topics/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The topic id.

Example

curl

curl -X DELETE "https://api.sendgrail.com/v1/topics/$TOPIC_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

await fetch(`https://api.sendgrail.com/v1/topics/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
});

Response

{
  "object": "topic",
  "id": "7b2e6f90-3c11-4a5d-9b8e-1f0c4d6a2e59",
  "deleted": true
}

A scheduled broadcast blocks the delete

If a broadcast is scheduled or already sending and is scoped to this topic, the delete is refused with 409:

{
  "message": "A scheduled or sending broadcast is scoped to this topic. Cancel it first.",
  "code": "topic_in_use",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

Allowing it would strip that broadcast of the very filter deciding who consented to receive it — and the send would then reach people who had opted out of exactly this. Cancel the broadcast first.

The contacts survive; their choices about this topic don't

Deleting a topic does not delete a single contact. Nobody is unsubscribed globally, nobody leaves your audience, and every other topic they subscribe to is untouched.

What does go is the subscription state for this topic. Every "yes" and every "no" a contact recorded against it is deleted with it. That matters because those "no"s were opt-outs: if you delete a topic and later create a new one with the same name, it is a new topic with a new key and no memory of who had left. The people who once opted out will be treated as having made no choice at all — and if the new topic's default_mode is opt_out, they are back in.

Unsubscribe links pointing at the deleted topic's key stop resolving, since the key goes with the topic.

If you only want to stop sending a topic, stop sending it and leave it in place; that preserves the opt-outs. Deleting is for when the category itself is gone for good.

A topic belonging to another team answers 404, not 403 — an id that isn't yours is an id that doesn't exist, as far as your key is concerned. A Sending-access key answers 403. See Errors.