HEXSMS API · v1

SMS送信を
サービスにつなごう.

APIキーひとつではじめられます。国を選んで、一度に最大1,000件の番号へSMSを送信。番号ごとの結果も確認できます。

REST APIJSON最大1,000件 / リクエスト

POST/api/v1/messages
GET/api/v1/messages/{id}
POST/api/v1/messages/{id}/refresh
GET/api/v1/messages/countries

クイックスタート

APIキーを作成
登録・承認・OTPログイン後、APIキー管理で発行します。
クレジットを用意
アカウントのクレジットと単価をそのまま使用します。送信受付時に金額が差し引かれます。
SMSを送信して結果を確認
送信IDを保存し、ステータス照会APIで結果を確認します。

Base URL https://hexsms.com

実際の連携はHTTPSサーバーから呼び出してください。プレビュー環境では実際のキー発行とAPI送信には対応していません。

対応国

主なカバレッジ対象国

アメリカ合衆国
カナダ
イギリス
ドイツ
フランス
スペイン
イタリア
オランダ
スウェーデン
ノルウェー
デンマーク
ポーランド
ルーマニア
チェコ
オーストリア
スイス
アイルランド
ポルトガル
フィンランド
日本
韓国
中国
台湾
中華人民共和国香港特別行政区
シンガポール
マレーシア
インドネシア
フィリピン
タイ
ベトナム
インド
バングラデシュ
パキスタン
オーストラリア
ニュージーランド
ブラジル
メキシコ
南アフリカ
ナイジェリア
アラブ首長国連邦
サウジアラビア

国ごとの送信可否・単価・送信者登録条件は、アカウントと現地の通信網によって異なります。送信前に国別料金をご確認ください。

GET`/api/v1/messages/countries`

有効な国と実際の適用単価をAPIで確認できます。送信リクエストでは country で国を指定し、1回のリクエストには同じ国の番号を入れてください。料金が設定されていない国への送信は受け付けません。

200 OK

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

APIキーで認証

すべての外部APIリクエストに以下のヘッダーを含めてください。ログインCookieやOTPコードは不要です。

HTTP

Authorization: Bearer hex_live_発行されたキー

キーの原文は発行時に一度だけ表示されます。サーバーの環境変数に保管し、フロントエンドのコードには含めないでください。キーを無効化するかアカウントが停止されると使用できなくなります。キーは最大5個まで作成できます。

POST/api/v1/messages

一度に1,000件の番号へ送信

1つのメッセージ本文を複数の番号に送信します。リクエストを検証してから送信キューに登録し、すぐに応答します。番号ごとに異なる内容を送るには、別のリクエストと新しい Idempotency-Key を使用してください。

フィールド	形式	説明
`country` *	string	ISO 3166-1 alpha-2 の国コード。例: US, GB, JP, KR。デフォルトの国はありません。
`text` *	string	前後の空白を除いて1〜1,600文字。1回のリクエストのすべての番号に同じ内容を送信します。
`recipients` *	string[]	1〜1,000件の携帯電話番号。+国番号形式を推奨し、すべての番号は country と同じ国である必要があります。
`Idempotency-Key` *	header	8〜100文字の英数字・ハイフン・アンダースコア。リクエストごとに一意の値を指定してください。

無効な番号や重複番号が1つでもあると、リクエスト全体を拒否します。この場合は送信も差し引きも行いません。重複は国際形式に変換した番号で判定します。

cURL · 一括送信

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

202 Accepted · 送信キュー登録完了

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

応答が途切れた場合は、同じリクエストキーで再送してください。

同じアカウント・同じ Idempotency-Key・同じ内容と番号順で再試行すると、追加の送信や差し引きなしに既存の結果を返します（200, replayed: true）。本文が異なる場合は409です。キーを入れ替えても重複防止は維持されます。リクエストキーは期限なく保管されます。

料金の計算方法

番号数 × 通数（segments） × アカウント単価で計算します。UCS-2文字は70文字まで1通、以降は67文字単位です。GSM-7の基本文字は160文字まで1通、以降は153文字単位です。拡張文字は2文字分、絵文字はUTF-16の長さで計算します。unitPrice と cost はUSDTです。レスポンスの単価が実際の適用単価で、上記の0.025は例です。

