SMSHub API documentation

curl -X POST 'https://smshub.et/api/sms' \
  -H "Authorization: Bearer $SMSHUB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"msisdn":"0911234567","text":"Hello from SMSHub"}'

POST /api/sms HTTP/1.1
Host: smshub.et
Authorization: Bearer sk_live_4f9c…
Content-Type: application/json

# .env — keep this file out of Git (add it to .gitignore)
SMSHUB_API_KEY=sk_live_your_key

<?php
$key = getenv('SMSHUB_API_KEY');
if (!$key) {
    throw new RuntimeException('SMSHUB_API_KEY is not set');
}

// Node.js (server side only — never ship your key to the browser)
const key = process.env.SMSHUB_API_KEY;
if (!key) throw new Error('SMSHUB_API_KEY is not set');

import os

key = os.environ["SMSHUB_API_KEY"]  # raises KeyError if it is missing

curl -X POST 'https://smshub.et/api/sms' \
  -H "Authorization: Bearer sk_live_your_key" \
  -H 'Content-Type: application/json' \
  -d '{"msisdn":"0911234567","text":"Your MyShop verification code is 482193. Use it to confirm your phone number. It expires in 5 minutes."}'

<?php
$ch = curl_init('https://smshub.et/api/sms');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('SMSHUB_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'msisdn' => '0911234567',
        'text'   => 'Your MyShop verification code is 482193. Use it to confirm your phone number. It expires in 5 minutes.',
    ]),
]);
$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($status !== 200) {
    error_log('SMSHub ' . $status . ': ' . ($body['message'] ?? 'unknown'));
}

const res = await fetch('https://smshub.et/api/sms', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SMSHUB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    msisdn: '0911234567',
    text: "Your MyShop verification code is 482193. Use it to confirm your phone number. It expires in 5 minutes.",
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(`${body.error_type}: ${body.message}`);
console.log(body.data.credits_remaining);

import os, requests

res = requests.post(
    'https://smshub.et/api/sms',
    headers={'Authorization': f"Bearer {os.environ['SMSHUB_API_KEY']}"},
    json={'msisdn': '0911234567', 'text': "Your MyShop verification code is 482193. Use it to confirm your phone number. It expires in 5 minutes."},
    timeout=30,
)
body = res.json()
if res.status_code != 200:
    raise RuntimeError(f"{body['error_type']}: {body['message']}")
print(body['data']['credits_remaining'])

{
  "status": "success",
  "data": {
    "message_id": "msg_9b2d4e6f8a0c1e3b5d7f",
    "msisdn": "0911234567",
    "network": "ethio",
    "message_status": "sent",
    "credits_used": 1,
    "credits_remaining": 4999,
    "signature_applied": true,
    "phone_in_signature": false
  },
  "request_id": "req_8f3a1c09d2e4b7a1"
}

{
  "msisdn": "0911234567",
  "text": "Your order has shipped: https://yourshop.et/o/1043",
  "track_links": true
}

{
  "status": "success",
  "data": {
    "mode": "test",
    "message_status": "test_passed",
    "would_send": true,
    "msisdn": "0911234567",
    "final_text": "Hello from SMSHub\n\n- Abebe Bekele | 0911000000",
    "characters": 44,
    "character_limit": 160,
    "encoding": "gsm7",
    "credits_used": 0,
    "provider_contacted": false,
    "sms_sent": false
  },
  "request_id": "req_0c9d8e7f6a5b4c3d"
}

<?php
// Your own table, e.g.: otp_codes(phone PK, code_hash, expires_at, attempts)

function startOtp(PDO $db, string $phone): void {
    $code = str_pad((string) random_int(0, 999999), 6, '0', STR_PAD_LEFT);
    $db->prepare('REPLACE INTO otp_codes (phone, code_hash, expires_at, attempts)
                  VALUES (?, ?, DATE_ADD(NOW(), INTERVAL 5 MINUTE), 0)')
       ->execute([$phone, password_hash($code, PASSWORD_DEFAULT)]);

    $ch = curl_init('https://smshub.et/api/sms');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('SMSHUB_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'msisdn' => $phone,
            'text'   => "Your MyShop login code is {$code}. Use this code to sign in. It expires in 5 minutes. If you did not request this, ignore this message.",
        ]),
    ]);
    $body   = json_decode((string) curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    if ($status !== 200) {
        throw new RuntimeException(($body['error_type'] ?? 'network_error') . ' (' . ($body['request_id'] ?? '-') . ')');
    }
}

