API インターフェース

Oblic API を使うと、サーバーから組織としてメール、SMS、WhatsApp を送信して結果を確認し、自社システムでの連絡先の操作を記録できます。送信に使用するテンプレート、送信者 ID、連絡先リスト、Webhook、サブアカウントも管理できます。サーバーは API キーで呼び出します。

ベース URL

すべてのパスは https://api.oblic.app/external/v1 で始まります。ただし、連絡先リストの従来のパスは https://api.oblic.app/external/contact-list/v1 で始まります。

API の呼び出し

呼び出しに使用するキー

curl https://api.oblic.app/external/v1/key \
  -H 'Authorization: Bearer YOUR_API_KEY'
  • API キーを送信する形式は Authorization: Bearer <key> です。設定 → APIの統合で、それぞれ必要なスコープを指定してキーを作成します。キーはサーバーに保管してください。ブラウザーやモバイルアプリ内のキーは誰でも読み取れます。認証を参照してください。
  • 本文のある応答は共通の JSON エンベロープを使います。{"status": "success", "data": …, "errors": null}、または "status": "error" とエラーを返し、各エラーにはコード(cd)とメッセージがあります。エラーを参照してください。
  • プラットフォームはサブアカウントを通じてテナントとして操作します。キーは一つで、各リクエストの X-Oblic-On-Behalf-Of にテナントを指定します。
  • キーの状態が保持されている間に再試行し、同じ Idempotency-Key と本文を使用します。メールと WhatsApp のキーは Redis に 24 時間保持されます。キャッシュの消失や期限切れにより再送が可能になる場合があります。SMS のキーは保存されたメッセージ行に残り、時間による期限切れはありません。永久に一度だけ実行される保証ではありません。メッセージを参照してください。

タイムスタンプ

時点を表す応答のタイムスタンプには ISO 8601 のオフセットが含まれます。たとえば 2026-10-30T20:00:00Z と 2026-10-31T01:30:00+05:30 は同じ時点です。利用者のタイムゾーンで表示する前にオフセットを解析してください。JavaScript の new Date(value) と Java の OffsetDateTime.parse(value) はこれを行います。オフセットのない値に Z を追加したり、時点を LocalDateTime として解析したりしても同じにはなりません。

日付だけの値は日付のままです。明示的なローカルスケジュールは別の契約で、時刻をタイムゾーンフィールドと組み合わせます。時刻だけを単独の時点として扱いません。

エンドポイント

「必要権限」はルートに必要なキーのスコープで、複数ある場合はいずれか一つで足ります。一部のルートでは所有者または管理者ロールのキーも必要です。スコープとロールは権限を与えますが、サービス設定やリソースの適格性によってリクエストが拒否される場合があります。

API メッセージ

メソッドパス機能必要権限
GET/external/v1/messagesAPI で送信したメッセージを新しい順に取得messages:read
POST/external/v1/messages/email確認済み送信者から、独自の HTML またはテンプレートでメールを送信email:send
POST/external/v1/messages/smsアカウントの DLT テンプレートに一致する SMS を送信sms:send
POST/external/v1/messages/whatsapp承認済み WhatsApp テンプレート、または 24 時間以内の返信を送信whatsapp:send
GET/external/v1/messages/{messageId}API で送信したメッセージとその結果を取得messages:read

レポート

メソッドパス機能必要権限
GET/external/v1/reports/summary期間中に送信したメッセージの結果をチャネルと状態別に取得messages:read

メールテンプレート

メソッドパス機能必要権限
GET/external/v1/templatesアカウントのメールテンプレートを新しい順に取得email:send または templates:manage
POST/external/v1/templatesHTML からメールテンプレートを作成templates:manage、所有者または管理者キー
GET/external/v1/templates/{id}メールテンプレートと HTML、対応する変数を取得email:send または templates:manage
PUT/external/v1/templates/{id}HTML から作成したメールテンプレートを置換templates:manage、所有者または管理者キー
DELETE/external/v1/templates/{id}メールテンプレートを削除templates:manage、所有者または管理者キー

SMS ヘッダーとテンプレート

必要なスコープとロールがあっても、SMS レジストリを変更できるのは設定済みのレジストリアカウントだけです。これらのルートは DLT に登録済みのヘッダーとテンプレートを記録するもので、DLT への登録は行いません。一覧には非アクティブなものを含む承認済みテンプレートが表示されます。送信可能かどうかには追加のチェックがあります。

