Mobile Push API

Beta

REST

Mobile Push API

Send transactional and marketing push notifications to iOS and Android apps. Register device tokens, target users or topics, attach deep-link data, and track delivery and opens with webhooks.

iOS & Android

One REST surface for both platforms. Sendexa routes through FCM (Android) and APNs (iOS) using credentials you configure once.

Flexible Targeting

Address a single device token, every device linked to a userId, or an entire topic subscription list.

Topics & Segments

Subscribe devices to topics for broadcast campaigns, product updates, and audience segments without storing token lists yourself.

Rich Notifications

Title, body, optional image, and arbitrary data payload for deep links and in-app routing.

Delivery & Opens

Webhooks for delivered, failed, and opened events so you can measure engagement without polling.

Secure by Default

HTTP Basic Auth on every call. Device tokens are scoped to your business and never shared across accounts.

Platforms

iOS + Android

APNs & FCM

Avg Accept

<200ms

API response time

Rate Limit

200/s

per API key

Title Limit

chars recommended

Authentication

All REST requests use HTTP Basic Auth with your dashboard Base64 token: Authorization: Basic <token>. Auth guide →

Beta status

Mobile Push is in Beta. Endpoints and payload fields are stable for integration, but rate limits, billing, and platform-specific edge cases may change. Feedback welcome via your dashboard support channel.

Quick Start

After you have registered a device token (see Getting Started), send a notification:

Bash

curl -X POST 'https://api.sendexa.co/v1/push/send' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN' \
  -d '{
    "to": { "type": "device", "value": "dG9rZW4tZXhhbXBsZQ..." },
    "title": "Order shipped",
    "body": "Your order #1234 is on the way.",
    "data": { "orderId": "1234", "screen": "orders" },
    "priority": "high"
  }'

Response

JSON

{
  "success": true,
  "code": "PUSH_QUEUED",
  "message": "Push notification accepted for delivery.",
  "requestId": "REQ-1782000000001",
  "timestamp": "2026-07-12T10:15:22.100Z",
  "data": {
    "pushId": "PUSH-8c1a2b3d-4e5f-6789-abcd-ef0123456789",
    "channel": "push",
    "target": {
      "type": "device",
      "value": "dG9rZW4tZXhhbXBsZQ...",
      "platform": "android",
      "resolvedDevices": 1
    },
    "notification": {
      "title": "Order shipped",
      "body": "Your order #1234 is on the way.",
      "image": null,
      "data": {
        "orderId": "1234",
        "screen": "orders"
      }
    },
    "delivery": {
      "status": "queued",
      "priority": "high",
      "ttl": 86400,
      "submittedAt": "2026-07-12T10:15:22.100Z"
    },
    "billing": {
      "units": 1,
      "pricing": {
        "unitCost": 0.002,
        "totalCost": 0.002,
        "currency": "USD"
      }
    }
  }
}

API Endpoints

/v1/push/devices/:token

Unregister Device

Remove a device token on logout, uninstall, or token invalidation.

Push to a device, user, or topic with title, body, data, image, priority, and TTL.

View docs

POST

/v1/push/topics/subscribe

Topic Subscribe

Subscribe one or more device tokens to a named topic for broadcast targeting.

View docs

Targeting Models

Device

type: "device" — send to one FCM or APNs token. Use for device-specific alerts or when you already resolved the token client-side.

User

type: "user" — fan-out to every registered device bound to a userId. Ideal for account alerts across phone and tablet.

Topic

type: "topic" — broadcast to all devices subscribed to a topic (e.g. news, promo-july).

Integration Lifecycle

Configure credentials — upload FCM service account JSON and/or APNs key (.p8) in the Sendexa dashboard. See Getting Started.
Register devices — your mobile app obtains a push token and calls POST /v1/push/devices (via your backend) with optional userId and topics.
Send notifications — use POST /v1/push/send from your servers. Prefer user/topic targeting over storing tokens in every service.
Observe events — subscribe to push.delivered, push.failed, and push.opened webhooks.
Clean up — unregister tokens on logout or when FCM/APNs reports them invalid to keep delivery rates high.

Delivery Statuses

Status	Meaning	Action
queued	Accepted by Sendexa, waiting to be handed to FCM/APNs	Wait — normal
sent	Accepted by the platform push service	Wait for delivery/open webhooks
delivered	Confirmed delivered to the device (when available)	Success — store the receipt
opened	User tapped the notification (client SDK reports open)	Attribute engagement
failed	Rejected by FCM/APNs or token invalid	Check error code; unregister bad tokens
expired	Not delivered before TTL elapsed	Resend if still relevant

Common Error Codes

HTTP	Code	Cause
400	`INVALID_TOKEN`	Device token missing, malformed, or wrong platform
400	`INVALID_TARGET`	to.type not device\|user\|topic, or value empty
400	`PAYLOAD_TOO_LARGE`	Combined title/body/data exceeds platform size limits
401	`UNAUTHORIZED`	Missing or invalid Authorization header
403	`PUSH_CREDENTIALS_MISSING`	FCM or APNs credentials not configured for this business
403	`INSUFFICIENT_CREDITS`	Account balance too low to send
404	`DEVICE_NOT_FOUND`	Token not registered, or already deleted
404	`USER_HAS_NO_DEVICES`	No devices registered for the given userId
429	`RATE_LIMIT_EXCEEDED`	Exceeded 200 req/s — implement exponential backoff

Best Practices

Always register devices through your backend — never embed the dashboard Basic token in a mobile app.
Store the pushId from every send response to correlate webhook events.
Prefer user and topic targeting over hard-coding device tokens in business logic.
Re-register tokens whenever the OS issues a new one (app reinstall, token refresh callbacks).
Delete invalid tokens on push.failed with unregistered / invalid token errors.
Keep titles under ~65 characters and bodies under ~240 for clean lock-screen display on both platforms.
Use webhooks for delivery and opens instead of polling.

Next: Getting Started

Configure FCM and APNs credentials, register your first device, and send a test notification.

Continue

Webhooks

Subscribe to push.delivered, push.failed, and push.opened with HMAC verification and retry policy.

View webhooks