SMS/RCS / はじめに
SMS メッセージを送信し、配信結果のレポートを収集するための HTTP ベース API です。
できること
- 予約配信 … 顧客リストの CSV をアップロードし、指定日時に配信する
- 即時配信 … 最大 10 件の宛先にその場で配信する。リストのアップロードは不要
- 配信のキャンセル … 予約した配信を、配信開始前に取り消す
- 結果の回収 … 配信全体のサマリー（成功 / 失敗 / スキップ件数）と、宛先ごとの到達ステータスを取得する
- URL 短縮 … メッセージ本文中の URL を短縮 URL に置き換える（共通仕様 / 短縮 URL）
このドキュメントの構成
- はじめに … 本ページ。プロダクトの概要・主要な概念・仕様書の読み方。
- クイックリファレンス … 認証・エンドポイント一覧・利用シナリオごとの配信の流れ・電話番号の形式など、最初に押さえる要点。
- API リファレンス … OpenAPI から自動生成される API 仕様。
- 共通仕様 … Mico の配信システムの横断仕様。プロダクトをまたいで挙動が同じもの。ヘッダーの「共通仕様」から入れます（レート制限 / 短縮 URL）。
どのエンドポイントをどの順で呼ぶかは、クイックリファレンスの「利用シナリオと配信の流れ」にシーケンス図付きでまとめてあります。
レート制限
各エンドポイントには、受け付けられるリクエスト数の上限があります。特定の値に依存せず、上限に達した場合の処理を必ず実装してください。
- SMS/RCS / レート制限 … エンドポイントごとの上限値と、上限の範囲内で要件を満たすための API の選び方
- 共通仕様 / レート制限 … 上限の考え方・上限を数える単位・ポーリング間隔と再試行の実装方針
主要な概念
| 用語 | 意味 |
|---|---|
site_uuid | 配信元となるサイトの識別子。SMS 配信 API のすべてのコールでヘッダに指定する |
upload_id | 配信リスト CSV のアップロード 1 回に対して払い出される識別子 |
delivery_list_id | アップロードが完了した配信リストの識別子。配信予約時に指定する |
delivery_request_id | 配信リクエスト 1 件の識別子。キャンセル・サマリー・レポートの取得に使う |
idempotency_key | 冪等性キー。呼び出し側で生成する、リクエストごとに一意な文字列。UUID v4 の使用を推奨 |
仕様書の読み方
API リファレンス は OpenAPI 仕様から自動生成しています。読むうえで前提になる表記のルールをまとめます。
必須フィールドと任意フィールド
必須のフィールドには型の隣に REQUIRED バッジが付きます。バッジの無いフィールドは任意です。
Notion 版ではフィールド名の末尾に ? を付けて任意であることを表していました（例: cursor?）。本サイトでは REQUIRED バッジで表すため ? は使いません。どちらの表記でも、実際に送受信する JSON のキー名に ? は含まれません。
波括弧には 2 つの意味がある
| 表記 | 意味 |
|---|---|
{delivery_request_id} | URL パス中のプレースホルダ。実際の ID に置き換える |
{{name}} | メッセージ本文の差し込み変数。宛先ごとの値に展開される |
差し込み変数の名前は、予約配信では配信リスト CSV の 3 カラム目以降のヘッダ名に、即時配信では recipients[].parameters[].key に対応します。
値の形式
- 日時 … リクエスト・レスポンスともすべて UTC の ISO 8601 形式（例:
2025-11-15T18:00:00Z） - ID …
upload_id/delivery_list_id/delivery_request_idはいずれも UUID - 電話番号 … 正規化されません。CSV やリクエストで指定した表記が、そのまま配信レポートで返ります
エラーレスポンスの読み方
エラーはすべて共通の形（code / message / details）で返ります。入力値が原因の場合は details.field_violations に、どのフィールドが何の理由で弾かれたかが入ります。具体的な形は クイックリファレンスの「エラーレスポンス」を参照してください。
field の命名は 2 種類あるfield_violations[].field に入る名前は、リクエストボディの検証で弾かれた場合はJSON のキーと同じスネークケース（例: delivery_list_id）ですが、パス・クエリパラメータや後段の検証で弾かれた場合はキャメルケース（例: deliveryListId、 uploadId、pageSize）になります。同じフィールドがどちらの表記でも現れうるため、 field の値で分岐する実装では両方を考慮してください。
コードサンプル
各エンドポイントのページには、リクエストのサンプルコード（curl・各言語）と、ステータスコード（200 / 400 / 401 など）ごとのレスポンスが付きます。
レスポンスの Example (auto) はスキーマから自動生成した例です。仕様として定義された例がある場合は、その隣に例の名前でタブが並びます。たとえば 401 には missingAuthorizationHeader / invalidToken / missingSiteUuidHeader の 3 つがあり、認証エラーの原因ごとに実際のレスポンスを確認できます。