入站邮件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轮询才发现新工单。邮件Webhook API在消息到达的那一刻就进行传递，让您的代理能够立即开始处理。

AgentSend中入站邮件的工作方式

AgentSend的邮件接收API围绕每个邮箱的Webhook构建。当您创建邮箱时，可以配置一个Webhook URL来接收该特定邮箱的每封入站消息。每个邮箱都是隔离的——没有共享的路由层需要您检查收件人地址并分派到正确的处理程序。

每次Webhook传递都在X-AgentSend-Signature标头中包含HMAC签名。您的应用程序使用邮箱的Webhook密钥验证此签名，以确认载荷由AgentSend发送且在传输过程中未被篡改。如果您的端点暂时不可用，AgentSend将以指数退避方式重试传递，最长可达24小时。

设置入站邮件

开始使用AgentSend的邮箱API需要两个步骤：创建带有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载荷。以下是使用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与传统方法的对比

有多种方法可以程序化接收邮件。以下是最常见的方法在AI代理用例中的比较。

关键区别在于隔离。Mailgun和SendGrid都在域级别运行：您将域的MX记录指向它们的服务器，该域的所有传入邮件都到达单个Webhook端点。您需要负责检查每个载荷中的收件人地址并将其路由到正确的代理。使用AgentSend，每个邮箱都有自己的Webhook、自己的签名密钥和自己的会话历史。没有需要构建或维护的路由逻辑。

邮箱API：程序化创建邮箱

邮箱API最强大的方面之一是能够即时创建邮箱。当您的平台引入新客户、配置新AI代理或启动新工作流时，您可以通过单个API调用创建专用邮箱。每个邮箱自动获得自己的邮件地址——无需DNS配置、无需手动设置、无需等待传播。

这对于多代理架构特别有用。客户支持系统可以为账单问题、技术支持和账户管理创建单独的邮箱。每个邮箱路由到一个专门的代理，拥有自己的Webhook端点和自己的对话历史。从一个代理扩展到五十个是一个API调用循环，而不是DNS迁移项目。

入站邮件API的用例

入站邮件API开启了一系列使用传统邮件基础设施难以或不可能构建的自主代理工作流。

• 客户支持代理 — 通过邮件接收支持工单，分类意图，自动解决常见问题，并将复杂问题连同完整的会话上下文升级给人工代理。
• 研究代理 — 订阅新闻通讯，接收报告，处理传入的信息流。代理读取每封邮件，提取相关数据，并在无需人工干预的情况下更新知识库。
• 日程安排代理 — 通过邮件接收会议请求和可用性回复。代理解析内容、检查日历并发送确认回复——所有这些都通过其自己的专用邮件地址进行。
• 带有回复处理的外发优先代理 — 发送冷开发、跟进序列或通知的代理可以通过同一邮箱接收和处理回复，保持完整的对话上下文。

在每种情况下，入站邮件API都消除了基础设施负担。您的代理代码专注于理解和回复消息，而不是维护IMAP连接、解析MIME或将邮件路由到正确的处理程序。