function checkOtp(PDO $db, string $phone, string $input): bool {
    $st = $db->prepare('SELECT code_hash, attempts FROM otp_codes WHERE phone = ? AND expires_at > NOW()');
    $st->execute([$phone]);
    $row = $st->fetch();
    if (!$row || $row['attempts'] >= 5) return false;            // expired or locked
    if (!password_verify($input, $row['code_hash'])) {
        $db->prepare('UPDATE otp_codes SET attempts = attempts + 1 WHERE phone = ?')->execute([$phone]);
        return false;
    }
    $db->prepare('DELETE FROM otp_codes WHERE phone = ?')->execute([$phone]);   // single use
    return true;
}

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

const codes = new Map(); // use Redis or your database in production
const hash = (s) => crypto.createHash('sha256').update(String(s)).digest();

export async function startOtp(phone) {
  const code = crypto.randomInt(0, 1_000_000).toString().padStart(6, '0');
  codes.set(phone, { hash: hash(code), expires: Date.now() + 5 * 60_000, attempts: 0 });

  const res = await fetch('https://smshub.et/api/sms', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SMSHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      msisdn: phone,
      text: `Your MyShop login code is ${code}. Use this code to sign in. It expires in 5 minutes. If you did not request this, ignore this message.`,
    }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`${err.error_type || res.status} (${err.request_id || '-'})`);
  }
}

export function checkOtp(phone, input) {
  const entry = codes.get(phone);
  if (!entry || entry.expires < Date.now() || entry.attempts >= 5) return false;
  if (!crypto.timingSafeEqual(hash(input), entry.hash)) { entry.attempts++; return false; }
  codes.delete(phone); // single use
  return true;
}

import hashlib, hmac, os, secrets, time
import requests

codes = {}  # use Redis or your database in production

def _hash(value):
    return hashlib.sha256(str(value).encode()).hexdigest()

def start_otp(phone):
    code = f"{secrets.randbelow(1_000_000):06d}"
    codes[phone] = {"hash": _hash(code), "expires": time.time() + 300, "attempts": 0}
    res = requests.post(
        "https://smshub.et/api/sms",
        headers={"Authorization": f"Bearer {os.environ['SMSHUB_API_KEY']}"},
        json={"msisdn": phone, "text": f"Your MyShop login code is {code}. Use this code to sign in. It expires in 5 minutes. If you did not request this, ignore this message."},
        timeout=30,
    )
    if res.status_code != 200:
        body = res.json()
        raise RuntimeError(f"{body.get('error_type')} ({body.get('request_id')})")

def check_otp(phone, user_input):
    entry = codes.get(phone)
    if not entry or entry["expires"] < time.time() or entry["attempts"] >= 5:
        return False
    if not hmac.compare_digest(_hash(user_input), entry["hash"]):
        entry["attempts"] += 1
        return False
    del codes[phone]  # single use
    return True

{
  "status": "error",
  "error_type": "invalid_msisdn",
  "message": "Invalid msisdn. Use an Ethiopian mobile number: 09xxxxxxxx (Ethio Telecom) or 07xxxxxxxx (Safaricom)…",
  "request_id": "req_1b2c3d4e5f6a7b8c"
}

{
  "status": "error",
  "error_type": "carrier_rejected",
  "message": "Safaricom did not accept this message: This message looks like a verification code without the required context and was blocked. OTP messages must clearly state what the code is for. Example: 'Your [Company] verification code is 472913. Please use this code to verify. If you did not request this, please ignore this message.' Your credit was refunded. Change the text and send again.",
  "request_id": "req_5d1e9a7c3b2f4a60"
}

