Build an Audience

This tutorial walks through creating a targeted audience using natural language, previewing its membership, refining the criteria, and targeting a send.

Step 1: Create the Audience

Describe your target audience in plain English. The platform translates the description into SQL-based audience criteria.

Tool: audiences.create_from_description


{
  "tool": "audiences.create_from_description",
  "input": {
    "brand_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "BPC-157 Re-engagement",
    "description": "Customers who purchased BPC-157 in the last 30 days and have not opened an email in 2 weeks",
    "tags": ["re-engagement", "bpc-157"]
  }
}

Response:


{
  "ok": true,
  "data": {
    "segment_id": "aud_abc123",
    "name": "BPC-157 Re-engagement",
    "estimated_size": 1247,
    "status": "draft"
  }
}

Step 2: Preview the Audience

Check the audience size and review sample members before using it in a send.

Tool: audiences.preview


{
  "tool": "audiences.preview",
  "input": {
    "segment_id": "aud_abc123",
    "sample_size": 5
  }
}

Response:


{
  "ok": true,
  "data": {
    "total_size": 1247,
    "sample": [
      { "person_id": "p_001", "email": "jane@example.com" },
      { "person_id": "p_002", "email": "john@example.com" },
      { "person_id": "p_003", "email": "alex@example.com" }
    ]
  }
}

Step 3: Refine the Audience

If the audience is too broad or too narrow, update the description to adjust the criteria.

Tool: audiences.update


{
  "tool": "audiences.update",
  "input": {
    "segment_id": "aud_abc123",
    "description": "Customers who purchased BPC-157 in the last 60 days, have not opened an email in 3 weeks, and are in the US"
  }
}

Response:


{
  "ok": true,
  "data": {
    "segment_id": "aud_abc123",
    "estimated_size": 892,
    "status": "draft"
  }
}

Step 4: Target a Send

Now use the audience in a send. Draft a send that pairs the audience with a template.

Tool: sends.draft


{
  "tool": "sends.draft",
  "input": {
    "name": "BPC-157 Re-engagement Campaign",
    "brand_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "template_id": "tpl_reengagement01",
    "audience_id": "aud_abc123",
    "channel": "email"
  }
}

Response:


{
  "ok": true,
  "data": {
    "send_id": "snd_def456",
    "status": "draft",
    "estimated_recipients": 892
  }
}

What Happens Next

From here you can:

Preview the send with sends.preview to check the rendered content
Test with sends.test to send a proof to your team
Schedule with sends.schedule to set a delivery time