Audiences
Contact lists for broadcasts. Dashboard-session endpoints.
Audiences
POST /audiences
GET /audiences
DELETE /audiences/:id
POST /audiences {"name": "Newsletter"}
-> {"id": "aud_...", "name": "Newsletter", "contact_count": 0, "created_at": "..."}Contacts
GET /audiences/:id/contacts
POST /audiences/:id/contacts
PATCH /audiences/:id/contacts/:contact_id
DELETE /audiences/:id/contacts/:contact_id
| Field | Type | Description |
|---|---|---|
| emailrequired | string | Unique within the audience; stored lowercased. |
| first_name / last_name | string | Used by broadcast {{variables}}. |
| unsubscribed | boolean | Unsubscribed contacts are skipped by broadcasts. Default false. |
| properties | object | Custom key/value pairs — usable in segments and as broadcast {{placeholders}}. |
Adding an address already in the audience returns 400. On PATCH, properties is merged into the existing set; send a key with a null value to delete it. Updates fire the contact.updated webhook.
Segments
GET /audiences/:id/segments
POST /audiences/:id/segments
PUT /audiences/:id/segments/:segment_id
DELETE /audiences/:id/segments/:segment_id
GET /audiences/:id/segments/:segment_id/contacts
A segment is a saved, ANDed filter list over the audience's contacts. Fields: email, first_name, last_name, unsubscribed, or properties.<key>. Ops: eq, neq, contains (all case-insensitive), exists, not_exists.
POST /audiences/:id/segments
{"name": "Pro users",
"filters": [{"field": "properties.plan", "op": "eq", "value": "pro"},
{"field": "email", "op": "contains", "value": "@acme.com"}]}
-> {"id": "seg_...", "name": "Pro users", "filters": [...], "contact_count": 42, ...}Pass segment_id when creating a broadcast to send to just the matching contacts — membership is evaluated at send time.
Topics (preference groups)
GET /topics
POST /topics
DELETE /topics/:id
Topics let contacts opt out of a category (“Weekly digest”) without unsubscribing entirely. Tag a broadcast with topic_id: its unsubscribe link becomes topic-scoped (with an “unsubscribe from everything” fallback), and contacts who opted out of that topic are skipped. Opt-outs are visible on the contact as unsubscribed_topics.