smsdora Integration Guide

x-api-key: smsgw_ab12cd34_e7f8a9b0c1d2e3f4...

Authorization: Bearer smsgw_ab12cd34_e7f8a9b0c1d2e3f4...

curl -X POST https://api.smsdora.com/messages/send \
  -H "x-api-key: smsgw_ab12cd34_e7f8a9b0c1d2e3f4..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+212600000000",
    "message": "Your verification code is 4829"
  }'

{
  "statusCode": 201,
  "message": "SMS queued for delivery",
  "data": {
    "id": "64a...",
    "recipient": "+212600000000",
    "message": "Your verification code is 4829",
    "status": "dispatching",
    "device": {
      "id": "64b...",
      "deviceName": "My Samsung S24"
    }
  }
}

curl "https://api.smsdora.com/messages?status=failed&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

{
  "statusCode": 200,
  "data": {
    "messages": [ /* array of message objects (see below) */ ],
    "pagination": {
      "total": 42,
      "page": 1,
      "limit": 20,
      "totalPages": 3
    }
  }
}

{
  "statusCode": 200,
  "data": {
    "id": "64a...",
    "deviceId": "64b...",
    "campaignId": null,
    "resentFromMessageId": null,
    "resentToMessageId": null,
    "recipient": "+212600000000",
    "message": "Your verification code is 4829",
    "segmentsCount": 1,
    "status": "delivered",
    "failureReason": null,
    "provider": "android_device",
    "source": "api",
    "externalRequestId": "order-123",
    "queuedAt": "2026-06-16T10:00:00.000Z",
    "dispatchedAt": "2026-06-16T10:00:01.000Z",
    "sendingAt": "2026-06-16T10:00:02.000Z",
    "sentAt": "2026-06-16T10:00:03.000Z",
    "deliveredAt": "2026-06-16T10:00:09.000Z",
    "failedAt": null,
    "createdAt": "2026-06-16T10:00:00.000Z",
    "updatedAt": "2026-06-16T10:00:09.000Z"
  }
}

curl -X POST https://api.smsdora.com/messages/MESSAGE_ID/resend \
  -H "x-api-key: YOUR_API_KEY"

{
  "statusCode": 201,
  "message": "SMS queued for delivery",
  "data": {
    "id": "<new message id>",
    "resentFromMessageId": "<original failed message id>",
    "resentToMessageId": null,
    "recipient": "+212600000000",
    "message": "Your verification code is 4829",
    "status": "dispatching",
    "source": "api",
    "externalRequestId": "order-123",
    "device": {
      "id": "64b...",
      "deviceName": "My Samsung S24",
      "phoneNumber": "+212600000000"
    }
  }
}

curl https://api.smsdora.com/devices \
  -H "x-api-key: YOUR_API_KEY"

{
  "statusCode": 200,
  "data": [
    {
      "id": "64b...",
      "deviceId": "android-abc123",
      "deviceName": "My Samsung S24",
      "platform": "android",
      "brand": "Samsung",
      "model": "SM-S921B",
      "isActive": true,
      "status": "online",
      "batteryLevel": 87,
      "isCharging": false,
      "simLabel": "Orange MA",
      "simSlot": 1,
      "lastSeenAt": "2026-06-16T10:00:00.000Z"
    }
  ]
}

npm install @smsdora/otp

import { SmsdoraOtp } from '@smsdora/otp';

const otp = new SmsdoraOtp({
  apiKey: process.env.SMSDORA_SECRET_KEY!,
  baseUrl: 'https://api.smsdora.com',
  tokenSecret: process.env.OTP_TOKEN_SECRET,
});

// 1. Send a code
const challenge = await otp.send({
  recipient: '+2348031234567',
  purpose: 'login',
});

// 2. Verify what the user typed
const result = await otp.verify({
  challengeId: challenge.id,
  code: '123456',
});

if (result.verified) {
  const claims = otp.verifyToken(result.verificationToken!);
  console.log('verified phone:', claims.sub, 'for', claims.purpose);
}

await otp.send({
  recipient: '+2348031234567',
  purpose: 'login',
  codeLength: 6,
  ttlSeconds: 300,
  templateOverride: 'Your code is {{code}} ({{ttl}} min)',
  metadata: { userId: 'u_123' },
  idempotencyKey: 'order-42',
});

const result = await otp.verify({
  challengeId: challenge.id,
  code: '123456',
});

// result.verified          -> boolean
// result.status            -> challenge status
// result.attemptsRemaining -> number
// result.verificationToken -> string (present when verified)

import { RateLimitError, DeliveryError, AuthError } from '@smsdora/otp';

try {
  await otp.send({ recipient });
} catch (err) {
  if (err instanceof RateLimitError) {
    // err.retryAfterSeconds
  } else if (err instanceof DeliveryError) {
    // no online device / FCM failure
  } else if (err instanceof AuthError) {
    // bad key / missing scope
  }
}

{
  "statusCode": 400,
  "message": "No eligible device available",
  "error": "Bad Request"
}

curl -X POST https://api.smsdora.com/messages/send \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient": "+2348034125567",
    "message": "Hello from smsdora!"
  }'

const response = await fetch(
  "https://api.smsdora.com/messages/send",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipient: "+2348034125567",
      message: "Hello from smsdora!",
    }),
  }
);

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.smsdora.com/messages/send",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "recipient": "+2348034125567",
        "message": "Hello from smsdora!",
    },
)

print(response.json())

<?php
$ch = curl_init("https://api.smsdora.com/messages/send");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "x-api-key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "recipient" => "+2348034125567",
        "message" => "Hello from smsdora!",
    ]),
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

using var client = new HttpClient();
client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");

var payload = new {
    recipient = "+2348034125567",
    message = "Hello from smsdora!"
};

var response = await client.PostAsJsonAsync(
    "https://api.smsdora.com/messages/send",
    payload
);

var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);