Send Push Notification

Send a push notification

curl --request POST \
  --url https://api.sendrealm.com/push/notifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app_id": "<string>",
  "tokens": [
    {
      "token": "<string>"
    }
  ],
  "notification": {
    "title": "<string>",
    "body": "<string>",
    "image_url": "<string>",
    "launch_url": "<string>"
  },
  "environment": "production",
  "web_subscriptions": [
    {
      "endpoint": "<string>",
      "keys": {
        "p256dh": "<string>",
        "auth": "<string>"
      },
      "expirationTime": 123
    }
  ],
  "device_ids": [
    "<string>"
  ],
  "contact_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "external_ids": [
    "<string>"
  ],
  "emails": [
    "jsmith@example.com"
  ],
  "audiences": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "excluded_audiences": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "platforms": [],
  "scheduled_at": "2023-11-07T05:31:56Z",
  "template_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "messages": [
    {
      "code": "<string>",
      "title": "<string>",
      "body": "<string>",
      "label": "<string>",
      "image_url": "<string>",
      "launch_url": "<string>"
    }
  ],
  "buttons": [
    {
      "id": "<string>",
      "text": "<string>",
      "title": "<string>",
      "icon": "<string>",
      "launch_url": "<string>"
    }
  ],
  "data": {},
  "android": {
    "channel_id": "<string>",
    "small_icon": "<string>",
    "large_icon": "<string>",
    "big_picture": "<string>",
    "category": "<string>",
    "sound": "<string>",
    "lockscreen_visibility": "<string>",
    "led_color": "<string>",
    "accent_color": "<string>",
    "ttl": "<string>"
  },
  "ios": {
    "sound": "<string>",
    "badge": 1,
    "category": "<string>",
    "thread_id": "<string>",
    "mutable_content": true
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app_id: '<string>',
    tokens: [{token: '<string>'}],
    notification: {
      title: '<string>',
      body: JSON.stringify('<string>'),
      image_url: '<string>',
      launch_url: '<string>'
    },
    environment: 'production',
    web_subscriptions: [
      {
        endpoint: '<string>',
        keys: {p256dh: '<string>', auth: '<string>'},
        expirationTime: 123
      }
    ],
    device_ids: ['<string>'],
    contact_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    external_ids: ['<string>'],
    emails: ['jsmith@example.com'],
    audiences: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    excluded_audiences: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    platforms: [],
    scheduled_at: '2023-11-07T05:31:56Z',
    template_version_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    messages: [
      {
        code: '<string>',
        title: '<string>',
        body: JSON.stringify('<string>'),
        label: '<string>',
        image_url: '<string>',
        launch_url: '<string>'
      }
    ],
    buttons: [
      {
        id: '<string>',
        text: '<string>',
        title: '<string>',
        icon: '<string>',
        launch_url: '<string>'
      }
    ],
    data: {},
    android: {
      channel_id: '<string>',
      small_icon: '<string>',
      large_icon: '<string>',
      big_picture: '<string>',
      category: '<string>',
      sound: '<string>',
      lockscreen_visibility: '<string>',
      led_color: '<string>',
      accent_color: '<string>',
      ttl: '<string>'
    },
    ios: {
      sound: '<string>',
      badge: 1,
      category: '<string>',
      thread_id: '<string>',
      mutable_content: true
    }
  })
};