Your MyShop verification code is 472913. Use it to confirm your phone number. It expires in 5 minutes. If you did not request this, ignore this message.

async function sendSms(msisdn, text) {
  const res = await fetch('https://smshub.et/api/sms', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SMSHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ msisdn, text }),
  });
  const body = await res.json().catch(() => ({}));
  if (res.ok) return body.data;                    // 200 — accepted by the carrier

  const err = new Error(`${res.status} ${body.error_type || 'error'}: ${body.message || res.statusText}`);
  err.retryable  = [429, 500, 502, 503].includes(res.status);   // safe to try again later
  err.retryAfter = Number(res.headers.get('Retry-After') || 0); // seconds (429 / 503)
  err.requestId  = body.request_id;                             // quote this to support
  throw err;
}

<?php
function sendSms(string $msisdn, string $text): array {
    $ch = curl_init('https://smshub.et/api/sms');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('SMSHUB_API_KEY'), 'Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => json_encode(['msisdn' => $msisdn, 'text' => $text]),
    ]);
    $raw    = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    $body = json_decode((string) $raw, true) ?: [];

    if ($status === 200) return $body['data'];       // accepted by the carrier
    $retryable = in_array($status, [0, 429, 500, 502, 503], true);   // 0 = network error
    throw new RuntimeException(sprintf('%d %s (%s)%s', $status, $body['error_type'] ?? 'error',
        $body['request_id'] ?? '-', $retryable ? ' — retry later' : ''));
}

import os, requests

RETRYABLE = {429, 500, 502, 503}

def send_sms(msisdn, text):
    res = requests.post(
        "https://smshub.et/api/sms",
        headers={"Authorization": f"Bearer {os.environ['SMSHUB_API_KEY']}"},
        json={"msisdn": msisdn, "text": text},
        timeout=30,
    )
    body = res.json() if res.content else {}
    if res.status_code == 200:
        return body["data"]                          # accepted by the carrier
    retry_after = int(res.headers.get("Retry-After", 0))
    raise RuntimeError(
        f"{res.status_code} {body.get('error_type')} ({body.get('request_id')})"
        + (f" — retry in {retry_after or 'a few'}s" if res.status_code in RETRYABLE else "")
    )

Your appointment is confirmed for 10:00 AM.

- Bethel Clinic | 0911000000

{
  "id": "evt_3f1c9a0b7d2e4c6a8b10",
  "type": "message.sent",
  "created": "2026-10-13T10:15:02+03:00",
  "data": {
    "message_id": "msg_9b2d4e6f8a0c1e3b5d7f",
    "msisdn": "0911234567",
    "network": "ethio",
    "status": "sent",
    "source": "api",
    "campaign_id": null,
    "credits_used": 1,
    "text": "Your order #1042 is ready.\n\n- MyShop",
    "error": null
  }
}

<?php
// webhook.php — SMSHub POSTs JSON here
$raw = file_get_contents('php://input');
if (!SmsHub::webhookValid($raw, $_SERVER['HTTP_X_SMSHUB_SIGNATURE'] ?? '', getenv('SMSHUB_WEBHOOK_SECRET'))) {
    http_response_code(400); exit;
}
$event = json_decode($raw, true);
switch ($event['type']) {
    case 'message.failed':     /* mark $event['data']['message_id'] as failed */ break;
    case 'campaign.completed': /* notify your team */ break;
    case 'credits.low':        /* top up */ break;
}
http_response_code(200);   // answer 2xx quickly; do slow work later

