ComRaidComRaid Docs
API referenceMessages

Create or schedule a message (Single send, Broadcast, or Draft)

POST
/messages

Authorization

bearerAuth
headerAuthorizationBearer <API key>

Project API key (cr_sk_...)

Header Parameters

Idempotency-Key?string

Project-scoped retry key. Same key + same body replays the stored 202 response. Same key + different body returns 409 idempotency_conflict. Same key while the first request is incomplete returns 409 idempotency_in_progress.

Request Body

application/json
  1. body

Single send uses to.external_user_ids. Broadcast uses targeting with exactly one of everyone, segment_id, or rules. Do not put preview-only platforms on targeting — platform filters for sends live under content.push.platforms. Raw provider tokens are not a public targeting field. to.endpoint_ids is rejected. Set draft: true to save a Draft (title and body required; Segment optional; Broadcast Everyone or segment only; not Data-only).

draft?boolean

When true, save as a Draft (status: draft) instead of sending. Segment may be empty. Limited to push Broadcast Everyone or segment_id.

Defaultfalse
channel*"push"

Required. Only push is accepted in V1.

Value in"push"
to?
targeting?

Broadcast targeting selector for message create. Exactly one of everyone, segment_id, or rules is required. External user ID lists belong on to.external_user_ids (Single send), not here. Does not include preview-only fields such as platforms.

everyone is the Everyone selector (Contacts with at least one Active Endpoint on the Message's Channel who are not Opted out). Built-in Segments use string IDs (seg_sys_*); saved Segments use UUIDs. Glossary names for builtins: Everyone, New contacts, Recently active, Engaged, Dormant, Android contacts, iOS contacts.

category?string
type?string
name?string
priority?string

Default high, or normal when content.push.data_only is true.

Value in"high""normal"
ttl?integer

Time-to-live in seconds from send time (or from send_at when scheduled). Default 86400 (24 hours). Mapped to FCM Android TTL and APNs apns-expiration. 0 means send now and do not store (FCM ttl: 0s, APNs apns-expiration: 0); the worker offers once and does not retry. For TTL greater than 0, Deliveries past expiry are skipped as ttl_expired.

Range0 <= value <= 2419200
collapse_key?string

Collapse key so later sends with the same key replace earlier ones on device. Mapped to FCM collapse_key and APNs apns-collapse-id.

Lengthlength <= 64
data?

Custom push data. Keys must not start with the reserved cr_ prefix.

send_at?|

Absolute UTC send time. Mutually exclusive with send_at_local.

Formatdate-time
send_at_local?|

Local wall-clock datetime without timezone (e.g. 2026-10-22T09:00:00). Delivered when that clock time occurs in each recipient Contact's timezone Property. Contacts without a timezone (or with an invalid IANA name) fall back to UTC. Mutually exclusive with send_at.

content*

Response Body

Accepted (new create or idempotent replay of a completed key). Replay returns the original MessageAccepted body. A Single send is built inside the request and returns delivery_count and recipients. A Broadcast returns status preparing without them: the worker builds its recipients in chunks, and GET /messages/{id} reports counts once it leaves preparing. A Broadcast whose Segment matches nobody ends as failed instead of returning 422 no_active_endpoints. A Draft (draft: true) returns status draft without delivery counts.

application/json
  1. response
message_id*string
Formatuuid
channel*string
status*string
Value in"draft""scheduled""preparing""processing""completed""failed""cancelled"
delivery_count?integer

Single send only. Absent for Broadcasts, which are built after the response.

recipients?array<>

Single send only. Absent for Broadcasts.

Example Request
curl -X POST 'https://api.comraid.io/messages' \  -H 'Content-Type: application/json' \  -d '{  "channel": "push",  "content": {    "push": {}  }}'
Example Response
{  "message_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",  "channel": "push",  "status": "processing",  "delivery_count": 1,  "recipients": []}