API インターフェース
Oblic API を使うと、サーバーから組織としてメール、SMS、WhatsApp を送信して結果を確認し、自社システムでの連絡先の操作を記録できます。送信に使用するテンプレート、送信者 ID、連絡先リスト、Webhook、サブアカウントも管理できます。サーバーは API キーで呼び出します。
このバージョンの OpenAPI ドキュメントは external-v1.json です。すべてのルート、必要なスコープ、受け付ける本文をOpenAPI リファレンスでも確認できます。API v2 は API キーではなく OAuth アクセストークンを使用します。
ベース 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/messages | API で送信したメッセージを新しい順に取得 | 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/templates | HTML からメールテンプレートを作成 | 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/templates | DLT 登録済みのテンプレートを 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/templates | WhatsApp テンプレートを 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/webhooks | Webhook エンドポイントを登録、または同じ 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 | 呼び出し元キーの名前、ロール、スコープ、現在の機能を取得 | 任意のキー |