Create a segment

A saved filter over one audience's contacts. A broadcast can be sent to a segment instead of the whole audience, and the people it matches are worked out when each batch is sent, so late changes to a contact count. Each rule has a field (email, first_name, last_name, status, created_at, property with a key, or topic with a topic_id), an op and usually a value. Text operators: equals, not_equals, contains, not_contains, starts_with, ends_with, is_set, is_not_set (case-insensitive). Number properties also take gt, gte, lt, lte. status is subscribed or unsubscribed. created_at takes before or after with a date, or within_days or older_than_days with a number. topic takes subscribed or not_subscribed. match is all (every rule) or any (at least one). Up to 10 rules.

Required scope: contacts:manage

Request body

Unknown fields are rejected, so a typo never silently does nothing.

Example

curl -X POST 'https://api.sendsend.email/v1/segments' \
  -H "Authorization: Bearer $SENDSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "audience_id": "aud_7Qe2…",
  "name": "Pro customers",
  "match": "all",
  "rules": [
    {
      "field": "property",
      "key": "plan",
      "op": "equals",
      "value": "pro"
    },
    {
      "field": "status",
      "op": "is",
      "value": "subscribed"
    }
  ]
}'

Response 201

{
  "id": "seg_Pm4…",
  "object": "segment",
  "audience_id": "aud_7Qe2…",
  "name": "Pro customers",
  "match": "all",
  "rules": [
    {
      "field": "property",
      "key": "plan",
      "op": "equals",
      "value": "pro"
    },
    {
      "field": "status",
      "op": "is",
      "value": "subscribed"
    }
  ],
  "created_at": "2026-10-06T15:00:00.000Z",
  "updated_at": "2026-10-06T15:00:00.000Z"
}

Errors

Every error has the same shape. See Errors.