Segments API

The segment object

matching_count is how many subscribed members the definition matches now.

{
  "object": "segment",
  "id": "nwsseg_abc123",
  "audience_id": "aud_abc123",
  "name": "Founders",
  "definition": {
    "match": "all",
    "rules": [
      { "kind": "merge_field", "field": "role", "operator": "equals", "value": "founder" },
      { "kind": "last_sign_of_life", "operator": "within_days", "value": 90 }
    ]
  },
  "matching_count": 128,
  "created_at": "2026-11-03T09:00:00.000Z",
  "updated_at": "2026-11-03T09:00:00.000Z"
}

List and get segments

The list returns { data: [segment] }, sorted by name and not paginated. An audience or segment outside your organization answers 404, and a key limited to other audiences gets a 403.

Create and update a segment

Create takes a name (1 to 120 characters, unique within the audience, or a 409) and a definition, and answers 201. It accepts an Idempotency-Key. Update takes either field or both; an omitted field keeps its value. An issue already scheduled keeps the membership fixed when it was scheduled.

A definition has match (all rules or any rule) and 1 to 10 rules:

• merge_field: a field of lowercase letters, digits and underscores, with equals, not_equals, contains or not_contains and a value compared without case, or is_set and is_not_set with no value. Negative rules only match fields that have a value.
• join_date: before, after, on_or_before or on_or_after a YYYY-MM-DD day in UTC.
• engagement_tier: is or is_not engaged, cooling, cold, dormant or not_enough_data.
• last_sign_of_life: within_days or not_within_days, 1 to 3650 days. A subscriber with no sign of life ever matches not_within_days.
• issues_received: at_least or at_most, 0 to 100,000 newsletters.

Delete a segment

Answers 204. A newsletter that sends to the segment holds it, whatever its status, sent issues included: the delete answers 409 and nothing changes. A block limited to the segment does not hold it. The delete succeeds, an unsent draft then fails the Block segments preflight check and cannot be scheduled until you change the block, and an issue already scheduled keeps the membership fixed when it was scheduled.

SDKs, CLI and MCP

const segment = await shipmail.audiences.segments.create("aud_abc123", {
  name: "Founders",
  definition: {
    match: "all",
    rules: [{ kind: "merge_field", field: "role", operator: "equals", value: "founder" }],
  },
});
const { data } = await shipmail.audiences.segments.list("aud_abc123");
await shipmail.audiences.segments.update("aud_abc123", segment.id, { name: "All founders" });
await shipmail.audiences.segments.delete("aud_abc123", segment.id);

segment = client.audiences.segments.create(
    "aud_abc123",
    {
        "name": "Founders",
        "definition": {
            "match": "all",
            "rules": [{"kind": "merge_field", "field": "role", "operator": "equals", "value": "founder"}],
        },
    },
)
client.audiences.segments.update("aud_abc123", segment["id"], {"name": "All founders"})

shipmail audiences segments list aud_abc123
shipmail audiences segments create aud_abc123 --name Founders --definition @segment.json
shipmail audiences segments update aud_abc123 nwsseg_abc123 --name "All founders"
shipmail audiences segments delete aud_abc123 nwsseg_abc123

MCP tools: shipmail_list_audience_segments, shipmail_create_audience_segment, shipmail_get_audience_segment, shipmail_update_audience_segment and shipmail_delete_audience_segment.