Segments

A segment is a saved filter over one audience: "customers tagged vip who opened something in the last 90 days", for example. A campaign created with a segment_id mails only the people the segment matches, and the same definition can be reused across campaigns and counted before anything is sent. See Campaigns.

A segment stores its rules, not its members. Every time it is used, whether by counting it, listing its contacts or sending a campaign, it is evaluated again against the contacts as they are at that moment. Engagement windows are measured back from the moment of evaluation, so the same segment matches different people on different days. A campaign freezes its recipient list when it starts sending, so a running campaign is not affected by later changes.

How a segment matches

A contact matches when every one of these holds:

1. They are on the segment's audience (audience_id is in their audience_ids).
2. Their unsubscribed flag is false.
3. Every rule the segment sets is satisfied. Rules left unset do not filter. Rules combine with AND; there is no OR between rules.

Tags in tags and exclude_tags are normalised when the segment is saved, the same way contact tags are: trimmed, lower-cased, runs of whitespace turned into a hyphen and cut to 60 characters.

Suppressions are not consulted when a segment is evaluated, only the unsubscribed flag. They are enforced when mail is sent, so a count can include an address that will be skipped at send time.

topic_key is checked when you save: a key that names no topic in the workspace is refused with 422 unknown_topic. The property in a filter is not checked against what contacts carry. A typo there is stored as written and quietly matches nobody (or, for not_equals and not_exists, everybody). Count the segment after creating it. A property that no contact can carry, because it is empty, contains . or a null character, or starts with $, is refused with 422.

Property filters

Each entry in properties tests one value in a contact's attributes.

gt and lt only compare values of the same kind: a number with a number, a string with a string. Strings compare character by character, so "9" is greater than "42". This is why a property's type matters: declare numeric properties as number so imported values are stored as numbers, and store dates as ISO 8601 strings so they sort in time order.

The segment object

Every field is always present. A rule that is not set is null, or [] for the list rules, so creating, retrieving, listing and updating a segment all return exactly the same fields.

{
  "id": "4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58",
  "key": "active-pro",
  "name": "Active Pro customers",
  "audience_id": "b7e2c1d4-6a3f-4e8b-9c5d-1f2a3b4c5d6e",
  "opened_within_days": 90,
  "clicked_within_days": null,
  "exclude_unengaged_days": null,
  "engaged_within_days": null,
  "properties": [
    { "property": "plan", "operator": "equals", "value": "pro" },
    { "property": "seats", "operator": "gt", "value": 3 }
  ],
  "tags": ["customer"],
  "exclude_tags": ["churned"],
  "topic_key": "product-updates",
  "created_at": "2026-09-10T09:00:00.000Z",
  "updated_at": null
}

List segments

GET /v1/segments · requires contacts:read

Every segment in the workspace, sorted by name, up to 500. There is no paging: next_cursor is always null, and has_more is true when 500 segments came back, which means there may be more than this endpoint can return.

Example

curl https://api.sendraven.ai/v1/segments \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58",
      "key": "active-pro",
      "name": "Active Pro customers",
      "audience_id": "b7e2c1d4-6a3f-4e8b-9c5d-1f2a3b4c5d6e",
      "opened_within_days": 90,
      "clicked_within_days": null,
      "exclude_unengaged_days": null,
      "engaged_within_days": null,
      "properties": [
        { "property": "plan", "operator": "equals", "value": "pro" },
        { "property": "seats", "operator": "gt", "value": 3 }
      ],
      "tags": ["customer"],
      "exclude_tags": ["churned"],
      "topic_key": "product-updates",
      "created_at": "2026-09-10T09:00:00.000Z",
      "updated_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Create a segment

POST /v1/segments · requires contacts:write

Saves a segment over one audience. Nothing is evaluated at this point; count it afterwards to check it matches who you expect.

name does not have to be unique, but key does, within the workspace: saving a second segment with a key already in use answers 409 conflict. Keep the returned id, which is what campaigns and every other segment call take.

Body

Example

curl -X POST https://api.sendraven.ai/v1/segments \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "audience_id": "b7e2c1d4-6a3f-4e8b-9c5d-1f2a3b4c5d6e",
    "key": "active-pro",
    "name": "Active Pro customers",
    "tags": ["Customer"],
    "exclude_tags": ["churned"],
    "opened_within_days": 90,
    "properties": [
      { "property": "plan", "operator": "equals", "value": "pro" },
      { "property": "seats", "operator": "gt", "value": 3 }
    ],
    "topic_key": "product-updates"
  }'

Response

201 Created

A segment object. Rules you did not set are null, or [] for the list rules.

{
  "id": "4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58",
  "key": "active-pro",
  "name": "Active Pro customers",
  "audience_id": "b7e2c1d4-6a3f-4e8b-9c5d-1f2a3b4c5d6e",
  "opened_within_days": 90,
  "clicked_within_days": null,
  "exclude_unengaged_days": null,
  "engaged_within_days": null,
  "properties": [
    { "property": "plan", "operator": "equals", "value": "pro" },
    { "property": "seats", "operator": "gt", "value": 3 }
  ],
  "tags": ["customer"],
  "exclude_tags": ["churned"],
  "topic_key": "product-updates",
  "created_at": "2026-09-15T12:00:00.000Z",
  "updated_at": null
}

