Skip to main content
Send a push notification to Sendrealm push devices, contacts, external IDs, email addresses, raw push tokens, or audiences.

​
Targeting

Use one Sendrealm targeting style per request:
  • tokens: raw Android FCM or iOS APNs push tokens with their platform.
  • web_subscriptions: raw browser PushSubscription.toJSON() objects for direct Web Push sends.
  • device_ids: Sendrealm push device IDs created by the SDK.
  • contact_ids: Sendrealm contact IDs.
  • external_ids: stable IDs set with SDK login or the server API.
  • emails: contact email addresses.
  • audiences: audience IDs for queued or scheduled audience sends.
Use excluded_audiences with contact, external ID, email, or audience sends to remove contacts that belong to specific audiences. Use platforms to limit delivery to android, ios, or web. Web devices registered by the React SDK can be targeted through device, contact, external ID, email, audience, or platforms: ["web"] filters. Set environment to development to target devices registered by development SDK builds. Omit it, or set production, for production devices. This is separate from iOS apns_environment. Audience sends are queued through the push broadcast delivery pipeline. Direct device, token, contact, external ID, and email sends are delivered immediately.

​
Body

{
  "app_id": "push_app_short_id",
  "environment": "development",
  "audiences": ["018f5b8d-2e2d-7a9b-9000-1c24e8a3b2c1"],
  "excluded_audiences": ["018f5b91-8f46-7f1d-a111-df39fd4b98a0"],
  "platforms": ["ios", "android"],
  "scheduled_at": "2026-06-21T20:30:00.000Z",
  "notification": {
    "title": "Order update",
    "body": "Your order is ready.",
    "launch_url": "myapp://orders/123",
    "image_url": "https://example.com/order.png"
  },
  "buttons": [
    {
      "id": "view_order",
      "text": "View order",
      "launch_url": "myapp://orders/123"
    }
  ],
  "data": {
    "order_id": "123"
  },
  "ios": {
    "sound": "default",
    "badge": 1,
    "apns_environment": "sandbox"
  },
  "android": {
    "channel_id": "orders",
    "sound": "default",
    "ttl": "3600"
  }
}
For direct browser sends, pass browser subscriptions separately from mobile tokens: 
{
  "app_id": "push_app_short_id",
  "web_subscriptions": [
    {
      "endpoint": "https://fcm.googleapis.com/fcm/send/...",
      "expirationTime": null,
      "keys": {
        "p256dh": "base64url-key",
        "auth": "base64url-secret"
      }
    }
  ],
  "notification": {
    "title": "New message",
    "body": "Open the inbox."
  }
}
Use buttons to attach up to three notification actions. Android renders the button text directly. iOS sends Sendrealm’s default action category and includes the button payload for SDK action tracking and deep-link handling. For localized messages, send messages with locale codes: 
{
  "app_id": "push_app_short_id",
  "contact_ids": ["018f5b8d-2e2d-7a9b-9000-1c24e8a3b2c1"],
  "messages": [
    {
      "code": "en-US",
      "label": "English",
      "title": "Welcome back",
      "body": "You have a new update."
    },
    {
      "code": "pt-BR",
      "label": "Portuguese",
      "title": "Bem-vindo de volta",
      "body": "Voce tem uma nova atualizacao."
    }
  ],
  "notification": {
    "title": "Welcome back",
    "body": "You have a new update."
  }
}

​
Tags And Contact Properties

SDK tags are client-sourced key/value data used for app behavior, preferences, audience targeting, and personalization. They are useful for values the app can observe directly, such as onboarding status, selected interests, locale, or app version. Server contact properties are authoritative backend data. Use the Contacts API for account, billing, compliance, lifecycle, verified profile, and CRM values. SDK tag writes cannot overwrite server-owned or system-owned contact properties. Protected SDK tag keys include identity and Sendrealm/system fields. Keys that start with sendrealm_, sys_, billing_, security_, or account_ are reserved. Audience properties are server-owned by default; set sdk_writable: true on an audience property only when the mobile app is allowed to manage that value.

​
Reporting

Each send records push notification rows and events for provider accepted sends, failures, opens, clicks, and SDK-tracked custom events. Provider accepted means the push provider accepted the request; it is not the same as confirmed display on the physical device.