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 name | Wire id | Definition |
|---|---|---|
| Everyone | seg_sys_subscribed | At least one Active Endpoint and not Opted out |
| New contacts (subscribed in the last 7 days) | seg_sys_new | In Everyone, and Contact first-seen within 7 days (imports keep the original first-seen) |
| Recently active | seg_sys_active | An Active Endpoint seen in the last 7 days |
| Engaged | seg_sys_engaged | Recently active and 3 or more sessions |
| Dormant | seg_sys_dormant | Active Endpoints, none seen in the last 7 days (including never seen) |
| Android contacts | seg_sys_android | Contacts with an Active Android Endpoint; also limits Message devices to Android |
| iOS contacts | seg_sys_ios | Contacts 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(requireskey) —exists,not_exists,eq,neq,in, and typedgt/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), pluswithin/not_withinwith a positive integer day count.endpoint.platform—eq,in(valuesandroid,ios).endpoint.is_active—eq(booleanvalue).endpoint.current_app_version,endpoint.first_app_version—eq,inonly (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), pluswithin/not_within.communication_preference(requireskey= 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 /segmentshides them by default; passinclude_archived=trueto include them. - New sends and targeting previews that pass an archived
targeting.segment_idare rejected until the Segment is restored. - Archived Segments cannot be updated until restored.
- Restoring when another active Segment already has the same name returns
409segment_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 # restoreNotes
- 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.