独自のコードから送信するためのSMS APIドキュメント

認証

Authorizationヘッダーにキーを送信します: Authorization: Bearer sso_live_...。キーは49文字で、sso_live_で始まります。アカウントごとに最大5個のキーを作成できます。ワークスペースでキーを取り消すと、すぐに機能しなくなります。料金表は公開されており、キーは必要ありません。

エラー

エラーはHTTPステータスコードと、安定したコードと人に表示できる文を含むJSONボディを使用します。リクエストが失敗しても課金されません。

HTTP/1.1 402 Payment Required
{ "error": { "code": "insufficient_credit", "message": "Short by $3.20. Add funds to send.", "total": "8.62480", "credit": "5.42000" } }

制限

• キーごとに1分間に240回のリクエストが可能で、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（Unix秒）に表示されます。
• 1リクエストあたり5,000件の番号、1テキストあたり2,000文字、1メッセージあたり10セグメント。
• 1アカウントあたり1分間に最大300件のメッセージが送信されます。
• send_atは10分後から30日前まで指定可能です。

料金

GET/api/v1/prices

GET/api/v1/prices/{country}

各国のメッセージ（1セグメント）あたりの価格を5桁のUSDで表示します。キーは不要です。

{ "price": { "country": "GB", "name": "United Kingdom", "dial_code": "+44", "price_usd": "0.00868" }, "updated": "2026-11-07" }

アカウント残高

GET/api/v1/account

{ "account": "SO8K2M4Q7X9TBA", "credit_usd": "41.27660", "currency": "USD" }

料金を見積もる

POST/api/v1/costs

送信と同じ本文を受け取り、送信や課金を行わずにコストを返します。各受信者のマージされたテキストがセグメントを決定するため、合計は正確です。

{
  "recipients": 2, "segments_min": 1, "segments_max": 1, "encoding": "gsm7", "messages_billed": 2,
  "total_usd": "0.01426", "credit_usd": "41.27660", "enough_credit": true,
  "countries": [ { "country": "GB", "recipients": 1, "price_usd": "0.00868", "subtotal_usd": "0.00868" },
                 { "country": "US", "recipients": 1, "price_usd": "0.00558", "subtotal_usd": "0.00558" } ],
  "dropped": [], "too_long": null
}

送信を作成

POST/api/v1/sends

1つのテキストを1つまたは複数の番号に送信します。送信が承認されると全体のクレジットが引き落とされ、失敗したメッセージは1件ずつ返金されます。

HTTP/1.1 201 Created
{
  "send": { "id": "CA7Q29XMAB4DFK", "status": "queued", "source": "api", "recipients": 2, "segments_max": 1,
            "encoding": "gsm7", "cost_usd": "0.01426", "refunded_usd": "0.00000", "client_ref": "bookings-1107",
            "send_at": null, "created_at": "2026-11-07T10:12:03.120Z", "started_at": null, "finished_at": null },
  "dropped": [ { "value": "+4412", "code": "too_short", "message": "Too short" } ]
}

送信できない番号はdroppedにリストされ、課金されません。コード: no_country_code, too_short, too_long, not_a_number, wrong_length, not_covered, duplicateおよびsuppressed（送信禁止リストに登録されている場合）。

送信を取得または一覧表示

GET/api/v1/sends/{id}

GET/api/v1/sends?limit=25&before={id}

1回の送信には、メッセージステータスごとのcountsが含まれます。リストは新しい順に表示され、次のページにはnext_beforeをbeforeとして渡します。ワークスペースからの送信もここに表示され、source: "web"が付きます。

メッセージ

GET/api/v1/sends/{id}/messages?status=failed&limit=100

GET/api/v1/messages/{id}

{ "message": { "id": "MS3D8RW0K2QJ7N", "send_id": "CA7Q29XMAB4DFK", "to": "+447700900461", "country": "GB",
  "segments": 1, "price_usd": "0.00868", "status": "delivered", "reason": null, "reason_text": null,
  "created_at": "2026-11-07T10:12:03.120Z", "sent_at": "2026-11-07T10:12:04.010Z", "done_at": "2026-11-07T10:12:09.400Z" } }

送信をキャンセル

POST/api/v1/sends/{id}/cancel

開始していない予約送信のみキャンセル可能です。全額がクレジットに戻り、回答にはrefunded_usdが含まれます。

ウェブフック

ワークスペース（APIおよびWebhook）にhttps URLを設定します。メッセージが配信されたか失敗したときにイベントをPOSTします。APIとワークスペースからの送信の両方に対応します。10秒以内に2xxステータスで応答してください。配信失敗は最大7回再試行されます: すぐに、1分後、5分後、30分後、1時間後、2時間後、3時間後。ワークスペースには各試行のステータスと回答が表示されます。

POST https://your-server.example/sms-events
X-SSO-Event: message.delivered
X-SSO-Delivery: evt_5a0c9e31d2b7f4a68c
X-SSO-Timestamp: 1794132729
X-SSO-Signature: sha256=8f1c...e42a

{ "id": "evt_5a0c9e31d2b7f4a68c", "event": "message.delivered", "created": "2026-11-07T10:12:09.000Z",
  "data": { "message": { "id": "MS3D8RW0K2QJ7N", "send_id": "CA7Q29XMAB4DFK", "to": "+447700900461", "country": "GB",
  "segments": 1, "price_usd": "0.00868", "status": "delivered", "reason": null, "reason_text": null,
  "client_ref": "bookings-1107", "created_at": "...", "sent_at": "...", "done_at": "..." } } }

署名は、署名シークレット（sso_whk_で始まる）を使用したtimestamp + "." + raw bodyのHMAC-SHA256です。解析前に生の本文で確認し、5分以上前のタイムスタンプを拒否し、配信IDを使用して繰り返しを無視します。

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), before JSON.parse
export function verify(rawBody, headers, secret) {
  const ts = headers["x-sso-timestamp"];
  const sig = headers["x-sso-signature"] || "";
  const want = "sha256=" + crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
}

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts = headers.get("X-SSO-Timestamp", "")
    sig = headers.get("X-SSO-Signature", "")
    mac = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256)
    want = "sha256=" + mac.hexdigest()
    fresh = ts.isdigit() and abs(time.time() - int(ts)) < 300
    return fresh and hmac.compare_digest(sig, want)

<?php
function verify(string $rawBody, string $ts, string $sig, string $secret): bool {
  $want = "sha256=" . hash_hmac("sha256", $ts . "." . $rawBody, $secret);
  return ctype_digit($ts) && abs(time() - (int)$ts) < 300 && hash_equals($want, $sig);
}

イベント: message.delivered、message.failed、およびSend test eventボタンからのtest。

ステータスと理由

失敗理由（reasonフィールド）: