Getting Started

Configure platform credentials, register your first device token, and send a test notification end-to-end. This guide assumes you already have an iOS or Android app that can receive FCM or APNs tokens.

Prerequisites

1. Configure push credentials in the dashboard

Sendexa stores your platform credentials encrypted and uses them only when sending on behalf of your business. Incomplete credentials return PUSH_CREDENTIALS_MISSING (HTTP 403) for the affected platform.

2. Obtain a device token in your app

Your mobile app must request notification permission (where required) and retrieve the platform push token. Send that token to your backend; the backend then registers it with Sendexa.

// FirebaseMessagingService or startup
FirebaseMessaging.getInstance().token.addOnCompleteListener { task ->
    if (!task.isSuccessful) return@addOnCompleteListener
    val fcmToken = task.result
    // POST fcmToken to YOUR backend — never call Sendexa with the app secret
    api.registerDevice(token = fcmToken, platform = "android")
}

// Also handle onNewToken for refreshes
override fun onNewToken(token: String) {
    api.registerDevice(token = token, platform = "android")
}

3. Register the device with Sendexa

From your backend, register or refresh the token. This call is idempotent for the same token: re-registering updates userId, platform, and topic memberships.

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"]
  }'

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

4. Send a test notification

Target the device you just registered. Use a physical device or emulator with Google Play services / APNs sandbox as appropriate.

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": "dG9rZW4tZXhhbXBsZS1mY20..."
    },
    "title": "Hello from Sendexa",
    "body": "Your Mobile Push integration is working.",
    "data": {
      "source": "getting-started",
      "screen": "home"
    },
    "priority": "high"
  }'