消息

消息代表收件箱发送或接收的单封邮件。发送富 HTML 邮件、跟踪投递状态并读取入站回复。

概述

消息是与收件箱关联的单封邮件。当您的智能体发送邮件时，会创建一条出站消息。当有人回复或发送邮件到您智能体的地址时，会自动创建一条入站消息。

每条消息都属于一个会话 — 要么是已存在的（用于回复），要么是在新对话开始时自动创建的新会话。

ℹ

消息一旦创建便不可修改。要发送后续消息，请通过传递 threadId 在同一会话中创建新消息。

发送邮件

POST /inboxes/{inboxId}/messages

通过向收件箱的消息端点发送 POST 请求来发送邮件。to 数组和 subject 是必填的；其他所有字段都是可选的。

请求体

字段	类型	说明
`to` 必填	string[]	收件人邮件地址数组。
`subject` 必填	string	邮件主题行。
`cc`	string[]	抄送收件人。
`bcc`	string[]	密送收件人。对其他收件人不可见。
`bodyText`	string	纯文本正文。当同时提供 `bodyHtml` 时用作后备。
`bodyHtml`	string	HTML 正文。当同时提供 `bodyText` 和 `bodyHtml` 时，邮件以 multipart/alternative 格式发送。
`threadId`	string	要回复到的会话。如果省略，将创建新会话。
`attachmentIds`	string[]	要包含的先前上传的附件 ID。

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages`,
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.AGENTSEND_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      to: ["customer@example.com"],
      subject: "Following up on your request",
      bodyText: "Hi, just checking in on your request.",
      bodyHtml: "<p>Hi, just checking in on your request.</p>",
    }),
  }
);

const message = await res.json();
console.log(message.id);     // msg_abc123
console.log(message.delivery); // "email" or "dry-run"
console.log(message.status); // "queued"

消息属性

API 返回的每个消息对象都有以下字段。

Property	Type	Description
`id`	string	唯一消息标识符。
`inboxId`	string	此消息所属的收件箱。
`threadId`	string	此消息归入的会话线程。
`direction`	string	`outbound` 表示您的智能体发送的邮件；`inbound` 表示接收的邮件。
`fromAddress`	string	发件人邮件地址。
`toAddresses`	string[]	主要收件人。
`ccAddresses`	string[]	抄送收件人。
`subject`	string	Email subject line.
`bodyText`	string	纯文本正文内容。
`bodyHtml`	string	HTML 正文内容。
`delivery`	string	环境是否发送了真实邮件（`email`）还是仅模拟（`dry-run`）。
`status`	string	当前投递状态。请参阅下方的消息状态。
`attachments`	object[]	附件对象数组，包含 `id`、`filename`、`contentType` 和 `size`。
`messageIdHeader`	string	RFC 5322 `Message-ID` 头部值，用于邮件客户端中的线程处理。
`createdAt`	string	消息创建时间的 ISO 8601 时间戳。

消息状态

出站消息经历投递生命周期。首先检查 delivery 确认环境是否发送了真实邮件，然后使用 status 或 webhooks 跟踪提供商端的生命周期。

出站生命周期

queued — 消息已被接受，正在等待发送。
sending — 消息正在积极投递到收件人的邮件服务器。
sent — 消息已被收件人的邮件服务器接受。
delivered — 投递已确认（在接收服务器支持的情况下）。

失败状态

failed — 临时或永久性错误阻止了投递。检查 webhook 载荷以了解原因。
bounced — 收件人地址不存在或服务器永久拒绝了消息。
complained — 收件人将邮件标记为垃圾邮件。

入站消息

received — 一封来自外部发件人的邮件到达了收件箱。

⚠

如果消息达到 bounced 或 complained 状态，请避免向该地址发送更多邮件以保护您的发件人声誉。

列出消息

GET /inboxes/{inboxId}/messages

检索收件箱消息的分页列表。按状态过滤以查找入站回复、失败发送或任何其他子集。

查询参数	类型	说明
`limit`	number	返回的消息数。默认 `20`，最大 `100`。
`offset`	number	分页跳过的消息数。默认 `0`。
`status`	string	按状态过滤。值为 `queued`、`sending`、`sent`、`delivered`、`failed`、`bounced`、`complained`、`received` 之一。

javascript

// Fetch the 10 most recent inbound messages
const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=10`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data, total } = await res.json();

for (const msg of data) {
  console.log(msg.fromAddress, msg.subject, msg.bodyText);
}

💡

使用 webhooks 而不是轮询，以便在新消息到达时立即获得通知。轮询是简单脚本和短期任务的良好后备方案。

HTML 与纯文本

AgentSend 支持纯文本、HTML 和多部分邮件。使用 bodyText 发送纯文本，使用 bodyHtml 发送 HTML 内容。

如果只提供 bodyText，邮件将以 text/plain 格式发送。
如果只提供 bodyHtml，邮件将以 text/html 格式发送。
如果同时提供两者，邮件将以 multipart/alternative 格式发送。支持 HTML 的邮件客户端将显示 HTML 版本；其他客户端则使用纯文本版本。

💡

始终在 bodyHtml 旁边包含 bodyText 版本。这可以提高投递率、可访问性以及与纯文本邮件客户端的兼容性。

删除消息

DELETE /messages/{id}

通过 ID 删除消息。这将从 AgentSend 中移除消息记录。它不会从收件人的邮箱中撤回已投递的邮件。

javascript

await fetch(`https://api.agentsend.io/messages/${messageId}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});

⚠

删除消息是永久性的。属于活跃会话的入站消息应谨慎删除，因为会话历史将不完整。