Opt many contacts out of this topic in one call, as a background job: the contacts you list (contact_ids or emails, up to 1,000, each a contact of this workspace) or every member of a segment (segment_id, however many; also needs segments:read). Send exactly one. Each contact is opted out as Set a contact's topic preference would: one that was subscribed gets a topic.unsubscribed webhook and an activity row naming your key; one already opted out is left as it is, with no webhook. Suppressions and other topics are untouched, and there is no bulk opt-in. Listed contacts are checked first: the first that isn't one of yours is a 404 naming it (details), and nothing starts. The answer is the job (202, Location); follow it with Retrieve a job. Pass an Idempotency-Key so a retry answers the same job instead of starting another. An email topic's id is a 404 here. Requires the topics:write capability.
Parameters2 fields
Field
Type
Description
idrequired
string · path
—
Idempotency-Key
string · header
Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.
Request body3 fields
Field
Type
Description
contact_ids
string[]
Contacts of this workspace (`con_…`), up to 1,000.
emails
string[]
Contacts of this workspace by email address, up to 1,000.
segment_id
string
Every member of this segment (`seg_…`), however many. Also needs `segments:read`.