fetch('https://api.sendrealm.com/push/notifications', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sendrealm.com/push/notifications"

payload = {
    "app_id": "<string>",
    "tokens": [{ "token": "<string>" }],
    "notification": {
        "title": "<string>",
        "body": "<string>",
        "image_url": "<string>",
        "launch_url": "<string>"
    },
    "environment": "production",
    "web_subscriptions": [
        {
            "endpoint": "<string>",
            "keys": {
                "p256dh": "<string>",
                "auth": "<string>"
            },
            "expirationTime": 123
        }
    ],
    "device_ids": ["<string>"],
    "contact_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "external_ids": ["<string>"],
    "emails": ["jsmith@example.com"],
    "audiences": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "excluded_audiences": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "platforms": [],
    "scheduled_at": "2023-11-07T05:31:56Z",
    "template_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "messages": [
        {
            "code": "<string>",
            "title": "<string>",
            "body": "<string>",
            "label": "<string>",
            "image_url": "<string>",
            "launch_url": "<string>"
        }
    ],
    "buttons": [
        {
            "id": "<string>",
            "text": "<string>",
            "title": "<string>",
            "icon": "<string>",
            "launch_url": "<string>"
        }
    ],
    "data": {},
    "android": {
        "channel_id": "<string>",
        "small_icon": "<string>",
        "large_icon": "<string>",
        "big_picture": "<string>",
        "category": "<string>",
        "sound": "<string>",
        "lockscreen_visibility": "<string>",
        "led_color": "<string>",
        "accent_color": "<string>",
        "ttl": "<string>"
    },
    "ios": {
        "sound": "<string>",
        "badge": 1,
        "category": "<string>",
        "thread_id": "<string>",
        "mutable_content": True
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "status": 123,
  "data": {
    "total": 123,
    "sent": 123,
    "failed": 123,
    "notifications": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "2023-11-07T05:31:56Z",
        "device_id": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

POST

push

notifications

Send a push notification

curl --request POST \
  --url https://api.sendrealm.com/push/notifications \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "app_id": "<string>",
  "tokens": [
    {
      "token": "<string>"
    }
  ],
  "notification": {
    "title": "<string>",
    "body": "<string>",
    "image_url": "<string>",
    "launch_url": "<string>"
  },
  "environment": "production",
  "web_subscriptions": [
    {
      "endpoint": "<string>",
      "keys": {
        "p256dh": "<string>",
        "auth": "<string>"
      },
      "expirationTime": 123
    }
  ],
  "device_ids": [
    "<string>"
  ],
  "contact_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "external_ids": [
    "<string>"
  ],
  "emails": [
    "jsmith@example.com"
  ],
  "audiences": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "excluded_audiences": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "platforms": [],
  "scheduled_at": "2023-11-07T05:31:56Z",
  "template_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "messages": [
    {
      "code": "<string>",
      "title": "<string>",
      "body": "<string>",
      "label": "<string>",
      "image_url": "<string>",
      "launch_url": "<string>"
    }
  ],
  "buttons": [
    {
      "id": "<string>",
      "text": "<string>",
      "title": "<string>",
      "icon": "<string>",
      "launch_url": "<string>"
    }
  ],
  "data": {},
  "android": {
    "channel_id": "<string>",
    "small_icon": "<string>",
    "large_icon": "<string>",
    "big_picture": "<string>",
    "category": "<string>",
    "sound": "<string>",
    "lockscreen_visibility": "<string>",
    "led_color": "<string>",
    "accent_color": "<string>",
    "ttl": "<string>"
  },
  "ios": {
    "sound": "<string>",
    "badge": 1,
    "category": "<string>",
    "thread_id": "<string>",
    "mutable_content": true
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    app_id: '<string>',
    tokens: [{token: '<string>'}],
    notification: {
      title: '<string>',
      body: JSON.stringify('<string>'),
      image_url: '<string>',
      launch_url: '<string>'
    },
    environment: 'production',
    web_subscriptions: [
      {
        endpoint: '<string>',
        keys: {p256dh: '<string>', auth: '<string>'},
        expirationTime: 123
      }
    ],
    device_ids: ['<string>'],
    contact_ids: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    external_ids: ['<string>'],
    emails: ['jsmith@example.com'],
    audiences: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    excluded_audiences: ['3c90c3cc-0d44-4b50-8888-8dd25736052a'],
    platforms: [],
    scheduled_at: '2023-11-07T05:31:56Z',
    template_version_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    messages: [
      {
        code: '<string>',
        title: '<string>',
        body: JSON.stringify('<string>'),
        label: '<string>',
        image_url: '<string>',
        launch_url: '<string>'
      }
    ],
    buttons: [
      {
        id: '<string>',
        text: '<string>',
        title: '<string>',
        icon: '<string>',
        launch_url: '<string>'
      }
    ],
    data: {},
    android: {
      channel_id: '<string>',
      small_icon: '<string>',
      large_icon: '<string>',
      big_picture: '<string>',
      category: '<string>',
      sound: '<string>',
      lockscreen_visibility: '<string>',
      led_color: '<string>',
      accent_color: '<string>',
      ttl: '<string>'
    },
    ios: {
      sound: '<string>',
      badge: 1,
      category: '<string>',
      thread_id: '<string>',
      mutable_content: true
    }
  })
};

