sendblue-api

Sendblue API

概要

Sendblue は、プロビジョニング済みの電話番号から iMessage（青い吹き出し）、SMS、RCS を送信する REST API です。すべて HTTPS 経由のプレーンな JSON で処理され、SDK は不要です。この API は、1 対 1 およびグループへの送信、iMessage のエフェクト、リアクション、入力中インジケーター、ステータスコールバック、受信 Webhook に対応しています。

このスキルを使用する場面

• 長時間稼働するサービスの一部として Sendblue メッセージを送信するアプリケーションコード（サーバー、ワーカー、関数）を書く場合に使用します。
• Webhook 経由で受信メッセージを受け取る場合に使用します。
• CLI では公開されていない機能（送信スタイル、リアクション、グループメッセージ、入力中インジケーター、ステータスコールバック、メディアのアップロード、基本的な CRUD を超える連絡先 API）が必要な場合に使用します。
• シェル環境から送信する場合（単発スクリプト、cron ジョブ、エージェントフック、「X が起きたら通知して」ワークフロー）は、代わりに [[sendblue-cli]] を使用してください。

仕組み

ステップ 1：認証

https://api.sendblue.com

すべてのリクエストに 2 つのヘッダーが必要です。

sb-api-key-id: <YOUR_API_KEY_ID>
sb-api-secret-key: <YOUR_API_SECRET>
Content-Type: application/json

両方の値はサーバー側で保持してください。ブラウザーやモバイルクライアントに含めてはいけません。

ステップ 2：メッセージを送信する

curl -X POST https://api.sendblue.com/api/send-message \
  -H "sb-api-key-id: $KEY_ID" \
  -H "sb-api-secret-key: $SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+15551234567",
    "from_number": "+1YOUR_SENDBLUE_NUMBER",
    "content": "Hello from the API!"
  }'

電話番号は E.164 形式である必要があります。from_number には所有している回線を指定してください。GET /api/lines で自分の回線を一覧表示できます。

ステップ 3：配信状況を追跡する

同期レスポンスには message_handle（Apple GUID。リアクションや返信に必要なため、保存してください）と、REGISTERED、PENDING、QUEUED、ACCEPTED、SENT、DELIVERED、DECLINED、ERROR のいずれかの status が含まれます。メッセージが届いたことを示すのは DELIVERED のみです。/api/status をポーリングする代わりに、status_callback を使用してください。

ステップ 4：受信する

ダッシュボードまたは POST /api/account/webhooks から Webhook URL を設定します。Sendblue は JSON をエンドポイントに POST します。速やかに 2xx を返してください。2xx 以外の場合は再試行が発生し、重複して配信されることがあります。イベントタイプ：receive、outbound、typing_indicator、call_log、line_blocked、line_assigned、contact_created。

主なエンドポイント

Method	Path	Purpose
POST	/api/send-message	1 対 1 のメッセージを送信（テキストやメディア）
POST	/api/send-group-message	複数の宛先に送信
POST	/api/create-group	名前付きグループスレッドを作成
POST	/api/send-reaction	Tapback を送信（love/like/dislike/laugh/emphasize/question）
POST	/api/send-typing-indicator	受信者のスレッドに「入力中…」を表示
POST	/api/mark-read	開封確認を送信
POST	/api/upload-file / /api/upload-media-object	メディアをアップロード（直接、または URL から）
GET	/api/status	メッセージの配信状況をポーリング
GET	/api/evaluate-service	電話番号が iMessage に対応しているか確認
GET	/api/v2/messages / /api/v2/messages/:id	メッセージ履歴を読み取る
GET / POST / PUT / DELETE	/api/v2/contacts[...]	連絡先を管理
GET	/api/lines	自分の Sendblue 電話番号を一覧表示
POST	/api/account/webhooks	Webhook サブスクリプションの CRUD

例

例 1：メディア、エフェクト、ステータスコールバックを付けて送信する

POST /api/send-message
{
  "number": "+15551234567",
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Optional text",
  "media_url": "https://example.com/img.jpg",
  "send_style": "celebration",
  "status_callback": "https://yourapp.com/sendblue/status"
}

content または media_url のどちらかが必須です。send_style は iMessage 専用です。有効な値：celebration、shooting_star、fireworks、lasers、love、confetti、balloons、spotlight、echo、invisible、gentle、loud、slam。SMS では無視されます。テキストは最大 18,996 文字、メディアは iMessage で最大 100 MB、SMS で最大 5 MB です。

例 2：グループメッセージ

POST /api/send-group-message
{
  "numbers": ["+15551234567", "+15557654321"],
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "content": "Hey team"
}

レスポンスには group_id が含まれます。毎回新しいグループを作成するのではなく、同じスレッドに続けて送信できるよう保存してください。

例 3：メッセージにリアクションする

POST /api/send-reaction
{
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "message_handle": "<message_handle from prior send>",
  "reaction": "love"
}

