> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Push Notification

> Send a push notification to a direct device target or to contact aliases.

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.


## OpenAPI

````yaml api-reference/openapi.json POST /push/notifications
openapi: 3.0.1
info:
  title: Sendrealm API
  description: >-
    API for email, push, audience resources, domains, campaign drafts,
    templates, events, topics, and automations
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.sendrealm.com
security:
  - bearerAuth: []
paths:
  /push/notifications:
    post:
      summary: Send a push notification
      description: >-
        Send a push notification to a direct device target or to contact
        aliases.
      requestBody:
        description: Push notification payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PushNotification'
        required: true
      responses:
        '201':
          description: Push notification sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PushNotificationResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
components:
  schemas:
    PushNotification:
      type: object
      required:
        - app_id
        - notification
      additionalProperties: false
      properties:
        app_id:
          type: string
          description: Push app short ID.
        environment:
          type: string
          enum:
            - production
            - development
          default: production
          description: >-
            Sendrealm push environment. Development sends only target devices
            registered in development mode.
        tokens:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - token
              - platform
            additionalProperties: false
            properties:
              token:
                type: string
              platform:
                type: string
                enum:
                  - android
                  - ios
        web_subscriptions:
          type: array
          minItems: 1
          description: >-
            Direct browser Web Push subscriptions from
            PushSubscription.toJSON(). Use device, contact, external ID, email,
            audience, or platforms targeting for SDK-registered web devices.
          items:
            type: object
            required:
              - endpoint
              - keys
            additionalProperties: false
            properties:
              endpoint:
                type: string
                format: uri
              expirationTime:
                type: integer
                nullable: true
                description: >-
                  Browser subscription expiration time in milliseconds since
                  epoch, when provided.
              keys:
                type: object
                required:
                  - p256dh
                  - auth
                additionalProperties: false
                properties:
                  p256dh:
                    type: string
                  auth:
                    type: string
        device_ids:
          type: array
          minItems: 1
          items:
            type: string
        contact_ids:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
        external_ids:
          type: array
          minItems: 1
          items:
            type: string
        emails:
          type: array
          minItems: 1
          items:
            type: string
            format: email
        audiences:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
        excluded_audiences:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
        platforms:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            enum:
              - web
              - android
              - ios
        scheduled_at:
          type: string
          format: date-time
          description: Queue an audience send for a future time.
        template_version_id:
          type: string
          format: uuid
        messages:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - code
              - title
              - body
            additionalProperties: false
            properties:
              code:
                type: string
              label:
                type: string
              title:
                type: string
              body:
                type: string
              image_url:
                type: string
                format: uri
              launch_url:
                type: string
                maxLength: 2048
        notification:
          type: object
          required:
            - title
            - body
          properties:
            title:
              type: string
            body:
              type: string
            image_url:
              type: string
              format: uri
            launch_url:
              type: string
              maxLength: 2048
        buttons:
          type: array
          maxItems: 3
          items:
            $ref: '#/components/schemas/PushActionButton'
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
        android:
          type: object
          properties:
            channel_id:
              type: string
            small_icon:
              type: string
            large_icon:
              type: string
            big_picture:
              type: string
              format: uri
            category:
              type: string
            sound:
              type: string
            lockscreen_visibility:
              type: string
            led_color:
              type: string
            accent_color:
              type: string
            ttl:
              type: string
        ios:
          type: object
          properties:
            sound:
              type: string
            badge:
              type: integer
              minimum: 0
            category:
              type: string
            thread_id:
              type: string
            mutable_content:
              type: boolean
            apns_environment:
              type: string
              enum:
                - sandbox
                - production
              description: >-
                APNs environment override for direct token sends.
                Device-targeted sends default to the registered device/provider
                environment.
      anyOf:
        - required:
            - tokens
        - required:
            - web_subscriptions
        - required:
            - device_ids
        - required:
            - contact_ids
        - required:
            - external_ids
        - required:
            - emails
        - required:
            - audiences
    PushNotificationResponse:
      allOf:
        - $ref: '#/components/schemas/Envelope'
        - type: object
          required:
            - data
          properties:
            data:
              type: object
              required:
                - total
                - sent
                - failed
                - notifications
              properties:
                total:
                  type: integer
                sent:
                  type: integer
                failed:
                  type: integer
                notifications:
                  type: array
                  items:
                    $ref: '#/components/schemas/PushNotificationResult'
    PushActionButton:
      type: object
      required:
        - id
      additionalProperties: false
      anyOf:
        - type: object
          required:
            - text
        - type: object
          required:
            - title
      properties:
        id:
          type: string
        text:
          type: string
        title:
          type: string
          description: Deprecated alias for text.
        icon:
          type: string
        launch_url:
          type: string
          maxLength: 2048
    JsonValue:
      oneOf:
        - type: string
          nullable: true
        - type: number
        - type: boolean
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
        - type: array
          items:
            $ref: '#/components/schemas/JsonValue'
    Envelope:
      type: object
      required:
        - status
      properties:
        status:
          type: integer
          description: HTTP response status code
    PushNotificationResult:
      type: object
      required:
        - id
        - status
        - platform
        - created_at
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - sent
            - failed
        platform:
          type: string
          enum:
            - web
            - android
            - ios
        created_at:
          type: string
          format: date-time
        device_id:
          type: string
          nullable: true
    Error:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: integer
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            details:
              $ref: '#/components/schemas/JsonValue'
            issues:
              type: array
              items:
                $ref: '#/components/schemas/ValidationIssue'
    ValidationIssue:
      type: object
      required:
        - code
        - path
        - message
      properties:
        code:
          type: string
        path:
          type: string
          nullable: true
        message:
          type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Request could not be processed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````