Robotomail — 为您的 AI Agent 配置真实邮箱

Robotomail 允许 AI Agent 以编程方式发送、接收并响应电子邮件。它是面向自主 Agent、助手和工作流的、以 API 为核心的电子邮件基础设施。

当您希望 Agent 实现以下功能时，可使用 Robotomail：

• 发送外发邮件、提醒、通知或跟进消息
• 从真实邮箱中读取入站邮件
• 通过 Webhook 或实时 SSE 事件响应入站邮件
• 使用标准邮件语义，在现有会话线程中进行回复
• 使用托管域名 robotomail.co 地址，或自定义域名

典型适用场景

1. Agent 支持邮箱

为您的 Agent 配置真实邮箱，使其能够对入站客服邮件进行分类、摘要、草拟回复或直接应答。

2. 外发跟进与提醒

让 Agent 从其专属邮箱发送提醒、轻量提示（nudges）、收据、预约确认或外发跟进邮件。

3. 实时邮件触发

通过 Webhook 或 SSE 订阅入站邮件事件，使 Agent 能够即时唤醒并响应。

快速上手

若用户首次使用 Robotomail，最快路径如下：

1. 在 https://robotomail.com 注册，或通过 POST /v1/signup 创建账户
2. 使用 GET /v1/mailboxes 查看已有邮箱，或使用 POST /v1/mailboxes 创建新邮箱
3. 使用 POST /v1/mailboxes/{id}/messages 发送一封测试邮件
4. 使用 GET /v1/mailboxes/{id}/messages?direction=INBOUND 读取入站邮件
5. 通过 Webhook 或 SSE 订阅入站事件

认证方式

所有请求均需在 Authorization 请求头中携带 API 密钥：

Authorization: Bearer 

基础 URL： https://api.robotomail.com

若用户尚未获取 API 密钥，可通过 https://robotomail.com 注册，或调用 POST /v1/signup 创建账户。

速查参考 — 我能做什么？

如需完整端点说明（含请求/响应 Schema），请参阅 references/api-reference.md。

Webhook 与 SSE 对比

当 Robotomail 需要将事件推送至您的公网 HTTPS 终端时，请使用 Webhook。

当 Agent 希望通过单个长连接维持实时事件流（例如运行本地监听器或 Agent 主循环）时，请使用 SSE。

若用户表述类似“流式接收入站邮件”、“监听新消息”或“实时收件箱事件”，请优先选用 SSE。

决策树 — 常见任务操作指南

“发送一封邮件”

1. 列出邮箱：GET /v1/mailboxes — 找到用于发信的邮箱
2. 发送邮件：POST /v1/mailboxes/{id}/messages，传入 to、subject、bodyText（可选 bodyHtml）
3. 如需回复已有邮件，请在请求体中包含 inReplyTo 字段，其值为原始邮件 messageId 头部的值

“检查我的收件箱” / “读取我的邮件”

1. 列出邮箱：GET /v1/mailboxes
2. 获取入站邮件：GET /v1/mailboxes/{id}/messages?direction=INBOUND
3. 读取某封特定邮件：GET /v1/mailboxes/{id}/messages/{msgId}

“回复一封邮件”

1. 先读取原始邮件，获取其 messageId 字段值
2. 发送回复：POST /v1/mailboxes/{id}/messages，设置 inReplyTo 为原始邮件的 messageId 值
3. 线程自动关联 — 回复将加入同一会话线程

“为新域名配置邮件服务”

1. 添加域名：POST /v1/domains，请求体为 {"domain": "example.com"}
2. 从响应中读取 dnsRecords 字段，并提示用户在其 DNS 提供商处完成相应配置
3. DNS 配置完成后，执行验证：POST /v1/domains/{id}/verify
4. 验证成功后，创建邮箱：POST /v1/mailboxes，请求体为 {"address": "agent", "domainId": ""}

“为入站邮件配置 Webhook”

1. 创建 Webhook：POST /v1/webhooks，传入 url 和 events: ["message.received"]
2. 保存响应中的 secret 字段值（仅返回一次）
3. 使用 X-Robotomail-Signature 请求头校验 Webhook 投递（基于 secret 对 payload 进行 HMAC-SHA256 签名）

签名验证代码详见 references/webhook-verification.md。

“实时监听入站邮件” / “使用 SSE”

1. 连接 GET /v1/events
2. 过滤或响应 message.received、message.delivered、message.bounced 和 message.complaint 事件
3. 当 Agent 需要持续流式事件而非公网 Webhook 投递时，使用 SSE

“发送带附件的邮件”

1. 上传文件：POST /v1/attachments（multipart/form-data，字段名为 file，单文件最大 25MB）
2. 记录响应中返回的附件 id
3. 发送邮件时，在请求体中指定 attachments: [""]

