Agent 邮箱
Agent 邮箱是一个可寻址的收件箱，由你的代码通过 API 管理。读取和过滤会话、回复消息或撰写新邮件，无需运行 IMAP 服务器或解析原始 MIME。
邮箱可以位于共享的 inbox.ai 域名上，也可以位于你自己启用了接收功能的发送域名上。地址在创建时即被占用，并始终属于你：本地部分保留给你的工作区，即使删除邮箱后也不会分配给其他人。
地址
每个邮箱有一个地址，{local_part}@inbox.ai。获取地址有两种方式：
- 自动生成：省略本地部分，我们会为你生成一个无冲突的地址（a7f3k2@inbox.ai）。始终可用。
- 自定义：指定一个本地部分（support@inbox.ai）。自定义标识全局唯一，先到先得，属于付费计划配额；免费工作区只能使用自动生成的地址。
地址一旦创建即不可更改。如需更改，请创建新邮箱并删除旧邮箱。旧的本地部分会保留 30 天（恢复窗口期），之后才能被重新申请，且始终保留给你的工作区。
会话与消息
收到和发出的邮件按会话分组，每个对话一个会话。会话包含参与者地址、未读计数、最新消息的方向（inbound 或 outbound）以及最近活动的时间戳。回复会归入所回答的会话；新撰写的邮件会开启一个新会话。
每条消息公开请求头、去除引用历史后提取的纯文本以及附件。原始正文保留 30 天；原始 MIME 仅对收到的消息可用。消息 ID 按方向添加前缀：rem_ 表示收到的消息，em_ 表示你发出的消息。
决定哪些邮件可以进入
收件箱前有两道控制，均根据信封发件人而非可伪造的 From: 请求头进行检查：
- 接收策略：邮箱范围的默认设置。
- open 接受所有通过身份验证的邮件。
- replies_only 仅接受延续邮箱中已有会话的邮件。
- allowlist 仅接受你的规则允许的发件人，以及对已有会话的回复。
- drop 丢弃所有邮件，无一例外。
- 接收规则：按发件人设置的允许或阻止条目，可匹配完整地址或域名（域名规则同时匹配其子域名）。阻止始终优先于允许。
被规则阻止或未通过 DMARC 的邮件仍会存储在邮箱中并可读取：它被归档到收件箱之外而非丢弃，也不会触发 webhook。唯一的例外是设置为 drop 的邮箱，它会在入口直接丢弃所有邮件而非归档。
发送
邮箱通过 API 以两种方式发送邮件：回复一条消息（出站消息归入该会话）或撰写一条新消息（开启一个新会话）。在仪表板中，打开一条消息并选择转发，即可在原始内容的 30 天窗口内将其正文和附件发送给新收件人。邮件从邮箱自身的地址发出，使用你在邮箱上配置的显示名称和默认 Reply-To。投递状态会回写到已发送消息上，以便你查看回复是否已投递或被退回。
事件
订阅 email_mailbox.* webhook 系列以驱动 agent 而无需轮询：email_mailbox.message_received（入站邮件到达收件箱）、email_mailbox.thread_created 以及你发送消息的投递状态事件。仅收件箱邮件会触发事件；垃圾邮件和被规则阻止的邮件会静默存储，因此被淹没的邮箱不会放大成 webhook 洪流。收件箱邮件还会触发标准的 email.received 事件，使现有的入站集成继续正常工作。
如果需要无 webhook 基础设施的实时视图，请连接 GET /v1/email/mailboxes/{mailbox_id}/events。SSE 流会发送邮箱活动的事件类型、会话 ID 和消息 ID，包括垃圾邮件和被阻止的到达。使用这些 ID 获取完整消息。流在断开连接后不会重放事件。请使用 webhook 实现持久投递，使用列表端点在中断后补齐数据。
保留与清除
邮箱的保留层级控制你可以读取消息请求头、提取文本和邮箱附件的时长，从发送或接收时起算。默认为 30 天。如果你的计划包含 90 天或 365 天保留，请在创建或更新时设置 retention_tier。计划中未包含的层级会被拒绝并返回 E17048。
| 内容或操作 | 保留窗口 |
|---|---|
| 消息请求头、提取文本和邮箱附件 | 所选层级：30、90 或 365 天 |
| 原始 HTML 和纯文本正文 | 所有层级均为 30 天 |
| 收到消息的原始 MIME | 所有层级均为 30 天；已发送消息无存储的原始 MIME |
| 在仪表板中转发消息 | 需要原始内容在其 30 天窗口内 |
| 读取提取文本或以新内容回复 | 在消息保留期间可用 |
例如，在第 40 天，90 天邮箱中的消息仍有可读取、可搜索的提取文本和保留的附件。你可以用新内容回复，但无法打开原始正文、下载其原始 MIME 或转发它。提取文本限制为每条消息 64 KiB，可能会省略原始内容的部分。在启用扩展附件保留之前存储的附件保持其约 31 天的原始过期时间；更改层级不会迁移这些附件。提升层级无法恢复已被删除的内容。
消息在保留期到期后不再由 API 返回。后台每小时执行一次清理；物理清除可能滞后于 API 到期时间。
降低层级立即对读取生效：任何超过新截止时间的内容会立即停止返回。你有十分钟可以撤销，且十分钟是唯一保证：在该窗口内重新提升层级，数据不会丢失。超过该窗口后，滞留消息变为可删除状态，下一次每小时清理会处理它们，因此后续提升层级只能恢复清理尚未触及的内容。
提升到你的计划包含的层级随时可接受，即使先前的更改仍在应用中也是如此。后台更新独立于十分钟撤销窗口。第二次降低层级需在第一次更改已更新所有存储消息后才会被接受。更新每十分钟启动一次，对于大型邮箱可能需要数小时。在更新完成之前，API 会返回 E17050；请稍后重试。
如果你的计划设置了有限的邮箱存储配额，则所有存活或可恢复的邮箱共享一个配额。每个邮箱将其占用量报告为 size_bytes。没有有限配额的计划具有无限邮箱存储。当所有邮箱的总量达到有限配额时，发送会被拒绝并返回 E17049，直到你在任一邮箱中释放空间。
删除邮箱后会立即停止接收邮件。邮箱可在 30 天内恢复，同时正常的消息保留期继续生效。30 天后，永久清除会移除邮箱及其剩余消息。一旦永久清除开始，即使清理仍在进行中，恢复也会被拒绝。地址始终保留给你的工作区。