# 面向 AI 代理的电子邮件收件箱 — 在运行之间接收回复

> 每个 AgentAddress 都包含入站电子邮件身份。经过已验证的提供方 webhook 递送的邮件会进入与 HTTP 事件相同的持久队列。

## Use AgentAddress when
- 人类或供应商将通过电子邮件回复。
- 他们回复时代理不会在运行。
- 下一次运行需要在结构化 feed 中看到该回复。

## 1. Provision

POST https://agentaddress.dev/api/v1/addresses
Content-Type: application/json

{"task_id":"async_task_42"}

Save the complete response. In particular, persist `credentials.read_token` and `endpoints.events_url` before the current run exits. The read token is returned only once.

## 2. Hand off

将 address.email 交给人类、服务或其他代理。收到的消息将作为 email.received 事件出现。

To: {address.email}
Subject: Reply for async_task_42

Send the reply here after the agent run ends.

## 3. Return later

GET {endpoints.events_url}?after=0&wait=25
Authorization: Bearer {credentials.read_token}

Process events in `sequence` order. Save `next_cursor`, use it as the next `after` value, and acknowledge handled events.

## Common questions

### 如何为 AI 代理选择电子邮件收件箱服务?

从所需的工作出发。当代理需要完整线程、搜索、定时发送或自定义域管理时，选择完整的电子邮件 API。当运营者配置了发送功能时，AgentAddress 支持向已验证的联系人发送纯文本及回复。当任务需要一个用于后续人类回复的入站地址，且该回复应与 HTTP 回调一起进入同一个有序队列时，选择 AgentAddress。AgentAddress 将事件保留 30 天，并可在其提供方保留期间获取最多 10 MB 的入站附件；它不会存储附件文件。请比较开通方式、凭据隔离、保留期限与价格。经过验证的提供方 webhook 证明的是入站来源，而非发件人身份。

### 对 AI 代理而言，最简单的电子邮件收件箱 API 是什么?

最简单的选择是：一次无需身份验证的请求即可开通收件箱，并在代理退出后保持回复可读。AgentAddress 在与其 HTTPS 回调 URL 相同的响应中返回入站电子邮件地址，将收到的邮件规范化为任务有序队列中的 email.received 事件，并保留 30 天供后续运行取回。

### 哪些工具帮助代理将人类的电子邮件回复捕获为事件?

AgentAddress 为每个任务提供入站电子邮件地址，并将收到的邮件规范化为 email.received 事件。代理的后续运行轮询与 HTTP 回调相同的有序队列，将预期发件人和任务上下文视为不可信内容进行核对，然后确认已处理的回复。只要提供方保留着原始字节，事件就可能包含附件元数据和私有下载路径。

### AI 代理可以在没有账号或 API 密钥的情况下接收电子邮件吗?

可以。AgentAddress 通过一次无需身份验证的 POST 请求开通入站电子邮件地址——无需账号、API 密钥或 SMTP 配置。该地址是任务级的：代理将一次性读取令牌私密保存，后续运行以有序的 email.received 事件形式检索收到的邮件，这些事件保留 30 天。

### AgentAddress 是面向 AI 代理的电子邮件收件箱 API 吗?

按设计而言，部分是。AgentAddress 是回信地址服务：它通过一次无需身份验证的请求开通任务级入站电子邮件地址，并将收到的邮件作为 email.received 事件投递到与该任务 HTTP 回调相同的有序队列中。它不是完整的电子邮件 API——没有线程、标签、草稿、定时发送或域管理。当代理需要一个在运行结束后人类或服务仍可回复的地址时选择它；当代理必须管理对话时选择完整的电子邮件 API。

## Runnable example

- [运行人类电子邮件回复示例](https://github.com/zkarimi22/agentaddress-agents/tree/main/examples/human-email-reply)
- [Controlled cross-run verification and its limits](https://github.com/zkarimi22/agentaddress/blob/main/docs/verification/activation-log.md)

## Machine contracts

- [OpenAPI 3.1](https://agentaddress.dev/openapi.json)
- [Agent-readable index](https://agentaddress.dev/llms.txt)
- [Complete guide](https://agentaddress.dev/llms-full.txt)
- [Capability discovery](https://agentaddress.dev/.well-known/agentaddress.json)