ComRaidComRaid Docs

Segments

Saved, reusable Segments defined by rules over Contact attributes, locale/timezone, endpoints, and Communication preferences.

Overview

A Segment is a named set of rules over your Project's Contacts. When you create a Message with targeting.segment_id, ComRaid keeps that Segment's rules from creation time; who matches is worked out when the Message sends. Preview size with targeting preview. Contacts who cannot receive (Opted out, Category preference block, Identity verification not met, Inactive, or no offerable Endpoint) are left out and get no Delivery — they are not recorded as skipped.

Built-in system Segments (IDs prefixed seg_sys_) are provided by ComRaid and cannot be updated or archived through these endpoints. Saved Segments require at least one condition; use Everyone targeting (targeting.everyone or seg_sys_subscribed) when you mean all Contacts who can receive.

Built-in Segments

Glossary nameWire idDefinition
Everyoneseg_sys_subscribedAt least one Active Endpoint and not Opted out
New contacts (subscribed in the last 7 days)seg_sys_newIn Everyone, and Contact first-seen within 7 days (imports keep the original first-seen)
Recently activeseg_sys_activeAn Active Endpoint seen in the last 7 days
Engagedseg_sys_engagedRecently active and 3 or more sessions
Dormantseg_sys_dormantActive Endpoints, none seen in the last 7 days (including never seen)
Android contactsseg_sys_androidContacts with an Active Android Endpoint; also limits Message devices to Android
iOS contactsseg_sys_iosContacts with an Active iOS Endpoint; also limits Message devices to iOS

Android/iOS builtins limit devices (intersected with any explicit content.push.platforms). Generic endpoint.* rules only pick Contacts — they do not restrict which of a Contact's devices receive the Message.

Rules shape

rules is an object with a top-level operator (and or or) and a list of conditions. Each condition has a field, an op, an optional value, and a key for fields that address a named attribute or category.

{
  "operator": "and",
  "conditions": [
    {"field": "endpoint.is_active", "op": "eq", "value": true},
    {"field": "endpoint.platform", "op": "in", "value": ["android", "ios"]},
    {"field": "contact_attribute", "key": "plan", "op": "eq", "value": "pro"},
    {"field": "contact.locale", "op": "in", "value": ["en", "en-US"]},
    {"field": "contact.last_active", "op": "within", "value": 7},
    {"field": "communication_preference", "key": "orders", "op": "eq", "value": true}
  ]
}

Fields and operators

  • contact_attribute (requires key) — exists, not_exists, eq, neq, in, and typed gt / gte / lt / lte (numbers and dates only; the server compares by the Attribute's stored type).
  • contact.locale, contact.timezone, contact.language, contact.country — exists, not_exists, eq, neq, in.
  • contact.last_active, contact.first_seen — exists, not_exists, eq, neq, gt, gte, lt, lte (RFC3339), plus within / not_within with a positive integer day count.
  • endpoint.platform — eq, in (values android, ios).
  • endpoint.is_active — eq (boolean value).
  • endpoint.current_app_version, endpoint.first_app_version — eq, in only (ordered comparison is not supported).
  • endpoint.os, endpoint.os_version, endpoint.model, endpoint.sdk_version — exists, not_exists, eq, neq, in.
  • endpoint.session_count — exists, not_exists, eq, neq, gt, gte, lt, lte.
  • endpoint.last_seen, endpoint.first_seen — exists, not_exists, eq, neq, gt, gte, lt, lte (RFC3339), plus within / not_within.
  • communication_preference (requires key = category slug) — exists, not_exists, eq (boolean). A missing preference row counts as enabled; the rule is evaluated for the push Channel.

One neq rule

neq X matches exactly the Contacts that do not match eq X, for every field. For endpoint.* fields this means no Active Endpoint has X — Contacts with no Endpoint or a null value match.

Create a segment

POST https://api.comraid.io/segments
Authorization: Bearer cr_sk_...
Content-Type: application/json

{
  "name": "Active pro Contacts",
  "description": "Pro-plan Contacts with an active endpoint",
  "rules": {
    "operator": "and",
    "conditions": [
      {"field": "endpoint.is_active", "op": "eq", "value": true},
      {"field": "contact_attribute", "key": "plan", "op": "eq", "value": "pro"}
    ]
  }
}

Returns 201 Created with the new segment_id, status, and updated_at.

{
  "segment_id": "b2f4c1a0-3d5e-4a71-9c2b-8e0f1d2a3b4c",
  "status": "active",
  "updated_at": "2026-11-11T00:00:00Z"
}

Rules must include at least one condition (use Everyone targeting for all Contacts). At most 50 conditions and 1,000 values per in list. An empty name is 400. A name already used by an active Segment returns 409 with code segment_name_taken.

List segments

GET https://api.comraid.io/segments
Authorization: Bearer cr_sk_...

Returns the Project's active Segments (each includes updated_at). Pass include_archived=true to include archived Segments:

GET https://api.comraid.io/segments?include_archived=true
Authorization: Bearer cr_sk_...

Get a segment

GET https://api.comraid.io/segments/{id}
Authorization: Bearer cr_sk_...

Response includes updated_at, live contact_count (Contacts who can receive), and scheduled_message_count.

Update a segment

Omitted fields keep their current values. Send only the fields you want to change. Empty name is 400. Saving rules with zero conditions is 400 (use Everyone). Renaming onto another active Segment's name returns 409 segment_name_taken.

PUT https://api.comraid.io/segments/{id}
Authorization: Bearer cr_sk_...
Content-Type: application/json

{
  "description": "Updated definition",
  "rules": {
    "operator": "or",
    "conditions": [
      {"field": "contact_attribute", "key": "plan", "op": "in", "value": ["pro", "team"]}
    ]
  }
}

Archive and restore

Deleting a Segment archives it (soft delete: status=archived and archived_at). Restore clears the archive and returns it to active. Labels stay Archive / Restore — this is not a deactivate of recipients or queued work.

  • Archived Segments remain readable by id. Public GET /segments hides them by default; pass include_archived=true to include them.
  • New sends and targeting previews that pass an archived targeting.segment_id are rejected until the Segment is restored.
  • Archived Segments cannot be updated until restored.
  • Restoring when another active Segment already has the same name returns 409 segment_name_taken.
  • A scheduled Notification that referenced the Segment keeps its rules from when it was created. Archiving does not cancel or rewrite already-scheduled sends.
DELETE https://api.comraid.io/segments/{id}          # archive
POST   https://api.comraid.io/segments/{id}/restore  # restore

Notes

  • Segments are scoped to the Project resolved from your API key; you cannot read or write another Project's Segments.
  • Use a Segment in a send via targeting.segment_id — see Notifications.
  • Full schemas: API Reference.

On this page