Notifications
Push Notifications are Messages on the push Channel. Create them with Single send or Broadcast via /messages, or Multi-send via /campaigns.
Send modes
A Notification is a Message on the push Channel — the name used in the Dashboard, SDKs, and these docs. The REST resources are /messages and /campaigns. A Notification reaches many Contacts; each Contact's copy is a Delivery.
- Single send —
POST /messageswithto.external_user_ids. Same Content for every recipient. - Broadcast —
POST /messageswithtargeting(everyone,segment_id, orrules). Same Content for every recipient. - Multi-send —
POST /campaignswith per-Contact Contents. Creates one Campaign and one child Message per recipient.
Single send
Set channel to "push". Omit send_at (or set it to null) to send ASAP; use an RFC3339 timestamp to schedule, or send_at_local to send at a clock time in each recipient's timezone. See Scheduling.
POST https://api.comraid.io/messages
Authorization: Bearer cr_sk_...
Idempotency-Key: acme_event_8392_user_123
Content-Type: application/json
{
"channel": "push",
"to": {
"external_user_ids": ["user_123"]
},
"category": "orders",
"type": "order_shipped",
"priority": "high",
"data": {
"order_id": "ord_8392",
"screen": "order"
},
"send_at": null,
"content": {
"push": {
"title": "Your order has shipped!",
"body": "Order #8392 is on its way.",
"image_url": null,
"platforms": ["android", "ios"],
"actions": [
{ "id": "accept", "text": "Accept" },
{ "id": "reject", "text": "Reject" }
]
}
}
}categorymust match an active project notification category slug (managed under Push → Push settings → Categories). Omit it to use the project default.- On Android, ComRaid resolves the category to an
android_channel_idand sends it through FCM. - On Android 8+ the category's channel decides the sound;
content.push.soundonly applies on iOS and Android 7 and older. To play a different sound on Android, send in a category with that sound. See Android SDK. - Missing or inactive categories are rejected before enqueue.
image_urlmust be a publicly reachable HTTP(S) URL (Endpoints fetch it). Upload viaPOST /media(API key) or the Dashboard composer, or host the file yourself and paste the URL. On iOS the image shows when the app has a Notification Service Extension — see Images and action buttons (iOS).- Optional
actions(max 3): stableid+ labeltext(optional Androidicon: a drawable name in the app). Withoutdata_only, actions still use today’s hybrid path (Android data-oriented; APNs may still alert). Prefer explicitdata_only: truewhen the OS must not draw. See React Native SDK and Migrate from RNFirebase.
Data-only Notifications
Set content.push.data_only: true for a Data-only Notification: the Provider omits system tray UI (no FCM notification block / no APNs alert). Optional title, body, and actions are app or SDK hints (for example presentNotification). Top-level Message data must be a non-empty object. When data_only is false or omitted, title and body remain required. Same rules for Single send, Broadcast, and Multi-send child Content. API / @comraid/node only — no Dashboard toggle.
POST https://api.comraid.io/messages
Authorization: Bearer cr_sk_...
Idempotency-Key: acme_rematch_m100
Content-Type: application/json
{
"channel": "push",
"to": {
"external_user_ids": ["user_42"]
},
"data": {
"type": "rematch",
"match_id": "m_100"
},
"content": {
"push": {
"data_only": true,
"title": "Rematch?",
"body": "Player_7 wants to play again.",
"platforms": ["android", "ios"],
"actions": [
{ "id": "accept", "text": "Accept" },
{ "id": "reject", "text": "Reject" }
]
}
}
}- Delivered is recorded when the SDK sends its receive ACK; opened is not implied by receive (CTR stays meaningful).
- Android force-stopped apps and iOS background delivery are best-effort — see Migrate from RNFirebase.
- Schemas: API Reference.
Broadcast
Use only one Broadcast selector per request: targeting.everyone, targeting.segment_id, or targeting.rules. Do not combine with to.external_user_ids.
POST https://api.comraid.io/messages
Authorization: Bearer cr_sk_...
Idempotency-Key: acme_segment_send_2026_03_09
Content-Type: application/json
{
"channel": "push",
"targeting": {
"segment_id": "seg_sys_subscribed"
},
"category": "orders",
"content": {
"push": {
"title": "Pro tip",
"body": "New features landed for your plan.",
"platforms": ["android", "ios"]
}
}
}Built-in Segments use seg_sys_* ids (for example seg_sys_subscribed for all Contacts with an Active push Endpoint). Saved Segments use UUIDs. Preview-only platforms belongs on POST /messages/targeting/preview, not inside create targeting — send platform filters under content.push.platforms.
POST https://api.comraid.io/messages
Authorization: Bearer cr_sk_...
Idempotency-Key: acme_rules_send_2026_03_09
Content-Type: application/json
{
"channel": "push",
"targeting": {
"rules": {
"operator": "and",
"conditions": [
{"field": "endpoint.is_active", "op": "eq", "value": true},
{"field": "contact_attribute", "key": "plan", "op": "eq", "value": "pro"}
]
}
},
"content": {
"push": {
"title": "Hello pro Contacts",
"body": "A one-off Segment without a saved segment_id.",
"platforms": ["android"]
}
}
}See Segments for the full rules shape.
Multi-send (Campaign)
When each Contact needs its own Content, create a Campaign. ComRaid splits the request into one child Message per recipient.
POST https://api.comraid.io/campaigns
Authorization: Bearer cr_sk_...
Idempotency-Key: acme_campaign_diwali_2026
Content-Type: application/json
{
"channel": "push",
"name": "Diwali offers",
"recipients": [
{
"external_user_id": "user_a",
"content": {
"push": {
"title": "Offer for you",
"body": "Save 20% today.",
"platforms": ["android", "ios"]
}
}
},
{
"external_user_id": "user_b",
"content": {
"push": {
"title": "Offer for you",
"body": "Save 30% today.",
"platforms": ["android", "ios"]
}
}
}
]
}A successful create returns 202 Accepted with campaign_id, rollup status, message_count, and per-recipient child Message rows. Recipients are capped at 10,000 (same Contact cap as Single send). Full create and poll schemas are in the API Reference. Inspect later with GET /campaigns/{id}. Child Messages use the same outcome vocabulary as Single send and Broadcast.
Response
Successful Message creates return 202 Accepted after durable persistence and queue intent — before Provider calls complete.
- Single send: the body includes
message_id, rollupstatus,delivery_count, and per-recipient rows. A list ofexternal_user_idsis capped at 10,000. - Broadcast: the body includes only
message_idand statuspreparing(orscheduled). ComRaid builds recipients in the background, so there is no Contact cap and nodelivery_countin the response. Read counts withGET /messages/{id}once the status leavespreparing. Sending starts while later parts of a large Segment are still being built. A Broadcast whose Segment matches nobody ends asfailed. - Multi-send:
recipientsis capped at 10,000. The create body includescampaign_id, rollupstatus,message_count, and per-recipient child Message rows.
Full create and poll schemas are in the API Reference.
Drafts
A Draft is a Message with status: draft — the same row you will send later (ADR 0013). Save with "draft": true on create. Title and body are required; Segment may be empty. Drafts are limited to a push Broadcast to Everyone or a Segment (not Data-only, Single send, or rules).
POST https://api.comraid.io/messages
Authorization: Bearer cr_sk_...
Idempotency-Key: draft_promo_1
Content-Type: application/json
{
"channel": "push",
"draft": true,
"targeting": { "everyone": true },
"content": {
"push": {
"title": "Weekend sale",
"body": "20% off through Sunday."
}
}
}GET /messages?status=draftlists non-archived Drafts. DefaultGET /messages(Push history) excludes them.PATCH /messages/{id}edits a Draft. Send theupdated_atyou loaded; a stale value returns409.POST /messages/{id}/sendruns full create validation and moves the same Message toscheduledorpreparing.DELETE /messages/{id}archives a Draft (deleted_at). Non-draft Messages return409.
Drafts never appear in analytics, sent counts, or Push history.
Get message
Poll status, delivery summary, and per-Endpoint delivery rows after create.
GET https://api.comraid.io/messages/9bc6a840-1f5d-49a7-bd1b-3f0d3a5cf2e7
Authorization: Bearer cr_sk_...The response includes status_summary (counts for sent, delivered, opened, failed, skipped, and optional action_clicks), timing, attribution ids, and a deliveries array. When the Notification declared actions, status_summary.action_clicks maps each action id to how many Deliveries recorded that button (first click per Delivery). Per-row action_id appears after an opened ack with that id — see Acknowledgements. Browse the full schema under Messages in the API Reference.
Get Campaign
Poll a Multi-send Campaign and its child Messages.
GET https://api.comraid.io/campaigns/0a1b2c3d-4e5f-6789-abcd-ef0123456789
Authorization: Bearer cr_sk_...The response includes rollup status, message_count, message_counts (per Message status: scheduled, preparing, processing, completed, failed, cancelled), delivery_totals (nested Delivery rollups + CTR summed across child Messages — same nesting as Message status_summary), and the child Message rows. Full schema: getCampaign.
Scheduling
Every send mode takes one of two schedules. Omit both to send right away. They are mutually exclusive.
| Schedule | Field | Example | Who receives it when |
|---|---|---|---|
| Fixed time | send_at — an RFC3339 instant with an offset or Z | "2026-11-07T21:00:00+05:30" (9 PM IST) | Every recipient at the same instant. A Contact in London gets it at 3:30 PM their time. |
| Recipient's local time | send_at_local — a date and clock time with no offset | "2026-11-07T21:00:00" | Each Contact at 9 PM on 7 November in their own timezone Property. A Contact without a valid timezone is treated as UTC. |
Use a fixed time for things that happen at one moment for everyone (a live match, a sale that opens at 9 PM IST). Use the recipient's local time for things that should land at a sensible hour wherever the Contact is (a 9 PM daily digest).
A send_at_local Message stays scheduled until that clock time first occurs anywhere on Earth (UTC+14); each Contact's Delivery is then released at their own local 9 PM, so one Message can take up to about a day to finish.
Cancel
Cancel a Message while it is scheduled, preparing, or processing. Queued Deliveries (including local-time ones waiting on a future available_at) become skipped with reason cancelled; Deliveries already sent stay sent and cannot be recalled. This is how you stop a wrong local-time send during its ~26h window.
POST https://api.comraid.io/messages/9bc6a840-1f5d-49a7-bd1b-3f0d3a5cf2e7/cancel
Authorization: Bearer cr_sk_...On success the body reports status: "cancelled". Sent and skipped counts stay visible on the Message. If the Message is already completed, failed, or cancelled, the API returns 409 conflict.
Cancel every cancellable child Message under a Campaign with the same rule:
POST https://api.comraid.io/campaigns/0a1b2c3d-4e5f-6789-abcd-ef0123456789/cancel
Authorization: Bearer cr_sk_...On success the body reports campaign_id and cancelled_count. Finished child Messages stay as they are. If none are cancellable, the API returns 409 conflict. Schema: cancelCampaign.
Preview targeting
Before a Broadcast, preview how many Contacts and Endpoints a selector resolves to. Send the same selector you would use on create: everyone, segment_id, or rules (optionally filtered by platforms). Pass optional category so counts exclude Contacts with that Category preference disabled (same offerability filter as Broadcast create). Omit category for Active + not Opted out only.
POST https://api.comraid.io/messages/targeting/preview
Authorization: Bearer cr_sk_...
Content-Type: application/json
{
"segment_id": "b2f4c1a0-3d5e-4a71-9c2b-8e0f1d2a3b4c",
"platforms": ["android", "ios"],
"category": "marketing"
}The preview response returns contact and active-endpoint counts (optionally split by platform). See the API Reference for the exact schema.
Lifecycle and outcomes
- Single send: create →
processing(orscheduled). Broadcast: create →preparing(orscheduled→preparingat send time) →processing. Inspect with GET. - Cancel works while a Message is
scheduled,preparing, orprocessing; finished statuses return 409. - Message statuses:
draft(saved, not sent),scheduled,preparing(resolving recipients),processing(sending),completed,failed,cancelled. A finished Message with at least one successful Delivery iscompletedand reports failed and skipped counts; one that reached nobody isfailed. - Delivery outcomes:
queued,processing,sent(Provider accepted),delivered(Endpoint ACK),opened,failed(tried and could not complete),skipped(never offered to the Provider — cancel, Inactive Endpoint, Opted out, Category preference block, invalid token, and equivalents). priorityishighornormal. It defaults tohigh, or tonormalfor a Data-only Notification: FCM deprioritizes apps whose high-priority pushes show nothing. Passpriority: "high"on a Data-only Notification only when it must arrive immediately.ttlis seconds from send time (or fromsend_atwhen scheduled); default86400(24 hours). Mapped to FCM Android TTL and APNsapns-expiration.ttl: 0means send now and do not store (FCMttl: 0s, APNsapns-expiration: 0): the worker offers the Delivery once and does not retry. For TTL greater than 0, Deliveries past expiry are skipped asttl_expired.- Scheduled Notifications freeze custom segment rules when they are created.
Always send an Idempotency-Key for Message and Campaign creates so client retries stay safe.
Endpoints
Register, list, and deactivate push Endpoints (FCM for Android, APNs for Expo iOS, or FCM for Firebase iOS), and manage Channel opt-outs.
Images and action buttons (iOS)
Add a Notification Service Extension so iOS shows push images and cold-device action buttons — Expo, bare React Native, and native iOS.