API と MCP による接続済みアカウント管理

接続済みアカウントを使用すると、ウェブメールのメールボックスから外部メールボックス、Gmail、Yahoo、iCloud、Outlook.com/Microsoft 365、または任意の IMAP サーバーにあるメールを読んだり送信したりできます。メッセージ API と MCP ツールは、同じ機能をプログラムから利用できるようにします。接続済みアカウントの一覧表示、追加、テスト、編集、削除のほか、通常のメッセージ呼び出し（一覧、閲覧、送信、フラグ、移動、削除、フォルダー）を、トークン自身のメールボックスではなく接続済みアカウントに向けることができます。

簡単に言うと、mailbox_id はエージェントが代理で操作できる TrekMail メールボックスを選び、external_account_id はその中の Gmail または別の接続済みメールボックスを選びます。両者を入れ替えることはできません。

プラン、制限、カタログの規模

接続済みアカウントの管理には 7 つのメッセージツールがあります。スコープが限定されたトークンには、製品カタログ全体ではなく、実際に使用できるツールだけが表示されます。

始める前に

• 接続済みアカウントはウェブメール機能であり、メッセージトークンのインターフェース (/api/v1/messages/...) を使用します。ダッシュボード API トークンではなく、以下のスコープを持つメッセージトークンで認証します。
• プランの制限はメールボックスごとに適用されます：Starter 5, Pro 10, Agency 30。Nano プランには接続済みアカウントが含まれません。
• 各 endpoint の範囲はトークン自身のメールボックスに限定されます。トークンが表示、管理できるのは自身の接続済みアカウントだけであり、別のメールボックスのアカウントにはアクセスできません。
• 認証情報と OAuth トークンは、応答では常にマスクされます。パスワードまたはアプリパスワードを書き込むことはできますが、後から読み戻すことはできません。
• Outlook.com および Microsoft 365 アカウントは、ウェブメール UI の Microsoft サインイン (OAuth) で接続します。接続後は API で管理、使用できますが、対話型の Microsoft 同意手順を API が実行することはありません。

スコープ

メッセージ呼び出しで接続済みアカウントを指定するには、その呼び出しで通常必要となるものと同じスコープが必要です（たとえばメッセージの一覧には messages:read、送信には messages:send が必要です）。

接続済みアカウントの管理

ベースパス：/api/v1/messages/external-accounts

アカウントを追加する

POST /api/v1/messages/external-accounts
Scope: messages:write

リクエスト本文：

最初に POST /external-accounts/detect を呼び出すと、provider とサーバー設定が自動入力されます。保存処理は保存前に実際の IMAP + SMTP テストを実行します。422 とエラーカテゴリー (auth、tls、network、transient_throttle) が返された場合、認証情報が機能せず、何も保存されなかったことを意味します。

メッセージ呼び出しで接続済みアカウントを指定する

メールボックスを操作するすべてのメッセージ endpoint は、任意の external_account_id を受け取ります。これを指定するとトークン自身のメールボックスではなく、その接続済みアカウントに対して呼び出しを実行します。メールボックス自体を使う場合は省略します。これは一覧、閲覧、送信、返信、フラグ、移動、削除、フォルダー一覧に適用されます。

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

external_account_id だけを指定した送信では、そのアカウント自身の SMTP サーバー（プロバイダーの SPF/DKIM）が使われます。代わりにソースに紐づいた identity_id を指定すると、その差出人 ID のドメインまたは保存済みプロファイルのルートを使用しながら、送信済みコピーは接続済み受信トレイに保存されます。アカウントは正常 (status: active) である必要があります。切断されたアカウントでは、再接続を求めるエラーが返されます。API と MCP による差出人アドレスを参照してください。

MCP ツール

同じ機能は MCP を介して AI エージェントでも利用できます（プライベート stdio サーバーとパブリック MCP サーバーの両方）：

メッセージツール list_messages、read_message、send_message、list_folders、update_message_flags、move_message、delete_message、prepare_reply、prepare_reply_all、prepare_forward は、任意の external_account_id 引数を受け取ります。送信、下書き、予約送信では、ソースに紐づいた identity_id も使用でき、この値は list_identities が返します。

管理ツールは、ユーザーが指定した認証情報を使って任意のメールサーバーへの外向き接続を開くため、接続済みアカウント機能のほかの部分と同じ安全対策を採用しています。具体的には、ホストの許可リスト、プライベート範囲のブロック、ポートの許可リスト、ホストごとの接続上限です。