Documentation
Contacts, audiences & segments
Contacts, CSV import, segments, double opt-in and topic preferences.
Contacts hold permission-based recipient data: email, name, attributes and marketing unsubscribe state. Audiences group contacts for campaigns. They are separate from transactional suppression, so a marketing unsubscribe does not block a receipt or security notice.
POST /v1/audiences
{ "name": "Product updates", "description": "Opt-in product news" }
POST /v1/contacts
{ "email": "[email protected]", "name": "Ada", "audience_id": "aud_…", "attributes": { "plan": "scale" } }
POST /v1/contacts/import
{ "audience_id": "aud_…", "csv": "email,name,plan
[email protected],Ada,scale" }CSV import reads the first row as headers, requires an email column and stores the remaining columns as attributes. Duplicate emails inside one import are skipped and reported separately. One-click marketing unsubscribes also set the contact’s unsubscribed state.
Double opt-in. An audience can require confirmation from a verified sender. New and imported contacts start as pending, receive a signed confirmation email, and are excluded from campaign snapshots until they confirm. The link expires after seven days; the dashboard can enqueue a resend.
Segments. Save a filter over audience, attributes, source and recent campaign engagement, then target it from a broadcast. Segments are evaluated when the broadcast starts, so the recipient list reflects current contact state. Unsubscribed contacts are excluded unless the segment opts in.
POST /v1/segments
{
"name": "Scale customers who clicked recently",
"audience_id": "aud_…",
"filters": {
"attributes": { "plan": "scale" },
"source": "api",
"clicked_within_days": 30
}
}
GET /v1/segments/seg_… # count and contact previewTopic preferences. A broadcast can carry a topic such as product-updates. Campaign email includes a signed preference link; contacts can switch individual topics off or stop marketing email entirely without affecting security and account messages. Topic opt-outs are applied at snapshot time and re-checked immediately before sending.
Need the full API surface? OpenAPI 3.1.