All APIsMarkdownllms.txt

SafeCode Messaging & Bulk SMS API

Deliver any SMS (marketing broadcasts, alerts, or OTPs generated by your own backend) to mobile numbers. One API key, pay-as-you-go, prepaid client wallet.

Base URL: https://api.safecode.vip/v1

Dashboard: https://safecode.vip/otp-delivery-api
Human docs page: https://safecode.vip/developer-apis/messaging
Full-text (this file): https://safecode.vip/developer-apis/messaging.md
LLM index: https://safecode.vip/developer-apis/messaging/llms.txt

Sender ID is locked to SafeLTD. For a branded sender ID, contact the developer on WhatsApp: https://wa.me/+233538993178

How it works

You compose the message body (a promotion, an alert, or an OTP your backend generated) and we deliver it via SMS. For authentication use-cases, you generate the code and store it on your side. When the recipient enters it back into your app, you compare it against what you stored. SafeCode never verifies codes for you.

Authentication

All requests include your API key in the Authorization header. Keys are prefixed sfcd_live_ (production) or sfcd_test_ (sandbox).

Authorization: Bearer sfcd_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Quickstart

# Marketing message
curl -X POST https://api.safecode.vip/v1/messages/send \
  -H "Authorization: Bearer sfcd_live_xxxx_yyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "phone":   "+233201234567",
    "country": "GH",
    "message": "Flash sale! 20% off today only. Shop: https://ex.co/s"
  }'

# OTP you generated in your own backend
curl -X POST https://api.safecode.vip/v1/messages/send \
  -H "Authorization: Bearer sfcd_live_xxxx_yyyy" \
  -H "Content-Type: application/json" \
  -d '{
    "phone":   "+233201234567",
    "country": "GH",
    "message": "Your Acme code is 482910. Valid for 5 min."
  }'

Response:

{
  "id":          "req_01jz...",
  "status":      "sent",
  "price":       0.57000,
  "currency":    "GHS",
  "price_usd":   0.05000,
  "balance":     56.03000,
  "balance_usd": 4.95000
}

HTTP clients and bot protection

Requests carrying a valid Authorization: Bearer sfcd_... key bypass browser
bot-detection entirely. Python urllib/requests, Go net/http, Java, PHP,
Node fetch and plain curl all work with their default user agents. You do
not need to spoof a browser user agent. If you ever receive an HTML error page
instead of JSON, retry and then contact support with the Cf-Ray header value.

Rate limits

Every response carries rate-limit headers so batch jobs can pace themselves:

Supported countries

Additional countries roll out as we secure sender-ID clearance.

Key scopes

Keys issued from the dashboard carry every scope below. If you mint a restricted key, this is what each endpoint checks:

A key without the right scope receives forbidden_scope (403).

POST /messages/send

Sends an SMS with the exact message you supply. Balance is debited at dispatch; if the provider fails, the charge is refunded automatically. Sender ID is locked to SafeLTD.

Request body:

Idempotency: pass an Idempotency-Key header (UUID) so retries are safe. Duplicate requests return the original response without re-charging.

Response: 200 OK:

{
  "id":          "9f2c1d3e-…",
  "status":      "sent",
  "expires_at":  "2026-06-29T14:10:00.000Z",
  "price":       0.57000,
  "currency":    "GHS",
  "price_ghs":   0.57000,
  "price_usd":   0.05000,
  "balance":     56.03000,
  "balance_ghs": 56.03000,
  "balance_usd": 4.95000,
  "request_id":  "550e8400-…"
}

id is the message id to use with /messages/status. request_id identifies this HTTP call for support.

WhatsApp channel

Pass "channel": "whatsapp" to provision a WhatsApp verification number instead of sending an SMS. The response gains a whatsapp_phone field holding the number that was allocated for the recipient; hand that to your user to complete their WhatsApp verification. Everything else, pricing, idempotency, status lookups, webhooks, behaves as for SMS. Any other channel value returns unsupported_channel (400).

POST /messages/send-batch

Send up to 100 messages in one request. Each item is priced, charged and
dispatched independently, so one bad number never blocks the rest.

curl -X POST https://api.safecode.vip/v1/messages/send-batch \
  -H "Authorization: Bearer sfcd_live_xxxx_yyyy" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "messages": [
      { "phone": "+233201234567", "country": "GH", "message": "Your 5GB bundle is active." },
      { "phone": "+233207654321", "country": "GH", "message": "Your 10GB bundle is active." }
    ]
  }'

Response: 200 all sent, 207 partial, 402 nothing sent (no funds), 400 all rejected:

{
  "batch_id":       "8c1e...",
  "accepted":       2,
  "failed":         0,
  "rejected":       0,
  "total":          2,
  "currency":       "GHS",
  "total_cost":     1.14000,
  "balance":        54.89000,
  "results": [
    { "index": 0, "id": "req_01jz...", "phone": "+233201234567", "status": "sent" },
    { "index": 1, "id": "req_01k0...", "phone": "+233207654321", "status": "sent" }
  ]
}

Per-item status is one of sent, failed (provider rejected, charge refunded),
rejected (validation failed, never charged) or skipped (batch stopped because
the wallet ran out; nothing was charged for these).

POST /messages/bulk