fetch('https://api.sendrealm.com/push/notifications', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sendrealm.com/push/notifications"

payload = {
    "app_id": "<string>",
    "tokens": [{ "token": "<string>" }],
    "notification": {
        "title": "<string>",
        "body": "<string>",
        "image_url": "<string>",
        "launch_url": "<string>"
    },
    "environment": "production",
    "web_subscriptions": [
        {
            "endpoint": "<string>",
            "keys": {
                "p256dh": "<string>",
                "auth": "<string>"
            },
            "expirationTime": 123
        }
    ],
    "device_ids": ["<string>"],
    "contact_ids": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "external_ids": ["<string>"],
    "emails": ["jsmith@example.com"],
    "audiences": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "excluded_audiences": ["3c90c3cc-0d44-4b50-8888-8dd25736052a"],
    "platforms": [],
    "scheduled_at": "2023-11-07T05:31:56Z",
    "template_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "messages": [
        {
            "code": "<string>",
            "title": "<string>",
            "body": "<string>",
            "label": "<string>",
            "image_url": "<string>",
            "launch_url": "<string>"
        }
    ],
    "buttons": [
        {
            "id": "<string>",
            "text": "<string>",
            "title": "<string>",
            "icon": "<string>",
            "launch_url": "<string>"
        }
    ],
    "data": {},
    "android": {
        "channel_id": "<string>",
        "small_icon": "<string>",
        "large_icon": "<string>",
        "big_picture": "<string>",
        "category": "<string>",
        "sound": "<string>",
        "lockscreen_visibility": "<string>",
        "led_color": "<string>",
        "accent_color": "<string>",
        "ttl": "<string>"
    },
    "ios": {
        "sound": "<string>",
        "badge": 1,
        "category": "<string>",
        "thread_id": "<string>",
        "mutable_content": True
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "status": 123,
  "data": {
    "total": 123,
    "sent": 123,
    "failed": 123,
    "notifications": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created_at": "2023-11-07T05:31:56Z",
        "device_id": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<string>",
    "issues": [
      {
        "code": "<string>",
        "path": "<string>",
        "message": "<string>"
      }
    ]
  }
}

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.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Push notification payload

app_id

string

required

Push app short ID.

tokens

object[]

required

Minimum array length: 1

Show child attributes

notification

object

required

Show child attributes

environment

enum<string>

default:production

Sendrealm push environment. Development sends only target devices registered in development mode.

Available options:

production,

development

web_subscriptions

object[]

Direct browser Web Push subscriptions from PushSubscription.toJSON(). Use device, contact, external ID, email, audience, or platforms targeting for SDK-registered web devices.

Minimum array length: 1

Show child attributes

device_ids

string[]

Minimum array length: 1

contact_ids

string<uuid>[]

Minimum array length: 1

external_ids

string[]

Minimum array length: 1

emails

string<email>[]

Minimum array length: 1

audiences

string<uuid>[]

Minimum array length: 1

excluded_audiences

string<uuid>[]

Minimum array length: 1

platforms

enum<string>[]

Minimum array length: 1

Available options:

web,

android,

ios

scheduled_at

string<date-time>

Queue an audience send for a future time.

template_version_id

string<uuid>

messages

object[]

Minimum array length: 1

Show child attributes

buttons

object[]

Maximum array length: 3

Option 1
Option 2

Show child attributes

data

object

Show child attributes

android

object

Show child attributes

ios

object

Show child attributes

Response

Push notification sent successfully

status

integer

required

HTTP response status code

data

object

required

Show child attributes

API Documentation

Emails

Project

Domains

Campaigns

Push Notifications

Events

Templates

Automations

Topics

Audiences

Audience Properties

Contacts

Targeting

Body

Tags And Contact Properties

Reporting

Authorizations

Body

Response

​Targeting

​Body

​Tags And Contact Properties

​Reporting

Authorizations

Body

Response

Targeting

Body

Tags And Contact Properties

Reporting