API リファレンス：文面

文面（messages）の操作です。共通の決まり（認証・レート制限・エラーの形）は概要を、型の詳細はスキーマを参照してください。

AI・コーディングエージェント向けにこのページの Markdown 版とllms.txtがあります。

• GET /api/v1/messages　文面の一覧（listMessages）
• POST /api/v1/messages　文面の作成（createMessage）
• GET /api/v1/messages/{message_id}　文面の取得（getMessage）
• PATCH /api/v1/messages/{message_id}　文面の更新（updateMessage）
• DELETE /api/v1/messages/{message_id}　文面の削除（deleteMessage）
• POST /api/v1/messages/{message_id}/duplicate　文面の複製（duplicateMessage）
• GET /api/v1/message_variables　文面で使える変数の一覧（listMessageVariables）
• GET /api/v1/message_examples　文面の例文の一覧（listMessageExamples）
• POST /api/v1/message_previews　文面のプレビュー（previewMessage）
• POST /api/v1/messages/estimate　SMS の文字数と課金通数の見積（estimateSmsSegments）

GET /api/v1/messages

文面の一覧

operationId：listMessages　必要なスコープ：messages:read

パラメータ

名前	場所	型	必須	説明
channel	クエリ	string（null 可）	—	値：sms・email（今後増えることがある）
limit	クエリ	integer	—	1〜200・既定値 50
cursor	クエリ	string（null 可）	—	—

応答

ステータス	説明	型
200	成功	MessageListOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

POST /api/v1/messages

文面の作成

operationId：createMessage　必要なスコープ：messages:write

リクエストの本文（JSON）

型：MessageIn（必須）

項目	型	必須	説明
channel	string	必須	値：sms・email（今後増えることがある）
subject	string（null 可）	—	—
body	string（null 可）	—	—
body_html	string（null 可）	—	—
header_image_url	string（null 可）	—	—
link_url	string（null 可）	—	—
link_params	object（項目は未掲載）	—	既定値 {}
blocks	任意の値 の配列（null 可）	—	—

応答

ステータス	説明	型
201	成功	MessageOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
409	状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

GET /api/v1/messages/{message_id}

文面の取得

operationId：getMessage　必要なスコープ：messages:read

パラメータ

名前	場所	型	必須	説明
message_id	パス	string（uuid）	必須	—

応答

ステータス	説明	型
200	成功	MessageOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
404	対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

PATCH /api/v1/messages/{message_id}

文面の更新

operationId：updateMessage　必要なスコープ：messages:write

パラメータ

名前	場所	型	必須	説明
message_id	パス	string（uuid）	必須	—

リクエストの本文（JSON）

型：MessagePatch（必須）

項目	型	必須	説明
channel	string（null 可）	—	値：sms・email（今後増えることがある）
subject	string（null 可）	—	—
body	string（null 可）	—	—
body_html	string（null 可）	—	—
header_image_url	string（null 可）	—	—
link_url	string（null 可）	—	—
link_params	object（項目は未掲載）（null 可）	—	—
blocks	任意の値 の配列（null 可）	—	—

応答

ステータス	説明	型
200	成功	MessageOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
404	対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

DELETE /api/v1/messages/{message_id}

文面の削除

operationId：deleteMessage　必要なスコープ：messages:write

パラメータ

名前	場所	型	必須	説明
message_id	パス	string（uuid）	必須	—

応答

ステータス	説明	型
204	成功（本文なし）	—
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
404	対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404	Error
409	状態の衝突（invalid_request）。message_in_use（ステップが使っている文面）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

POST /api/v1/messages/{message_id}/duplicate

文面の複製

operationId：duplicateMessage　必要なスコープ：messages:write

複製（実体コピー）。作成と同じ検証・権限（body_html の直書きは owner / admin だけ）。

パラメータ

名前	場所	型	必須	説明
message_id	パス	string（uuid）	必須	—

応答

ステータス	説明	型
201	成功	MessageOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
404	対象が見つからない（not_found）。他のテナントの ID を指した時も同じ 404	Error
409	状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

GET /api/v1/message_variables

文面で使える変数の一覧

operationId：listMessageVariables　必要なスコープ：messages:read

パラメータ

名前	場所	型	必須	説明
campaign_id	クエリ	string（uuid）	必須	—

応答

ステータス	説明	型
200	成功	MessageVariablesOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
404	campaign_id のキャンペーンが見つからない（not_found）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

GET /api/v1/message_examples

文面の例文の一覧

operationId：listMessageExamples　必要なスコープ：messages:read

全プランで使える。プランの上限（1シナリオのステップ数）は、作った文面をステップに置く時に見る。

SMS の【ショップ名】は置き場。店名に書き換えないままでは、そのシナリオを有効化できない。

パラメータ

名前	場所	型	必須	説明
channel	クエリ	string（null 可）	—	値：sms・email（今後増えることがある）

応答

ステータス	説明	型
200	成功	MessageExampleListOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

POST /api/v1/message_previews

文面のプレビュー

operationId：previewMessage　必要なスコープ：messages:read

リクエストの本文（JSON）

型：MessagePreviewIn（必須）

項目	型	必須	説明
campaign_id	string（uuid）	必須	—
subject	string（null 可）	—	—
blocks	任意の値 の配列	必須	—

応答

ステータス	説明	型
200	成功	MessagePreviewOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
404	campaign_id のキャンペーンが見つからない（not_found）	Error
409	状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error

POST /api/v1/messages/estimate

SMS の文字数と課金通数の見積

operationId：estimateSmsSegments　必要なスコープ：messages:read

SMS 本文から文字数と課金通数の目安を返す。保存しない（読み取りスコープ messages:read）。数え方は文面の保存時に入る通数の目安（sms_segments）と同じ。

• 目安である：URL の変数は送信時と同じ長さで展開するが、商品名（{{product_name}}）は字面（16文字）のまま数える。実際の商品名の長さは使うキャンペーンで変わるので、送信時の通数とはずれうる（実績は配信の segments）
• キャリアが分からないのでワーストケース（docomo の刻み）で数える
• 本文が上限（URL 展開後で660文字）を超えると 422 sms_body_too_long
• POST なのでテストキーでは OKAERI-Dry-Run: true が付くが、そもそも何も保存しない

リクエストの本文（JSON）

型：SmsEstimateIn（必須）

項目	型	必須	説明
body	string	必須	1文字以上

応答

ステータス	説明	型
200	成功	SmsEstimateOut
401	APIキーが無効・失効（authentication_error）	Error
403	スコープ不足（permission_error / scope_insufficient）・プランの上限（plan_limit_exceeded）・APIキーではできない操作（session_required 等）	Error
409	状態の衝突（invalid_request）。idempotency_key_in_progress（同じ Idempotency-Key の要求が処理中）	Error
422	パラメータ不正（invalid_request）。param に対象の項目名、message に理由（日本語）	Error
429	レート制限の超過（rate_limit_error）。上限はテナント単位（テナント内の全キーの合計）の直近60秒の回数で、プラン別に Free 60 / Starter 60 / Growth 300 / Pro 1,000 回。個別の設定がある場合は応答ヘッダ X-RateLimit-Limit の値が正。Retry-After（秒）の後に再試行する	Error
5XX	サーバ側の失敗（api_error）。request_id を添えて問い合わせてください。時間をおいた再試行で解消することがある（POST は同じ Idempotency-Key を付けて再試行する）	Error