受信メールAPI：AIエージェントのためにプログラムでメールを受信する方法

受信メールAPIは、アプリケーションがプログラムでメールを受信することを可能にします。メールボックスをポーリングしたり受信トレイをスキャンしたりする代わりに、受信メッセージはWebhookを介してリアルタイムでコードに配信されます。メールを読み、理解し、返信する必要があるAIエージェントにとって、受信メールAPIは自律的なメールワークフローを可能にする基本的な構成要素です。

このガイドでは、受信メールAPIの仕組み、AgentSendでの設定方法、そしてメールボックスごとのWebhookモデルがIMAPポーリングやドメインレベルの受信解析などの従来のアプローチよりもAIエージェントに適している理由を説明します。

受信メールAPIとは？

受信メールAPIは、あなたに代わって受信メールを受け取り、構造化データとしてアプリケーションに配信するサービスです。典型的なフローは次のように機能します：MXレコードが受信メールをAPIプロバイダーのサーバーに送り、プロバイダーが生のメールを構造化ペイロード（送信者、件名、本文、添付ファイル、ヘッダー）に解析し、設定したWebhook URLにそのペイロードを配信します。

従来のメール受信に対する主な利点は、アプリケーションがメールサーバーを管理する必要がないことです。維持するIMAP接続も、調整するPOP3ポーリング間隔も、実装する生のMIME解析もありません。HTTP POST経由でクリーンなJSONペイロードを受信し、処理して、200ステータスコードで応答します。それが統合のすべてです。

AIエージェントにとってこれが重要なのは、エージェントが受信メールにリアルタイムで反応する必要があるからです。カスタマーサポートエージェントは、新しいチケットを発見するために次のIMAPポーリングまで5分間待つことができません。メールWebhook APIはメッセージが到着した瞬間に配信し、エージェントが即座に処理を開始できるようにします。

AgentSendでの受信メールの仕組み

AgentSendのメール受信APIは、メールボックスごとのWebhookを中心に構築されています。メールボックスを作成すると、その特定のメールボックスへのすべての受信メッセージを受け取るWebhook URLを設定できます。各メールボックスは分離されており、受信者のアドレスを検査して正しいハンドラーにディスパッチする必要がある共有ルーティング層はありません。

すべてのWebhook配信には、X-AgentSend-SignatureヘッダーにHMAC署名が含まれています。アプリケーションは、メールボックスのWebhookシークレットを使用してこの署名を検証し、ペイロードがAgentSendによって送信され、転送中に改ざんされていないことを確認します。エンドポイントが一時的に利用できない場合、AgentSendは最大24時間、指数バックオフで配信を再試行します。

受信メールの設定

AgentSendのメールボックスAPIを使い始めるには2つのステップが必要です：Webhook URLを指定してメールボックスを作成し、受信ペイロードを処理します。

ステップ1：Webhook付きメールボックスの作成

cURLの使用：

curl -X POST https://api.agentsend.io/v1/inboxes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-agent",
    "webhook_url": "https://yourapp.com/webhooks/inbound-email",
    "webhook_secret": "whsec_your_secret_here"
  }'

Pythonの使用：

import requests

resp = requests.post(
    "https://api.agentsend.io/v1/inboxes",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "support-agent",
        "webhook_url": "https://yourapp.com/webhooks/inbound-email",
        "webhook_secret": "whsec_your_secret_here",
    },
)
inbox = resp.json()
print(inbox["email"])  # support-agent@yourteam.agentsend.io

ステップ2：Webhookペイロードの処理

メールが到着すると、AgentSendはWebhook URLにJSONペイロードをPOSTします。以下はFlaskを使用した最小限のPythonハンドラーです：

import hmac, hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"

@app.route("/webhooks/inbound-email", methods=["POST"])
def handle_inbound():
    # Verify HMAC signature
    signature = request.headers.get("X-AgentSend-Signature")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({"error": "invalid signature"}), 401

    payload = request.json
    sender = payload["from"]
    subject = payload["subject"]
    body = payload["body_text"]
    thread_id = payload["thread_id"]

    # Pass to your AI agent for processing
    process_with_agent(sender, subject, body, thread_id)

    return jsonify({"status": "ok"}), 200

受信メールAPI vs 従来のアプローチ

プログラムでメールを受信する方法はいくつかあります。AIエージェントのユースケースにおいて、最も一般的なアプローチがどのように比較されるかを示します。

決定的な違いは分離です。MailgunとSendGridはどちらもドメインレベルで動作します：ドメインのMXレコードをそれらのサーバーに向け、そのドメインへのすべての受信メールが単一のWebhookエンドポイントに届きます。各ペイロードの受信者アドレスを検査し、正しいエージェントにルーティングする責任はあなたにあります。AgentSendでは、各メールボックスに独自のWebhook、独自の署名シークレット、独自のスレッド履歴があります。構築や保守するルーティングロジックはありません。

メールボックスAPI：プログラムによるメールボックスの作成

メールボックスAPIの最も強力な側面の一つは、メールボックスをオンザフライで作成できることです。プラットフォームが新しい顧客をオンボードしたり、新しいAIエージェントをプロビジョニングしたり、新しいワークフローを立ち上げたりするとき、単一のAPIコールで専用のメールボックスを作成できます。各メールボックスは自動的に独自のメールアドレスを取得します。DNS設定も、手動セットアップも、伝搬を待つ必要もありません。

これはマルチエージェントアーキテクチャに特に有用です。カスタマーサポートシステムは、請求に関する質問、技術サポート、アカウント管理のために別々のメールボックスを作成できます。各メールボックスは独自のWebhookエンドポイントと独自の会話履歴を持つ専門エージェントにルーティングされます。1つのエージェントから50にスケールアップするのはAPIコールのループであり、DNS移行プロジェクトではありません。

受信メールAPIのユースケース

受信メールAPIは、従来のメールインフラストラクチャでは構築が困難または不可能な、さまざまな自律エージェントワークフローを実現します。

• カスタマーサポートエージェント — メールでサポートチケットを受信し、意図を分類し、一般的な質問を自動的に解決し、完全なスレッドコンテキスト付きで複雑な問題を人間のエージェントにエスカレーションします。
• リサーチエージェント — ニュースレターを購読し、レポートを受信し、受信情報フィードを処理します。エージェントは各メールを読み、関連データを抽出し、人間の介入なしにナレッジベースを更新します。
• スケジューリングエージェント — メールで会議リクエストと空き状況の返信を受信します。エージェントはコンテンツを解析し、カレンダーを確認し、確認の返信を送信します。すべて独自の専用メールアドレスを通じて行います。
• 返信処理を伴うアウトバウンドファーストエージェント — コールドアウトリーチ、フォローアップシーケンス、通知を送信するエージェントは、同じメールボックスを通じて返信を受信・処理し、完全な会話コンテキストを維持できます。

いずれの場合も、受信メールAPIがインフラストラクチャの負担を排除します。エージェントのコードは、IMAP接続の維持、MIMEの解析、メールの正しいハンドラーへのルーティングではなく、メッセージの理解と返信に集中します。