// Express — keep the RAW body for the signature check
app.post('/smshub/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const raw = req.body.toString('utf8');
  if (!SmsHub.webhookValid(raw, req.get('X-SMSHub-Signature'), process.env.SMSHUB_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(raw);
  if (event.type === 'message.failed') { /* … */ }
  res.sendStatus(200);
});

# Flask
@app.post('/smshub/webhook')
def smshub_webhook():
    raw = request.get_data()
    if not SmsHub.webhook_valid(raw, request.headers.get('X-SMSHub-Signature', ''), os.environ['SMSHUB_WEBHOOK_SECRET']):
        return '', 400
    event = request.get_json()
    if event['type'] == 'message.failed':
        pass  # …
    return '', 200

curl 'https://smshub.et/api/messages/msg_9b2d4e6f8a0c1e3b5d7f' \
  -H "Authorization: Bearer $SMSHUB_API_KEY"

{
  "status": "success",
  "data": {
    "message_id": "msg_9b2d4e6f8a0c1e3b5d7f",
    "msisdn": "0911234567",
    "network": "ethio",
    "message_status": "sent",
    "delivery_report": null,
    "source": "api",
    "campaign_id": null,
    "credits_used": 1,
    "created_at": "2026-10-13T10:15:02+03:00"
  },
  "request_id": "req_…"
}

curl 'https://smshub.et/api/balance' -H "Authorization: Bearer $SMSHUB_API_KEY"

{
  "status": "success",
  "data": { "credits": 4210, "credit_rule": { "ethio": 1, "safaricom": 2 }, "low_credit_threshold": 20 },
  "request_id": "req_…"
}

{
  "status": "success",
  "data": {
    "verification_id": "ver_a1b2c3d4e5f60718293a",
    "msisdn": "0911234567",
    "network": "ethio",
    "verification_status": "pending",
    "expires_at": "2026-10-13T10:25:02+03:00",
    "expires_in": 600,
    "code_length": 6,
    "max_attempts": 5,
    "message_id": "msg_…",
    "credits_used": 1,
    "credits_remaining": 4209
  },
  "request_id": "req_…"
}

{
  "status": "success",
  "data": {
    "verification_id": "ver_a1b2c3d4e5f60718293a",
    "msisdn": "0911234567",
    "valid": true,
    "verification_status": "approved",
    "attempts_left": 0,
    "message": "Code is correct."
  },
  "request_id": "req_…"
}

# 1. send a code
curl -X POST 'https://smshub.et/api/verify/send' \
  -H "Authorization: Bearer $SMSHUB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"msisdn":"0911234567","app_name":"MyShop"}'

# 2. check what the customer typed
curl -X POST 'https://smshub.et/api/verify/check' \
  -H "Authorization: Bearer $SMSHUB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"verification_id":"ver_…","code":"482193"}'

<?php
$sms = new SmsHub(getenv('SMSHUB_API_KEY'));

// sign-up form: send a code
$v = $sms->verifySend('0911234567', ['app_name' => 'MyShop']);
$_SESSION['verification_id'] = $v['verification_id'];

// next screen: check the code
$r = $sms->verifyCheck($_SESSION['verification_id'], $_POST['code']);
if ($r['valid']) {
    // phone number confirmed
}

import { SmsHub } from './smshub.js';
const sms = new SmsHub(process.env.SMSHUB_API_KEY);

const { verification_id } = await sms.verifySend('0911234567', { app_name: 'MyShop' });
// …later, with what the customer typed:
const { valid, attempts_left } = await sms.verifyCheck(verification_id, req.body.code);

from smshub import SmsHub
sms = SmsHub(os.environ['SMSHUB_API_KEY'])

v = sms.verify_send('0911234567', app_name='MyShop')
# …later, with what the customer typed:
r = sms.verify_check(v['verification_id'], code)
if r['valid']:
    print('phone confirmed')

{
  "status": "error",
  "error_type": "ip_not_allowed",
  "message": "Requests with this API key are only accepted from the IP addresses in its allowlist. This request came from 41.223.0.10.",
  "request_id": "req_…"
}

<?php
/** SMSHub client — save as SmsHub.php. Needs PHP 8.0+ with curl. */
final class SmsHub
{
    public function __construct(private string $key, private string $base = 'https://smshub.et') {}

    public function send(string $msisdn, string $text, bool $trackLinks = false): array
    { return $this->call('POST', '/api/sms', ['msisdn' => $msisdn, 'text' => $text, 'track_links' => $trackLinks]); }
    public function test(string $msisdn, string $text): array
    { return $this->call('POST', '/api/test', ['msisdn' => $msisdn, 'text' => $text]); }
    public function balance(): array   { return $this->call('GET', '/api/balance'); }
    public function message(string $id): array { return $this->call('GET', '/api/messages/' . rawurlencode($id)); }
    public function verifySend(string $msisdn, array $opts = []): array
    { return $this->call('POST', '/api/verify/send', ['msisdn' => $msisdn] + $opts); }
    public function verifyCheck(string $verificationId, string $code): array
    { return $this->call('POST', '/api/verify/check', ['verification_id' => $verificationId, 'code' => $code]); }

    /** Webhooks: true when the X-SMSHub-Signature header matches the raw body (and is under 5 minutes old). */
    public static function webhookValid(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
    {
        if (!preg_match('/t=(\d+),v1=([a-f0-9]{64})/', $header, $m) || abs(time() - (int)$m[1]) > $tolerance) return false;
        return hash_equals(hash_hmac('sha256', $m[1] . '.' . $rawBody, $secret), $m[2]);
    }

    private function call(string $method, string $path, ?array $body = null): array
    {
        $ch = curl_init($this->base . $path);
        curl_setopt_array($ch, [
            CURLOPT_CUSTOMREQUEST  => $method,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 30,
            CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $this->key, 'Content-Type: application/json', 'Accept: application/json'],
        ] + ($body !== null ? [CURLOPT_POSTFIELDS => json_encode($body)] : []));
        $raw = curl_exec($ch);
        $status = (int)curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $err = curl_error($ch);
        curl_close($ch);
        $json = json_decode((string)$raw, true);
        if ($status !== 200 || !is_array($json) || ($json['status'] ?? '') !== 'success') {
            throw new RuntimeException(($json['error_type'] ?? 'http_' . $status) . ': ' . ($json['message'] ?? $err ?: 'request failed'), $status);
        }
        return $json['data'];
    }
}

// $sms = new SmsHub(getenv('SMSHUB_API_KEY'));
// $sent = $sms->send('0911234567', 'Your order #1042 is ready.');
// echo $sent['message_id'], ' · ', $sent['credits_remaining'], " credits left\n";

// SMSHub client — save as smshub.js. Node 18+ (built-in fetch). Use it on your server, never in a browser.
import crypto from 'node:crypto';

export class SmsHub {
  constructor(key, base = 'https://smshub.et') { this.key = key; this.base = base; }

  send(msisdn, text, trackLinks = false) { return this.#call('POST', '/api/sms', { msisdn, text, track_links: trackLinks }); }
  test(msisdn, text)                     { return this.#call('POST', '/api/test', { msisdn, text }); }
  balance()                              { return this.#call('GET', '/api/balance'); }
  message(id)                            { return this.#call('GET', '/api/messages/' + encodeURIComponent(id)); }
  verifySend(msisdn, opts = {})          { return this.#call('POST', '/api/verify/send', { msisdn, ...opts }); }
  verifyCheck(verificationId, code)      { return this.#call('POST', '/api/verify/check', { verification_id: verificationId, code }); }

  /** Webhooks: pass the RAW request body (a string), the X-SMSHub-Signature header and your signing secret. */
  static webhookValid(rawBody, header, secret, tolerance = 300) {
    const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header || '');
    if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > tolerance) return false;
    const want = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest('hex');
    return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
  }

  async #call(method, path, body) {
    const res = await fetch(this.base + path, {
      method,
      headers: { Authorization: `Bearer ${this.key}`, 'Content-Type': 'application/json', Accept: 'application/json' },
      body: body ? JSON.stringify(body) : undefined,
    });
    const json = await res.json().catch(() => ({}));
    if (!res.ok || json.status !== 'success') {
      const e = new Error(`${json.error_type || 'http_' + res.status}: ${json.message || 'request failed'}`);
      e.status = res.status; e.type = json.error_type; e.requestId = json.request_id;
      throw e;
    }
    return json.data;
  }
}

// const sms = new SmsHub(process.env.SMSHUB_API_KEY);
// const { message_id, credits_remaining } = await sms.send('0911234567', 'Your order #1042 is ready.');

# SMSHub client — save as smshub.py. Needs: pip install requests
import hashlib, hmac, re, time
import requests

class SmsHubError(Exception):
    def __init__(self, status, error_type, message, request_id=None):
        super().__init__(f"{error_type}: {message}")
        self.status, self.error_type, self.request_id = status, error_type, request_id

class SmsHub:
    def __init__(self, key, base='https://smshub.et', timeout=30):
        self.key, self.base, self.timeout = key, base, timeout

    def send(self, msisdn, text, track_links=False):
        return self._call('POST', '/api/sms', {'msisdn': msisdn, 'text': text, 'track_links': track_links})
    def test(self, msisdn, text):
        return self._call('POST', '/api/test', {'msisdn': msisdn, 'text': text})
    def balance(self):
        return self._call('GET', '/api/balance')
    def message(self, message_id):
        return self._call('GET', '/api/messages/' + message_id)
    def verify_send(self, msisdn, **opts):
        return self._call('POST', '/api/verify/send', {'msisdn': msisdn, **opts})
    def verify_check(self, verification_id, code):
        return self._call('POST', '/api/verify/check', {'verification_id': verification_id, 'code': code})

    @staticmethod
    def webhook_valid(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
        m = re.search(r't=(\d+),v1=([a-f0-9]{64})', header or '')
        if not m or abs(time.time() - int(m.group(1))) > tolerance:
            return False
        want = hmac.new(secret.encode(), m.group(1).encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
        return hmac.compare_digest(want, m.group(2))

    def _call(self, method, path, body=None):
        r = requests.request(method, self.base + path, json=body, timeout=self.timeout,
                             headers={'Authorization': f'Bearer {self.key}', 'Accept': 'application/json'})
        try:
            data = r.json()
        except ValueError:
            data = {}
        if r.status_code != 200 or data.get('status') != 'success':
            raise SmsHubError(r.status_code, data.get('error_type', f'http_{r.status_code}'), data.get('message', 'request failed'), data.get('request_id'))
        return data['data']

# sms = SmsHub(os.environ['SMSHUB_API_KEY'])
# print(sms.send('0911234567', 'Your order #1042 is ready.')['message_id'])

<?php
function sendOtp(string $phone): string {
    $code = str_pad((string) random_int(0, 999999), 6, '0', STR_PAD_LEFT);

    $ch = curl_init('https://smshub.et/api/sms');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_HTTPHEADER     => [
            'Authorization: Bearer ' . getenv('SMSHUB_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'msisdn' => $phone,
            'text'   => "Your MyShop login code is {$code}. Use this code to sign in. It expires in 5 minutes. If you did not request this, ignore this message.",
        ]),
    ]);
    $body   = json_decode((string) curl_exec($ch), true);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 200) {
        throw new RuntimeException(($body['error_type'] ?? 'network_error') . ': ' . ($body['message'] ?? ''));
    }
    // Store a hash of $code with a 5-minute expiry — never the plain code.
    return $code;
}

async function sendSms(msisdn, text, attempt = 1) {
  const res = await fetch('https://smshub.et/api/sms', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SMSHUB_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ msisdn, text }),
  });
  const body = await res.json();

  // Only 429 and 502 are worth retrying.
  if ((res.status === 429 || res.status === 502) && attempt < 4) {
    const wait = res.status === 429
      ? Number(res.headers.get('Retry-After') || 1) * 1000
      : 2 ** attempt * 500;
    await new Promise(r => setTimeout(r, wait));
    return sendSms(msisdn, text, attempt + 1);
  }
  if (!res.ok) throw new Error(`${body.error_type}: ${body.message} (${body.request_id})`);
  return body.data;
}

import os, requests

res = requests.post(
    'https://smshub.et/api/sms',
    headers={'Authorization': f"Bearer {os.environ['SMSHUB_API_KEY']}"},
    json={'msisdn': '+251911234567', 'text': 'ትዕዛዝዎ ተልኳል። ዛሬ ይደርሳል።'},  # 70-char Unicode limit
    timeout=30,
)
print(res.status_code, res.json())