Broadcast one freeform SMS to up to 500 recipients in a single call. Unlike
send-batch, every recipient gets the same message and the send runs in the
background: you get a job_id back immediately and poll for progress. Ghana only.

The wallet is debited for the full estimated cost up front so the job can never
overdraw mid-run; anything unused (invalid numbers, provider failures) is
refunded when the job completes.

action selects what the call does:

Estimate

curl -X POST https://api.safecode.vip/v1/messages/bulk   -H "Authorization: Bearer sfcd_live_xxxx_yyyy"   -H "Content-Type: application/json"   -d '{
    "action": "estimate",
    "message": "Flash sale! 20% off today only.",
    "recipients": ["+233201234567", "+233207654321", { "phone": "+233209999999" }]
  }'

Response: 200 OK:

{
  "total": 3,
  "invalid_count": 0,
  "invalid": [],
  "currency": "GHS",
  "sms_parts_per_recipient": 1,
  "sms_encoding": "gsm7",
  "unit_price": 0.14,
  "estimated_cost": 0.42,
  "current_balance": 56.03,
  "unit_price_usd": 0.01224,
  "estimated_cost_usd": 0.03672,
  "current_balance_usd": 4.95,
  "sufficient_balance": true
}

Long messages are billed per SMS part; sms_parts_per_recipient tells you the multiplier before you commit. sms_encoding is gsm7 (160 chars per part) or ucs2 (70 chars per part, used when the text contains characters outside the GSM alphabet such as emoji).

Send

Same body with "action": "send" (or no action). Returns 202 Accepted as soon as the job is queued:

{
  "ok": true,
  "job_id": "3b8e…",
  "total": 3,
  "invalid_count": 0,
  "invalid": [],
  "currency": "GHS",
  "estimated_cost": 0.42,
  "estimated_cost_ghs": 0.42,
  "estimated_cost_usd": 0.03672
}

Your client must have accepted the current bulk-messaging terms in the dashboard; otherwise the send is refused with terms_not_accepted (403) and estimate still works.

Status

curl -X POST https://api.safecode.vip/v1/messages/bulk   -H "Authorization: Bearer sfcd_live_xxxx_yyyy"   -H "Content-Type: application/json"   -d '{ "action": "status", "job_id": "3b8e…" }'

Returns { "ok": true, "job": { … } } where job.status is running, completed or failed, with processed, sent, failed, total_cost_usd, balance_after_usd and up to 200 per-recipient failures.

GET /messages/status?id={id}

curl "https://api.safecode.vip/v1/messages/status?id=req_01jz..." \
  -H "Authorization: Bearer sfcd_live_xxxx_yyyy"

Response: 200 OK:

{
  "id":           "req_01jz...",
  "phone_e164":   "+233201234567",
  "country_code": "GH",
  "status":       "delivered",
  "sent_at":      "2026-06-29T14:05:00.000Z",
  "delivered_at": "2026-06-29T14:05:07.412Z",
  "cost_usd":     0.05000
}

GET /balance

curl "https://api.safecode.vip/v1/balance" \
  -H "Authorization: Bearer sfcd_live_xxxx_yyyy"

Response: 200 OK:

{
  "balance":            56.03000,
  "balance_usd":       4.95000,
  "currency":          "GHS",
  "plan":              "live",
  "allowed_countries": ["GH"]
}

Low balance: below cost-per-message, /messages/send returns insufficient_balance (402).

Webhooks

Register a webhook URL in your dashboard. We POST a JSON event every time a message changes state, and when your wallet runs low. Failed deliveries retry up to 6 times with exponential backoff (1m → 5m → 30m → 2h → 12h → 24h).

Events:

message.* events are aliases of the legacy otp.* names, so subscribing to either
name works, and the event you receive is labelled with the name you subscribed to.
message.delivered / message.failed come from the carrier delivery report, so
they arrive after the sent response, which only confirms acceptance.

Low-balance payload:

{
  "event": "balance.low",
  "ts": 1729000000,
  "data": {
    "client_id":                     "8c1e...",
    "balance":                       3.20000,
    "threshold":                     5.00000,
    "currency":                      "GHS",
    "estimated_messages_remaining":  5,
    "depleted":                      false
  }
}

Configure the threshold, the alert email address, and the on/off switch under
client settings in your dashboard. Alerts repeat at most once every 6 hours and
re-arm once your balance recovers above twice the threshold.

Payload:

POST https://your-app.com/webhooks/safecode
Content-Type: application/json
X-SafeCode-Event: message.delivered
X-SafeCode-Signature: t=1729000000,v1=8a7f...e3

{
  "event": "message.delivered",
  "ts": 1729000000,
  "data": {
    "id":           "req_01jz...",
    "status":       "delivered",
    "country_code": "GH",
    "phone_e164":   "+233201234567"
  }
}

Verify the signature by computing HMAC-SHA256 over "<t>.<rawBody>" using your endpoint secret, then compare against v1.

// Node.js
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const [tPart, v1Part] = header.split(',');
  const t  = tPart.split('=')[1];
  const v1 = v1Part.split('=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Respond fast: return 2xx within 10s or the delivery is treated as failed and queued for retry.

Errors

All errors follow the same shape:

{
  "error":      "insufficient_balance",
  "message":    "Balance GH₵0.23 below price GH₵0.57",
  "request_id": "550e8400-..."
}