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.

create audience and import contacts
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.

create a segment
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 preview

Topic 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.