Send SMS

API reference for sending transactional SMS messages.

Send a transactional SMS through the PlatformXe multi-provider fallback chain.

Endpoint

POST /api/v1/messaging/sms

Scope: messaging:send

Request body

Field	Type	Required	Description
to	string	Yes	Recipient phone number in E.164 format (e.g. +2348012345678)
message	string	Yes	SMS body text (max 1600 characters)
regionCode	string	No	ISO 3166-1 alpha-2 country code for routing optimization (e.g. NG). Default: auto-detected from phone number

Response

{
  "success": true,
  "data": {
    "messageId": "sms_abc123def456",
    "provider": "primary",
    "status": "sent"
  }
}

Field	Type	Description
messageId	string	Unique message identifier for tracking
provider	string	Which provider in the fallback chain handled delivery
status	string	sent (dispatched) or queued (accepted for retry)

Examples

curl

curl -X POST https://api.platformxe.com/api/v1/messaging/sms \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -H "x-idempotency-key: otp-login-12345" \
  -d '{
    "to": "+2348012345678",
    "message": "Your verification code is 482910. It expires in 10 minutes.",
    "regionCode": "NG"
  }'

SDK

import { PlatformXe } from '@caldera/platformxe-sdk';

const px = new PlatformXe({ apiKey: 'pxk_live_your_api_key_here' });

const result = await px.sms.send({
  to: '+2348012345678',
  message: 'Your verification code is 482910. It expires in 10 minutes.',
  regionCode: 'NG',
});

console.log(result.data.messageId);
// "sms_abc123def456"

console.log(result.data.status);
// "sent"

Error responses

Code	Description
BAD_REQUEST	Missing or invalid fields (e.g. invalid phone number format)
FORBIDDEN	API key does not have the messaging:send scope
RATE_LIMITED	Rate limit exceeded for this API key
PROVIDER_ERROR	All providers in the fallback chain failed