“读取入站邮件的附件” / “处理内联图片”

带附件的入站邮件在两个接口层面暴露附件信息，但其结构不同。请根据您的访问模式选择合适的方式 —— 不要假设 REST 接口响应中已包含可直接使用的下载 URL。

1. Webhook / SSE message.received 事件载荷 — data.attachments[] 中每个附件均提供开箱即用的 download_url 字段（R2 预签名 URL，自发布起 24 小时有效），以及 id、filename、content_type、size_bytes 和 content_id 字段。字段命名采用 snake_case。可直接发起 HTTP GET 下载，无需 Authorization 头：

   for att in event.data.attachments:
       bytes = HTTP_GET(att.download_url)
       save_to(att.filename, bytes)
   

2. REST 接口 GET /v1/mailboxes/{id}/messages 与 GET /v1/mailboxes/{id}/messages/{msgId} — attachments[] 仅包含元数据（id、filename、contentType、sizeBytes、contentId），不含 URL 字段。如需下载，请对每个附件 ID 调用 GET /v1/attachments/{id}，并在该响应中使用 url 字段。字段命名采用 camelCase。此方式也适用于刷新旧 Webhook/SSE 回放中已过期的 download_url。

内联图片：当附件的 content_id（Webhook/SSE 中为 snake_case）或 contentId（REST 中为 camelCase）非空时，该附件将在 body_html / bodyHtml 中以 形式被引用。在将 HTML 传递给渲染器或视觉模型前，需将每个 cid: 引用替换为实际可下载的 URL。来自 Webhook/SSE 载荷（其中 download_url 已附于附件对象）：

for att in event.data.attachments where att.content_id is not None:
    body_html = body_html.replace(f"cid:{att.content_id}", att.download_url)

来自 REST 接口读取的邮件，则需先为每个内联附件单独获取预签名 URL：

for att in message.attachments where att.contentId is not None:
    url = GET(f"/v1/attachments/{att.id}").url
    bodyHtml = bodyHtml.replace(f"cid:{att.contentId}", url)

附件截断限制：若单封邮件附件数超过 20 个，或任一附件大小超过 25 MB，则事件载荷中将包含 attachments_dropped: true 及 attachments_dropped_reason: "size" | "count" | "both"。邮件本身仍会投递，但超限附件不会被存储。如检测到该标志，请主动告知用户。

关键约束条件

• 日发送限额：免费版 100 封/天，付费版 500–2,000 封/天（按套餐不同而异），按邮箱计；UTC 时间每日零点重置
• 月发送限额：免费版 5,000 封/月，Developer 套餐 15,000 封/月，Growth 及 Scale 套餐无上限，均按邮箱计
• 速率限制：每邮箱 30 封/分钟，每账户 60 封/分钟；超出时返回 429
• 退信率（Bounce Rate）：7 日滚动窗口内必须低于 3%（最低统计基数为 50 封邮件）。超出将自动暂停该邮箱。
• 投诉率（Complaint Rate）：7 日滚动窗口内必须低于 0.05%（最低统计基数为 50 封邮件）。超出将自动暂停该邮箱。
• 附件大小限制：单文件最大 25MB
• 存储空间：免费版 1GB，Developer 套餐 10GB，Growth 套餐 25GB，Scale 套餐 100GB
• 免费版限制：仅支持 3 个 robotomail.co 域名下的邮箱
• 付费方案起价 $19/月（Developer）：支持 10+ 个邮箱及自定义域名

若发送请求返回 429，表示该邮箱已触及日/月限额或速率限制。请向用户说明情况，并建议其降低频率或升级至付费计划（如当前使用免费版）。

错误处理

所有错误均返回标准格式 {"error": "message"}，并附带标准 HTTP 状态码：

• 401 — 缺失或无效的 API 密钥
• 403 — 账户已被暂停，或作用域受限的密钥尝试访问受保护资源。暂停状态下响应中将包含 { "suspended": true, "reason": "bounce_rate_exceeded" }。请提示用户联系 support@robotomail.com。
• 404 — 资源未找到
• 429 — 触发了速率限制、发送频率限制或配额限制
• 413 — 附件过大

使用技巧

• 始终使用 bodyText 提供纯文本版本；仅在需要富文本格式时额外添加 bodyHtml。
• 使用会话线程接口（GET /v1/mailboxes/{id}/threads/{tid}）在回复前查看完整对话历史。
• 调用邮件列表接口时，使用 since 参数（ISO-8601 格式）仅获取最近的邮件。
• 退订列表（GET /v1/suppressions）包含所有发生退信或投诉的邮箱地址 —— 发送前请检查目标地址是否已在该列表中。