ComRaidComRaid Docs

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 /messages with to.external_user_ids. Same Content for every recipient.
  • Broadcast — POST /messages with targeting (everyone, segment_id, or rules). Same Content for every recipient.
  • Multi-send — POST /campaigns with 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" }
      ]
    }
  }
}
  • category must 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_id and sends it through FCM.
  • On Android 8+ the category's channel decides the sound; content.push.sound only 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_url must be a publicly reachable HTTP(S) URL (Endpoints fetch it). Upload via POST /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): stable id + label text (optional Android icon: a drawable name in the app). Without data_only, actions still use today’s hybrid path (Android data-oriented; APNs may still alert). Prefer explicit data_only: true when 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, rollup status, delivery_count, and per-recipient rows. A list of external_user_ids is capped at 10,000.
  • Broadcast: the body includes only message_id and status preparing (or scheduled). ComRaid builds recipients in the background, so there is no Contact cap and no delivery_count in the response. Read counts with GET /messages/{id} once the status leaves preparing. Sending starts while later parts of a large Segment are still being built. A Broadcast whose Segment matches nobody ends as failed.
  • Multi-send: recipients is capped at 10,000. The create body includes campaign_id, rollup status, 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=draft lists non-archived Drafts. Default GET /messages (Push history) excludes them.
  • PATCH /messages/{id} edits a Draft. Send the updated_at you loaded; a stale value returns 409.
  • POST /messages/{id}/send runs full create validation and moves the same Message to scheduled or preparing.
  • DELETE /messages/{id} archives a Draft (deleted_at). Non-draft Messages return 409.

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.

ScheduleFieldExampleWho receives it when
Fixed timesend_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 timesend_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 (or scheduled). Broadcast: create → preparing (or scheduled → preparing at send time) → processing. Inspect with GET.
  • Cancel works while a Message is scheduled, preparing, or processing; 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 is completed and reports failed and skipped counts; one that reached nobody is failed.
  • 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).
  • priority is high or normal. It defaults to high, or to normal for a Data-only Notification: FCM deprioritizes apps whose high-priority pushes show nothing. Pass priority: "high" on a Data-only Notification only when it must arrive immediately.
  • ttl is seconds from send time (or from send_at when scheduled); default 86400 (24 hours). Mapped to FCM Android TTL and APNs apns-expiration. ttl: 0 means send now and do not store (FCM ttl: 0s, APNs apns-expiration: 0): the worker offers the Delivery once and does not retry. For TTL greater than 0, Deliveries past expiry are skipped as ttl_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.

On this page