Create or schedule a message (Single send, Broadcast, or Draft)
bearerAuthAuthorizationBearer <API key>Project API key (cr_sk_...)
Idempotency-Key?stringProject-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.
application/json- 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?booleanWhen true, save as a Draft (status: draft) instead of sending. Segment may be empty. Limited to push Broadcast Everyone or segment_id.
falsechannel*"push"Required. Only push is accepted in V1.
"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?stringtype?stringname?stringpriority?stringDefault high, or normal when content.push.data_only is true.
"high""normal"ttl?integerTime-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.
0 <= value <= 2419200collapse_key?stringCollapse key so later sends with the same key replace earlier ones on device. Mapped to FCM collapse_key and APNs apns-collapse-id.
length <= 64data?Custom push data. Keys must not start with the reserved cr_ prefix.
send_at?|Absolute UTC send time. Mutually exclusive with send_at_local.
date-timesend_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*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- response
message_id*stringuuidchannel*stringstatus*string"draft""scheduled""preparing""processing""completed""failed""cancelled"delivery_count?integerSingle send only. Absent for Broadcasts, which are built after the response.
recipients?array<>Single send only. Absent for Broadcasts.
curl -X POST 'https://api.comraid.io/messages' \ -H 'Content-Type: application/json' \ -d '{ "channel": "push", "content": { "push": {} }}'{ "message_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789", "channel": "push", "status": "processing", "delivery_count": 1, "recipients": []}List Messages GET
Lists Project Messages. Omit `status` for Push history (excludes `draft` and archived Drafts). Pass `status=draft` for the Drafts list.
Preview Broadcast targeting POST
Evaluates a Broadcast targeting selector without creating a message. `platforms` is preview-only and filters endpoint counts; it is not a targeting selector and must not be sent under `targeting` on create.