REST, SMPP, webhooks, and route controls

An SMS API for teams that need to know what happened

Send OTP, transactional, and campaign messages through the route that fits the use case. SDKs, idempotency keys, signed webhooks, and delivery events turn messaging from a hopeful request into an observable workflow.

Get Started → See Coverage

node.js

python

php

curl

// npm install @onemessage/sdk
import One Message from '@onemessage/sdk';

const client = new One Message({ apiKey: 'ark_live_...' });

const msg = await client.messages.create({
  to:      '+447911123456',
  sender:  'OneMSG',
  body:    'Your code is 4821',
  route:   'local_operator'  // or 'local_reseller'
});

console.log(msg.id);
// → msg_8f3a1c...

# pip install onemessage
from onemessage import Client

client = Client(api_key="ark_live_...")

msg = client.messages.create(
    to="+447911123456",
    sender="OneMSG",
    body="Your code is 4821",
    route="local_operator",  # or "local_reseller"
)

print(msg.id)
# → msg_8f3a1c...

// composer require onemessage/sdk
use One Message\Client;

$client = new Client(['api_key' => 'ark_live_...']);

$msg = $client->messages->create([
  'to'     => '+447911123456',
  'sender' => 'OneMSG',
  'body'   => 'Your code is 4821',
  'route'  => 'local_operator', // or 'local_reseller'
]);

echo $msg->id;

curl https://api.onemessage.live/v1/messages \
  -H "Authorization: Bearer ark_live_..." \
  -H "Idempotency-Key: req_8a3..." \
  -d '{
    "to": "+447911123456",
    "sender": "OneMSG",
    "body": "Your code is 4821",
    "route": "local_operator"
  }'

{ "id": "msg_8f3a1c...", "status": "queued" }

Quickstart

From sandbox to live traffic without mystery

Start with a test key, understand the response, wire up webhooks, and move live when routes and sender setup are ready.

Install the SDK

Pick the SDK that matches your stack. Or skip it and hit the REST API directly.

npm install @onemessage/sdk

Drop in your API key

Grab it from the dashboard. Test keys start with ark_test_, live with ark_live_.

ONE_MESSAGE_API_KEY=ark_live_...

Send your first message

One call. Idempotent, signed responses, sandbox-friendly. Webhooks fire on delivery.

client.messages.create({...})

Endpoints

A surface area built around the full message lifecycle

Send, inspect, verify, batch, register senders, check balance, and receive webhooks from one consistent API surface.

POST

/v1/messages

Send a single SMS, OTP, or transactional message.

POST

/v1/messages/batch

Send up to 10,000 messages in one call with per-recipient personalisation.

GET

/v1/messages/:id

Retrieve delivery status, segments, and DLR history for a message.

GET

/v1/messages

List messages with filters (status, sender, date range, route).

POST

/v1/otp/send

Generate and send a one-time code with a stored template.

POST

/v1/otp/verify

Verify a code submitted by the end user.

POST

/v1/voice/calls

Trigger a bulk voice broadcast or single IVR call.

POST

/v1/senders

Submit a new sender ID for compliance approval.

GET

/v1/balance

Check current credit balance and recent top-ups.

POST

/v1/webhooks

Webhooks

Delivery events that hold up under audit

Every event is signed, retryable, and designed for clean reconciliation in the systems your team already trusts.

HMAC-SHA256 signaturesVerify every payload came from us with the secret from your dashboard.
Smart retriesUp to 7 retries over 24 hours with exponential backoff if your endpoint 5xxs.
Event typesmessage.delivered, message.failed, otp.verified, sender.approved, balance.low.
Replay protectionEach delivery has a unique event_id you can dedupe against.

webhook payload

POST /your-webhook-endpoint
X-One Message-Signature: t=1700000000,v1=a3f...
Content-Type: application/json

{
  "event_id": "evt_8a3f...",
  "type": "message.delivered",
  "created": 1700000000,
  "data": {
    "id":        "msg_8f3a...",
    "to":        "+447911123456",
    "operator":  "Vodafone UK",
    "latency_ms": 1840,
    "segments":  1
  }
}

An SMS API for teams that need to know what happened

From sandbox to live traffic without mystery

A surface area built around the full message lifecycle

Meet developers where they already work

Delivery events that hold up under audit

Build the integration before the stakes get high