リアクションは iMessage でのみ機能し、元のメッセージの message_handle が必要です。有効な値：love、like、dislike、laugh、emphasize、question。

例 4：受信 Webhook ペイロード（receive）

{
  "accountEmail": "[email protected]",
  "content": "Reply text",
  "media_url": "https://...",
  "is_outbound": false,
  "number": "+15551234567",
  "from_number": "+1YOUR_SENDBLUE_NUMBER",
  "service": "iMessage",
  "group_id": "...",
  "date_sent": "2024-01-01T12:00:00Z"
}

ステータスコールバックのペイロード（outbound）は send-message のレスポンスと同様で、メッセージの状態が SENT → DELIVERED（または ERROR）へ進むと更新されます。

ベストプラクティス

• ✅ 送信のたびに message_handle を保存してください。 リアクション、返信、ステータスコールバックとの照合に必要です。
• ✅ ポーリングより status_callback を使用してください。 GET /api/status より低コストで、正確です。
• ✅ ウェブフックからは速やかに 2xx を返し、その後非同期で処理してください。 2xx 以外を返すと、配信が重複します。
• ✅ 受信者に iMessage 専用機能を使用する前に、/api/evaluate-service でサービスを確認してください。
• ✅ 受信したメディアはすぐに別の場所へホストしてください — メディアの URL は約 30 日で有効期限が切れます。
• ❌ sb-api-key-id / sb-api-secret-key をクライアントに渡さないでください。 これらはサーバー側の認証情報です。
• ❌ /api/send-message の 200 を配信済みと見なさないでください。 これは「受け付けた」という意味にすぎません。

制限事項

• 同期送信のレスポンスで報告されるのは受け付けたことのみで、配信状況ではありません。最終状態は status_callback または GET /api/status で通知されます。
• SMS（緑色の吹き出しの受信者）では、send_style は何もせずに処理を終了します。
• 受信メディアの URL は約 30 日で有効期限が切れます。
• 回線ごとにレート制限があります。1 つの番号から多数のメッセージを連続して送信すると、Apple のスパム判定に引っかかる可能性があります。送信間隔を空けるか、複数の回線に分けてください。
• リアクションとエフェクトは iMessage 専用です。

セキュリティと安全性に関する注意事項

• sb-api-key-id と sb-api-secret-key はサーバー側で管理してください。ブラウザー、モバイル端末、CI のログで安全に扱えるものではありません。
• ウェブフックのエンドポイントには HTTPS を使用し、冪等性を確保してください。同じ message_handle が複数回届く可能性があります。
• メッセージ本文に含まれる機密データは、受信者の端末のロック画面プレビューに表示されます。シークレット、トークン、個人を特定できる情報全体を含めず、認証が必要なダッシュボードへのリンクや短縮したペイロードを使用してください。
• どちらかの値が漏えいした場合は、Sendblue ダッシュボードで API キーをローテーションしてください。ローテーションすると古いキーのペアは無効になります。

よくある落とし穴

• E.164 形式のみ対応しています。 5551234567 や (555) 123-4567 は失敗します。必ず +15551234567 のように指定してください。
• from_number には自分の回線のいずれかを指定する必要があります。 偽装した番号やプロビジョニングされていない番号を指定するとエラーになります。
• SMS では send_style は何もせずに処理を終了します。 受信者が緑色の吹き出しの場合、エフェクトは表示されません。重要な場合は、まず /api/evaluate-service でサービスを確認してください。
• message_handle を保存してください。 リアクション、返信、ステータスコールバックと自分の記録との照合に必要です。
• メディアの URL は約 30 日で有効期限が切れます。 受信ウェブフックのメディアを長期間保持する必要がある場合は、受信時にダウンロードして別の場所へホストしてください。
• ステータスは非同期です。 /api/send-message の 200 は受け付けたことを意味し、配信済みという意味ではありません。同期レスポンスを待つのではなく、status_callback を使用してください。
• 2xx 以外を返すとウェブフックが再試行されます。 イベントを無視すると判断した場合も 200 を返してください。そうしないと、重複配信が発生します。
• レート制限は回線ごとに適用されます。 1 つの番号から多数のメッセージを連続して送信すると、Apple のスパム判定に引っかかります。送信間隔を空けるか、複数の回線に分けてください。

関連スキル

• @sendblue-cli — シェルコンテキストからの送信（スクリプト、cron、エージェントフック）向けのシェルラッパーです。HTTP の完全な統合が不要な場合に使用してください。
• @sendblue-notify — API または CLI の上に構築する、「X が完了したらテキストで知らせる」通知のパターンと文面のルールです。

リンク

• 全リファレンス：https://docs.sendblue.com/
• Sendblue：https://sendblue.com
• ここでは説明していない便利な機能：カルーセル（/api/send-carousel）、FaceTime／連絡先カードの共有、高度なウェブフックフィルタリング、基本的な CRUD を超える連絡先 API — ドキュメントサイトをご覧ください。