Errors

Retrieve a segment

GET /v1/segments/{id} · requires contacts:read

Returns one segment's definition. Passing a segment's name or key instead of its id answers 404, and when it matches a segment in the workspace (case-insensitively) the message gives its id.

Path parameters

Example

curl https://api.sendraven.ai/v1/segments/4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58 \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

A segment object.

{
  "id": "4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58",
  "key": "active-pro",
  "name": "Active Pro customers",
  "audience_id": "b7e2c1d4-6a3f-4e8b-9c5d-1f2a3b4c5d6e",
  "opened_within_days": 90,
  "clicked_within_days": null,
  "exclude_unengaged_days": null,
  "engaged_within_days": null,
  "properties": [
    { "property": "plan", "operator": "equals", "value": "pro" },
    { "property": "seats", "operator": "gt", "value": 3 }
  ],
  "tags": ["customer"],
  "exclude_tags": ["churned"],
  "topic_key": "product-updates",
  "created_at": "2026-09-10T09:00:00.000Z",
  "updated_at": null
}

Errors

Update a segment

PATCH /v1/segments/{id} · requires contacts:write

Changes any of a segment's fields. Send only what should change; everything else stays as it was. Each field you send replaces the stored value whole: a properties array replaces every existing filter, and tags replaces the whole tag list.

What an update can and cannot do:

• Clear a list rule by sending an empty array: "tags": [], "exclude_tags": [] or "properties": [].
• Clear the topic rule by sending "topic_key": "". An empty key is treated as no topic, and reads back as null. Any other topic_key must name an existing topic.
• Clear an engagement window by sending null: "opened_within_days": null, "clicked_within_days": null, "exclude_unengaged_days": null or "engaged_within_days": null. It reads back as null.
• key cannot be changed. A body that contains key, even with the current value, is refused with 422 invalid_request (key: a segment's key cannot be changed; create a new segment) and nothing is changed. To use a different key, create a new segment.
• Moving the segment to another audience with audience_id is allowed. A campaign already using the segment is not re-checked, so its segment can then filter a different audience from the campaign's own.

A campaign that has already started sending has frozen its recipients and is not affected by an update.

Path parameters

Body

All fields are optional. Each has the same type and limits as on create.

Example

curl -X PATCH https://api.sendraven.ai/v1/segments/4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58 \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "opened_within_days": 30,
    "exclude_tags": []
  }'

Response

200 OK

The updated segment object, now with updated_at set.

{
  "id": "4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58",
  "key": "active-pro",
  "name": "Active Pro customers",
  "audience_id": "b7e2c1d4-6a3f-4e8b-9c5d-1f2a3b4c5d6e",
  "opened_within_days": 30,
  "clicked_within_days": null,
  "exclude_unengaged_days": null,
  "engaged_within_days": null,
  "properties": [
    { "property": "plan", "operator": "equals", "value": "pro" },
    { "property": "seats", "operator": "gt", "value": 3 }
  ],
  "tags": ["customer"],
  "exclude_tags": [],
  "topic_key": "product-updates",
  "created_at": "2026-09-10T09:00:00.000Z",
  "updated_at": "2026-09-15T12:00:00.000Z"
}

Errors

Delete a segment

DELETE /v1/segments/{id} · requires contacts:write

Deletes the segment's definition. No contacts are touched.

Path parameters

Example

curl -X DELETE https://api.sendraven.ai/v1/segments/4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58 \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "id": "4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58",
  "deleted": true
}

Errors

Get segment metrics

GET /v1/segments/{id}/metrics · requires contacts:read

How many contacts the segment matches right now. Run it before building a campaign around a segment: a filter that matches nobody, or everybody, is much easier to spot here than after a send. The segment is evaluated in full on every call, so on a large audience this is not a cheap request.

Path parameters

Example

curl https://api.sendraven.ai/v1/segments/4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58/metrics \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "id": "4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58",
  "contact_count": 312
}

Errors

List the contacts in a segment

GET /v1/segments/{id}/contacts · requires contacts:read

The email addresses the segment matches right now, one page at a time. data is an array of address strings, not contact objects; look a person up with GET /v1/contacts?email= for the rest.

The list is cursor-paged like every other (pagination): newest contact first, by when the contact was created, the same order as GET /v1/contacts. Pass next_cursor back as cursor while has_more is true. Membership is worked out on each call, so a contact who stops matching (or starts) between two pages drops out of (or joins) the later pages. For the number of matches, use metrics; this list carries no count.

Path parameters

Query parameters

Example

curl "https://api.sendraven.ai/v1/segments/4c9e2a7b-1d3f-4b8e-a6c5-7f2d9e1b3a58/contacts?limit=3" \
  -H "Authorization: Bearer $SENDRAVEN_API_KEY"

Response

200 OK

{
  "object": "list",
  "data": ["ana@example.com", "bo@example.com", "cy@example.com"],
  "has_more": true,
  "next_cursor": "MjAyNi0wOS0xNVQxMjowMDowMC4wMDBafDdmMmQ5ZTFiLTNhNTgtNGM5ZS1hMmI3LTFkM2Y0YjhlYTZjNQ"
}

Errors