Audiences: Segmentation

An audience is a group of contacts defined by rules. Use audiences to segment your contacts for targeted campaigns and flows.

Create an Audience

Define an audience using filtering rules.

cURL

curl -X POST https://api.tratto.email/v1/audiences \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":"VIP Newsletter Subscribers",
    "rules":[
      {"field":"status","operator":"equals","value":"subscribed"},
      {"field":"tags","operator":"array_contains","value":"vip"}
    ]
  }'

Response:

{
  "data": {
    "id": "aud_abc123"
  }
}

rules-based audiences are materialized asynchronously right after creation — fetch GET /v1/audiences/{id} a moment later for the resolved contactCount.

Rule Types

Every rule is { field, operator, value }. Available operators: equals, not_equals, contains, not_contains, array_contains.

contains/not_contains/array_contains compare strings case-insensitively.

Multiple Rules (AND Logic)

All rules must match:

{
  "rules": [
    {"field": "status", "operator": "equals", "value": "subscribed"},
    {"field": "tags", "operator": "array_contains", "value": "newsletter"}
  ]
}

This audience includes contacts that are:

• Status: subscribed AND
• Have tag: newsletter

Add Contacts Manually

In addition to rules, manually add specific contacts.

cURL

curl -X POST https://api.tratto.email/v1/audiences/aud_abc123/contacts \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds":["cont_abc123","cont_def456"]
  }'

Response:

{
  "data": {
    "added": 2,
    "alreadyInAudience": 0,
    "notFound": 0
  }
}

Dynamic vs Static

• Dynamic (has rules): membership is reconciled automatically on every contact create/update/delete — a contact that starts (or stops) matching an audience's rules is added to (or removed from) it right away, no manual action needed.
• Static (no rules, contacts added via the endpoint above): fixed list, never changes on its own.

An audience is dynamic if it has rules, static otherwise — there's no separate type field, it's inferred from whether rules is empty.

List Audiences

Get all audiences for your tenant.

cURL

curl https://api.tratto.email/v1/audiences \
  -H "Authorization: Bearer tratto_live_..."

Get Audience Details

Retrieve a specific audience.

cURL

curl https://api.tratto.email/v1/audiences/aud_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Response:

{
  "data": {
    "id": "aud_abc123",
    "name": "VIP Newsletter Subscribers",
    "description": "",
    "rules": [...],
    "contactCount": 1250,
    "createdAt": "2025-06-30T12:00:00Z"
  }
}

Delete an Audience

Permanently deletes the audience itself. Contacts are never touched: deleting an audience just removes that grouping; every contact that was a member keeps existing untouched, with all its data, tags and status intact.

cURL

curl -X DELETE https://api.tratto.email/v1/audiences/aud_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Returns 204 No Content on success.

If the audience is still referenced by a campaign that hasn't finished sending (draft, scheduled, sending or paused), the request is rejected with 409 Conflict instead. Remove the audience from those campaigns first, or wait until they complete.

Using Audiences in Campaigns

Send a campaign to an entire audience.

cURL

curl -X POST https://api.tratto.email/v1/campaigns \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Q3 VIP Offer",
    "templateId":"tmpl_abc123",
    "audienceId":"aud_abc123"
  }'

Using Audiences in Flows

Trigger a flow when a contact joins an audience.

{
  "name": "Welcome VIP",
  "trigger": {
    "type": "contact_joins_audience",
    "audienceId": "aud_abc123"
  },
  "steps": [...]
}

See Flows for details.

Next Steps

• Send to an audience? Go to Campaigns
• Trigger flows on audience join? See Flows
• Tag contacts? Go back to Contacts