GET/api/v1/messages/{id}

番号ごとの送信結果を確認

送信APIで受け取った id を使用します。同じアカウントでAPIから送信した履歴のみ照会できます。照会は保存済みの結果を返します。キャリアの最新結果が必要な場合は、次のステータス更新APIを先に呼び出してください。

cURL · ステータス照会

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

200 OK · 番号ごとの結果

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

limit は1〜1,000（デフォルト100）、offset は0〜1,000（デフォルト0）です。nextOffset が null なら最終ページです。summary は全番号のステータス別件数です。to は + を除いた国際番号形式、時刻はUnixミリ秒で返します。最初の送信時の番号順と照会順は異なる場合があります。各 message の id で区別してください。

DONE は受信完了を意味しません。

送信キューの処理が終わったという意味です。実際に届いたかどうかは、messages の status が DELIVERED かどうかで確認してください。

POST/api/v1/messages/{id}/refresh

ステータスコードについて

送信リクエストの state

PREPARING 準備中 · RUNNING 処理中 · PAUSED 一時停止 · DONE キュー処理完了 · CANCELED キャンセル

番号ごとの status	意味
QUEUED	送信待ちです。
SENDING	キャリアにリクエスト中です。
PENDING	キャリアが受け付け、最終的な受信結果を待っています。
DELIVERED	受信端末に配信されました。
UNDELIVERABLE	配信できませんでした。
EXPIRED	配信の有効期限が切れました。
REJECTED	リクエストが拒否されたか、処理エラーが発生しました。
CANCELED	送信待ちがキャンセルされました。
UNKNOWN	結果をまだ確認できていません。

キャリアのステータスコードが追加される可能性があるため、不明な status も処理してください。失敗理由は statusName、description、error で確認できます。

エラー時の確認方法

エラーレスポンスの形式

{ "error": "クレジットが不足しています。チャージしてから再度リクエストしてください。", "code": "INSUFFICIENT_CREDITS" }

HTTP	code	確認事項
403	`COUNTRY_NOT_ENABLED`	国別の送信料金と有効状態を確認してください。
400	`INVALID_COUNTRY`	country にISO国コードを指定してください。
400	`INVALID_BODY / INVALID_JSON / INVALID_TEXT`	JSONオブジェクトとメッセージ本文を確認してください。
400	`INVALID_RECIPIENTS / INVALID_PHONE / DUPLICATE_PHONE`	番号の数・形式・重複を確認してください。
400	`INVALID_IDEMPOTENCY_KEY / INVALID_PAGINATION`	リクエストキーまたはページの値を確認してください。
401	`UNAUTHORIZED`	Bearer APIキーがないか、無効です。
402	`INSUFFICIENT_CREDITS`	クレジットをチャージしてください。
403	`ACCOUNT_INACTIVE`	承認済みの有効なアカウントか確認してください。
404	`NOT_FOUND`	送信IDとアカウントの所有権を確認してください。
409	`IDEMPOTENCY_CONFLICT`	同じリクエストキーを異なる本文に使用しました。
413 / 415	`BODY_TOO_LARGE / UNSUPPORTED_MEDIA_TYPE`	128KiB以下のJSON本文を送信してください。
429	`RATE_LIMITED / REFRESH_TOO_SOON`	Retry-After の秒数だけ待ってから再リクエストしてください。
500 / 502	`INTERNAL_ERROR / PROVIDER_UNAVAILABLE`	しばらくしてから再試行してください。送信の再試行には同じリクエストキーを使用します。
503	`PREVIEW_ONLY`	プレビューでは実際のAPIを呼び出せません。

送信・照会・更新を合わせて、APIキーごとに1分あたり120回までリクエストできます。制限に達した場合は Retry-After ヘッダーを確認してください。APIはサーバー間連携用で、ブラウザからのCORS呼び出しには対応していません。

Node.js でつないでみよう

Node.js · サーバーで実行

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

リクエストキーは操作ごとに一度作成し、応答がなく再試行する場合も同じ値を使用してください。一度成功した操作を新しいキーで再送すると、別の送信として処理されます。