Mobile Push API

Beta

REST

Devices & Topics

Manage the device token inventory that powers targeting. Register tokens from your backend, bind them to users, subscribe to topics, and remove stale tokens so FCM and APNs delivery rates stay healthy.

Token registry

Store iOS and Android tokens per business with optional user binding.

User binding

Attach a userId so one send fans out to every device the user owns.

Topics

Subscribe tokens to named topics for campaigns and product segments.

Clean lifecycle

Delete tokens on logout or invalidation to protect delivery quality.

Authentication

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

Platforms

ios | android

per registration

Topics / device

maximum

Idempotent

Yes

re-register updates

Rate limit

200/s

per API key

POST

/v1/push/devices

Beta

Create or update a device registration. If the same token already exists for your business, Sendexa updates platform, userId, and merges topics (union with existing subscriptions unless you manage topics separately).

Request parameters

Field	Type	Required	Description
token	string	required	Full FCM registration token or APNs device token (hex string). Max 4096 chars.
platform	"ios" \| "android"	required	Must match the service that issued the token.
userId	string	optional	Your application user id (max 128). Pass null-equivalent by omitting to leave unbound; send a new value to rebind after login.
topics	string[]	optional	Initial topics to subscribe. Each name: 1–64 chars, [A-Za-z0-9_-]. Max 50 topics.

JSON

{
  "token": "dG9rZW4tZXhhbXBsZS1mY20tYW5kcm9pZA...",
  "platform": "android",
  "userId": "user_abc123",
  "topics": ["news", "orders", "promo-july"]
}

Success response (200)

JSON

{
  "success": true,
  "code": "DEVICE_REGISTERED",
  "message": "Device token registered.",
  "requestId": "REQ-1782000002001",
  "timestamp": "2026-07-12T12:00:00.000Z",
  "data": {
    "deviceId": "DEV-4f2a9c1e-88b0-4d2a-9f11-0c1d2e3f4a5b",
    "token": "dG9rZW4tZXhhbXBsZS1mY20tYW5kcm9pZA...",
    "platform": "android",
    "userId": "user_abc123",
    "topics": ["news", "orders", "promo-july"],
    "createdAt": "2026-07-12T12:00:00.000Z",
    "updatedAt": "2026-07-12T12:00:00.000Z"
  }
}

Bash

curl -X POST 'https://api.sendexa.co/v1/push/devices' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN' \
  -d '{
    "token": "dG9rZW4tZXhhbXBsZS1mY20...",
    "platform": "android",
    "userId": "user_abc123",
    "topics": ["news", "orders"]
  }'

When to re-register

Call register on first launch after permission grant, on every FCM/APNs token refresh callback, after user login (to set userId), and when the user changes notification preference segments (topics).

DELETE

/v1/push/devices/:token

Unregister

Remove a device from your registry. After deletion, sends that target this token (or a user that only had this device) will fail resolution. Topic memberships for the token are removed.

Field	Type	Required	Description
token	string (path)	required	Exact device token previously registered. URL-encode if it contains special characters.

Encoding path tokens

FCM tokens may include characters that need percent-encoding in the URL path. Prefer encoding the full token segment, e.g. encodeURIComponent(token).

Bash

curl -X DELETE \
  'https://api.sendexa.co/v1/push/devices/dG9rZW4tZXhhbXBsZS1mY20...' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN'

HTTP	Code	Meaning
200	`DEVICE_DELETED`	Token removed (or already absent — still success for idempotent clients)
404	`DEVICE_NOT_FOUND`	Strict mode: token never registered for this business
401	`UNAUTHORIZED`	Missing or invalid Basic auth

Recommended delete triggers

User logs out of the app on that device
Webhook push.failed with invalid / unregistered token error
User disables push notifications in your in-app settings
Account deletion / GDPR erase requests

POST

/v1/push/topics/subscribe

Topics

Subscribe one or more already-registered device tokens to a topic. Topics are created implicitly on first subscription. Sending with to.type = "topic" reaches all current subscribers.

Field	Type	Required	Description
topic	string	required	Topic name: 1–64 characters, letters, numbers, _ and - only.
tokens	string[]	required	One or more registered device tokens (max 1000 per request).

JSON

{
  "topic": "promo-july",
  "tokens": [
    "dG9rZW4tZXhhbXBsZS1mY20tMQ...",
    "dG9rZW4tZXhhbXBsZS1hcG5zLTI..."
  ]
}

Bash

curl -X POST 'https://api.sendexa.co/v1/push/topics/subscribe' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Basic YOUR_DASHBOARD_BASE64_TOKEN' \
  -d '{
    "topic": "promo-july",
    "tokens": [
      "dG9rZW4tZXhhbXBsZS1mY20tMQ...",
      "dG9rZW4tZXhhbXBsZS1hcG5zLTI..."
    ]
  }'

Topic naming rules

Rule	Detail
Length	1–64 characters
Characters	A–Z, a–z, 0–9, underscore (_), hyphen (-)
Case	Case-sensitive (News ≠ news)
Reserved	Avoid names starting with sendexa_ or fcm_ (reserved for internal use)
Per device	Maximum 50 topic memberships
Per subscribe call	Maximum 1000 tokens

Register topics vs subscribe endpoint

Passing topics on POST /v1/push/devices is convenient at registration time. Use POST /v1/push/topics/subscribe for bulk or later membership changes (e.g. user opts into a campaign).

Device lifecycle

Install / permission — App obtains FCM or APNs token.
Register — Backend calls POST /v1/push/devices without userId if the user is anonymous.
Login — Re-register with userId so account alerts reach this device.
Segment — Subscribe to topics based on preferences or cohorts.
Refresh — OS issues a new token → register again; old token may later fail and should be deleted when FCM/APNs reports invalid.
Logout / uninstall — Delete token. Uninstall is often detected only via failed deliveries.

Error reference

HTTP	Code	Endpoint	Cause
400	`INVALID_TOKEN`	register / subscribe	Empty, too long, or malformed token
400	`INVALID_PLATFORM`	register	platform not ios or android
400	`INVALID_TOPIC`	register / subscribe	Topic name fails naming rules
400	`TOO_MANY_TOPICS`	register / subscribe	Device would exceed 50 topics
400	`TOO_MANY_TOKENS`	subscribe	More than 1000 tokens in one request
401	`UNAUTHORIZED`	all	Auth missing or invalid
404	`DEVICE_NOT_FOUND`	delete / subscribe	Token not in registry (subscribe may partial-fail)
429	`RATE_LIMIT_EXCEEDED`	all	Over 200 req/s

Best practices

Treat the mobile app as untrusted: only your backend should call these endpoints with the Basic token.
On login, always re-register with the current token + userId so multi-device accounts stay accurate.
On logout, delete the token or re-register without userId if you still want anonymous marketing topics.
Prune tokens that fail with permanent invalid/unregistered errors — they drag down delivery metrics.
Use stable topic names in code (constants), not free-form user input, to avoid fragmenting audiences.
After bulk subscribe, send a small test push with type: topic before a large campaign. See Send Notification.

Privacy note

Device tokens are credentials for messaging a specific installation. Store them only as needed, restrict API key access, and delete tokens promptly when users revoke consent or delete their accounts.