收件箱

每个智能体都有自己的收件箱和唯一的邮件地址。收件箱是 AgentSend 中的基本单元。

概述

收件箱是单个智能体的专用邮件地址。您的智能体发送或接收的每封邮件都通过收件箱流转。您可以创建任意数量的收件箱 — 每个智能体一个、每个客户一个、每个工作流一个 — 没有限制。

默认情况下，收件箱在 @agentsend.io 域名上分配。如果您希望智能体从您自己的域名发送（例如 agent@yourcompany.com），请参阅自定义域名。

ℹ

收件箱之间相互隔离。智能体只能通过自己的收件箱发送和接收邮件 — 无法访问其他收件箱的消息。

创建收件箱

POST /inboxes

通过发送 POST 请求创建新的收件箱。两个 body 字段都是可选的 — 如果省略 displayName，收件箱将不带显示名称。如果省略 domainId，地址将在 @agentsend.io 上分配。

javascript

const res = await fetch("https://api.agentsend.io/inboxes", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    displayName: "Support Agent",   // optional
    domainId: "dom_abc123",         // optional — omit for @agentsend.io
  }),
});

const inbox = await res.json();
console.log(inbox.address); // e.g. a1b2c3@agentsend.io
console.log(inbox.id);      // e.g. inb_7x9kQm2Np...

响应包含完整的收件箱对象，包括可以立即开始使用的自动生成的 address。

收件箱属性

每个收件箱对象都有以下字段：

属性	类型	说明
`id`	string (uuid)	收件箱的唯一标识符。在所有 API 调用中使用。
`address`	string (email)	分配给此收件箱的完整邮件地址，例如 `a1b2c3@agentsend.io`。
`displayName`	string \| null	收件箱的可读标签。显示为发出邮件头中的发件人名称。
`domainId`	string \| null	与此收件箱关联的自定义域名 ID。默认 `@agentsend.io` 地址为 `null`。
`status`	string	当前收件箱状态：`active`、`suspended` 或 `deleted`。只有 `active` 状态的收件箱可以发送和接收。
`dailySendLimit`	number	此收件箱在 24 小时内可发送的最大邮件数。
`sendsToday`	number	当前 24 小时内已发送的邮件数。每日 UTC 午夜重置。
`totalSent`	number	自创建以来从此收件箱发送的所有邮件的累计计数。
`bounceCount`	number	此收件箱记录的硬退信数。高退信率可能触发暂停。
`complaintCount`	number	此收件箱记录的垃圾邮件投诉数。
`createdAt`	string (ISO 8601)	收件箱创建时间戳。

自定义域名

默认情况下，每个收件箱都会获得一个 @agentsend.io 地址。如果您希望智能体从您自己的域名发送 — 例如 agent@support.yourcompany.com — 您可以连接自定义域名并在创建收件箱时传入 domainId。

💡

自定义域名可以提高投递率和品牌信任度。参阅域名指南添加和验证您的域名，然后回到这里在其上创建收件箱。

列出收件箱

GET /inboxes

检索您账户中所有收件箱的分页列表。使用 limit 和 offset 进行分页。

javascript

const res = await fetch(
  "https://api.agentsend.io/inboxes?limit=20&offset=0",
  {
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const { data, total } = await res.json();
// data  — array of inbox objects
// total — total count across all pages

for (const inbox of data) {
  console.log(inbox.address, inbox.status, inbox.sendsToday);
}

查询参数	类型	说明
`limit`	number	返回的结果数。默认 `20`，最大 `100`。
`offset`	number	跳过的结果数。默认 `0`。

删除收件箱

DELETE /inboxes/{id}

永久删除收件箱及其所有关联的消息、会话和 webhooks。

⚠

此操作是永久性的，无法撤销。属于该收件箱的所有消息、会话和 webhook 订阅将被立即删除。收件箱的邮件地址将被释放并可能被重新分配。

javascript

await fetch(`https://api.agentsend.io/inboxes/${inboxId}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});
// Returns 204 No Content on success

发送限制

每个收件箱都有一个 dailySendLimit，限制其在 24 小时滚动窗口内可以发送的邮件数量。sendsToday 字段告诉您当前窗口内已使用的发送数。

如果收件箱达到限制，后续发送请求将返回 429 Too Many Requests 错误。窗口在 UTC 午夜重置。

ℹ

在发送大量邮件之前监控 sendsToday。如果您的智能体需要发送超过默认限制的邮件，请联系支持以请求提高您账户的限额。

javascript

const inbox = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
).then(r => r.json());

const remaining = inbox.dailySendLimit - inbox.sendsToday;
if (remaining <= 0) {
  console.log("Daily send limit reached. Try again after midnight UTC.");
} else {
  console.log(`${remaining} sends remaining today`);
}