受信

ラベルとバケット

送信済みメールと受信メールを自動的にラベルへ振り分け、エージェントの会話が外に出ないバケットを用意します。

ラベル

ラベルはGmailのフォルダのように機能します。1通のメッセージに付けられるラベルは最大10個、1つのワークスペースで作成できるラベルは200個です。POST /labelsでラベルを作成し、GET /labelsでメッセージ数と未読数を含めて一覧表示し、GET /emails?label=Billingで特定のラベルのメールを読み取ります。ラベルはどこでも名前またはlbl_ IDで参照できます。

ラベルを付けて送信する

POST /emailsのボディ

{
  "from": "Orders <orders@example.com>",
  "to": [
    "customer@example.net"
  ],
  "subject": "Order 1042",
  "text": "Reply with a delivery window.",
  "labels": [
    "Agent/Orders"
  ]
}

存在しないラベル名は自動的に作成されます。顧客からの返信を含め、その会話の以降のすべてのメッセージは会話のラベルを引き継ぎます。

バケット

"skip_inbox": trueを指定してラベルを作成すると、バケットになります。振り分けルール、ラベル付きの会話への返信、またはPOST /emails/:id/labelsによってバケットのラベルが付いた受信メールはアーカイブされ、受信トレイには表示されずラベル内にのみ表示されます。送信済みメールが受信トレイに表示されることはありません。これにより、エージェントのタスクに関する会話は送受信の両方向で1か所にまとまります。

POST /labelsのボディ

{
  "name": "Agent/Orders",
  "skip_inbox": true,
  "rules": [
    {
      "inbox_id": "inb_…"
    }
  ],
  "apply_to_existing": true
}

振り分けルール

ルールは新着メールを自動的に振り分けます。ルールに設定したすべての条件に一致する必要があります。条件は、inbox_id（受信アドレス）、direction（inまたはout）、および大文字と小文字を区別しないfrom、to（ToとCc）、subjectの部分文字列です。ルール自体のskip_inboxは、そのルールに一致した受信メールだけをアーカイブします。ルールはPOST /labels/:id/rulesで追加します。apply_to_existingを指定すると、保持済みのメールも振り分けられます。

バケットを処理する

GET /emails?label=Agent%2FOrders&direction=in&unread=trueをポーリングし、GET /threads/:idで会話を読み、reply_to_email_idで返信してから、PATCH /emails/:id {"read": true}で処理済みにします。メッセージをラベルに出し入れするにはPOST /emails/:id/labels {"add": [...], "remove": [...]}を使います。MCPサーバーは同じ操作をcreate_label、create_label_rule、label_email、list_emailsとして公開しています。