メソッドパス機能必要権限
GET/external/v1/sms/accountアカウントの SMS 制限と今月の送信数を取得sms:send または templates:manage
GET/external/v1/sms/sendersアカウントの DLT ヘッダーを取得sms:send または templates:manage
GET/external/v1/sms/templatesアカウントの DLT テンプレートを取得sms:send または templates:manage
POST/external/v1/sms/templatesDLT 登録済みのテンプレートを Oblic に記録templates:manage、所有者または管理者キー
PUT/external/v1/sms/senders/{senderId}DLT ヘッダーを記録、または既定の指定を変更templates:manage、所有者または管理者キー
DELETE/external/v1/sms/senders/{senderId}DLT ヘッダーを削除templates:manage、所有者または管理者キー
PUT/external/v1/sms/templates/{id}DLT テンプレートを変更templates:manage、所有者または管理者キー
DELETE/external/v1/sms/templates/{id}DLT テンプレートを削除templates:manage、所有者または管理者キー
PUT/external/v1/sms/templates/{id}/sharingテンプレートの送信を、すべて・指定のサブアカウントに許可するか、どれにも許可しないtemplates:manage、所有者または管理者キー

WhatsApp 番号とテンプレート

メソッドパス機能必要権限
GET/external/v1/whatsapp/connectionアカウントに接続された WhatsApp 番号を取得whatsapp:send または templates:manage
POST/external/v1/whatsapp/connectionアカウントの WhatsApp Business 番号を接続または置換templates:manage、所有者または管理者キー
DELETE/external/v1/whatsapp/connectionアカウントの WhatsApp 番号を切断templates:manage、所有者または管理者キー
GET/external/v1/whatsapp/templatesアカウントの WhatsApp テンプレートと Meta の審査結果を取得whatsapp:send または templates:manage
POST/external/v1/whatsapp/templatesWhatsApp テンプレートを Meta に審査依頼templates:manage、所有者または管理者キー
GET/external/v1/whatsapp/recipients/{number}その番号にアカウントが現在送信できる内容を取得whatsapp:send または templates:manage

送信者 ID

メソッドパス機能必要権限
GET/external/v1/identities送信ドメインとアドレス、および各確認状態を取得email:send または identities:manage
POST/external/v1/identities確認対象の送信ドメインまたはアドレスを追加identities:manage
DELETE/external/v1/identities/{identityId}送信者 ID を削除identities:manage

連絡先リスト

メソッドパス機能必要権限
POST/external/contact-list/v1/add連絡先リストを作成contacts:manage
POST/external/contact-list/v1/{contactListId}/addリストに連絡先を追加contacts:manage
GET/external/contact-list/v1/{nextIndex}/{limit}アカウントの連絡先リストをページ単位で取得contacts:manage

イベント

メソッドパス機能必要権限
POST/external/v1/events注文やカート放棄など、連絡先のイベントを最大 100 件記録events:write

API Webhook

メソッドパス機能必要権限
GET/external/v1/webhooks組織の Webhook エンドポイントを取得webhooks:manage、所有者または管理者キー
POST/external/v1/webhooksWebhook エンドポイントを登録、または同じ URL のものを検索webhooks:manage、所有者または管理者キー
GET/external/v1/webhooks/deliveries失敗した配信を、直近の失敗から順に取得webhooks:manage、所有者または管理者キー
GET/external/v1/webhooks/{webhookId}Webhook エンドポイントを取得webhooks:manage、所有者または管理者キー
PUT/external/v1/webhooks/{webhookId}エンドポイントの URL またはイベント種別を変更webhooks:manage、所有者または管理者キー
DELETE/external/v1/webhooks/{webhookId}エンドポイントへの配信を停止webhooks:manage、所有者または管理者キー
POST/external/v1/webhooks/deliveries/{deliveryId}/replay失敗した配信を再びキューに追加webhooks:manage、所有者または管理者キー

API サブアカウント

メソッドパス機能必要権限
GET/external/v1/accounts組織のサブアカウントを取得accounts:manage、所有者または管理者キー
POST/external/v1/accounts独自の API キーを持つサブアカウントを作成、または externalId で検索accounts:manage、所有者または管理者キー
DELETE/external/v1/accounts/{accountId}サブアカウントを無効にし、キーを失効accounts:manage、所有者または管理者キー

API キー

メソッドパス機能必要権限
GET/external/v1/healthキーで API に到達できるか確認所有者または管理者ロールの任意のキー
GET/external/v1/infoキーが代表する組織を取得任意のキー
GET/external/v1/key呼び出し元キーの名前、ロール、スコープ、現在の機能を取得任意のキー
このページは役に立ちましたか?