Agent-readable docs index: /docs/llms.txt. Full docs in one file: /docs/llms-full.txt. Download /docs/docs.zip to grep all markdown files locally.

Build and publish dynamic audience segments

Segments define reusable audiences with rules. A segment can query all contacts or selected source lists, evaluate channel eligibility, and supply an audience to an email, SMS, or WhatsApp campaign. Creating or previewing a segment sends no messages.

Build a definition

  1. Open Segments and create a draft with a meaningful name, description, and purpose.
  2. Choose the source: all contacts or selected contact lists.
  3. Add all/any rule groups, including nested conditions where needed.
  4. Use supported data: contact fields, tags, registered custom attributes, list, consent, suppression, reachability, email engagement, campaign receipts, or form submissions.
  5. Check typed values, particularly dates, numbers, booleans, and missing data.
Rules query actual stored data. A custom field must be populated consistently for meaningful matches. Choosing a field type for a condition does not retroactively repair imported values.

Preview the audience

Preview runs in the background and reports status, matching counts, channel eligibility, exclusion categories, samples, and evaluation time. Refresh a stale preview and investigate failure states before publishing.
Counts do not reserve capacity. Preview does not certify sender readiness, domain state, wallet funds, organisational sending status, or current provider limits. Delivery rechecks the relevant rules and preferences.

Publish and use a version

Review the draft and confirm purpose before publishing. Published definitions are immutable. Edits create another draft version; an existing campaign pins the published definition when sending starts, so a later edit cannot silently change it.
Use one channel per segment campaign. Select the appropriate sender and content, then review excluded contacts. Marketing eligibility requires affirmative channel consent and honors suppression.

API workflow

Use segments:read and/or segments:write and the public segment ID. Supported actions include list, create, show, update, preview, evaluate, versions, usage, publish, and archive.
{
  "segment": {
    "name": "Subscribed customers in Lagos",
    "purpose": "marketing",
    "source": {"type": "all"},
    "rules": {
      "logic": "and",
      "rules": [
        {"field": "city", "operator": "equals", "value": "Lagos"},
        {"field": "consent.email", "operator": "is_true"}
      ]
    }
  }
}
Preview: POST /api/v1/segments/preview, then poll GET /api/v1/segments/preview?evaluation_id=sev_... until completed or failed. Publish: POST /api/v1/segments/:public_id/publish with the reviewed version_id and purpose_confirmed.
Next: launch a campaign or build a segment-triggered automation.
Automation segment-entry triggers use the current automation engine. A cached segment count is not an execution history or conversion report.