Tin Nhắn

Gửi email đi, liệt kê tin nhắn trong một hộp thư, lấy một tin nhắn, và xóa tin nhắn.

ⓘ

Tất cả yêu cầu cần header x-api-key. URL cơ sở cho mọi endpoint là https://api.agentsend.io.

Đối Tượng Tin Nhắn

Mỗi endpoint trả về tin nhắn sẽ trả về cấu trúc này.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Hello from AgentSend",
  "bodyText": "This email was sent by an AI agent.",
  "bodyHtml": "<p>This email was sent by an AI agent.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v...@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Trường	Kiểu	Mô tả
`id`	string (uuid)	Unique message identifier.
`inboxId`	string (uuid)	The inbox this message belongs to.
`threadId`	string (uuid)	The thread this message belongs to.
`direction`	enum	`outbound` for sent messages, `inbound` for received messages.
`fromAddress`	string	The sender email address.
`toAddresses`	string[]	Primary recipient email addresses.
`ccAddresses`	string[]	CC recipient email addresses.
`subject`	string	Email subject line.
`bodyText`	string \| null	Plain-text body.
`bodyHtml`	string \| null	HTML body.
`delivery`	enum	`email` when AgentSend handed the message to SES, `dry-run` when this environment simulated delivery without actually sending mail.
`status`	enum	Current delivery status. One of `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received`.
`attachments`	AttachmentMeta[]	Mảng các attachment metadata objects (id, filename, contentType, size).
`messageIdHeader`	string	The RFC 5322 `Message-ID` header value.
`createdAt`	string (ISO 8601)	When the message được tạo.

Gửi Tin Nhắn

POST /inboxes/{inboxId}/messages

Send an outbound email from an inbox. The message is queued immediately and returns 202 Accepted along with the new Message object. Check delivery to see whether the environment sent real mail (email) or only simulated it (dry-run). Delivery status updates are available via webhooks or by polling GET /messages/{id}.

Path Parameters

Parameter	Type	Description
`inboxId` bắt buộc	string (uuid)	The ID of the inbox to send from.

Request Body

Parameter	Type	Description
`to` bắt buộc	string[]	One or more recipient email addresses.
`subject` bắt buộc	string	Email subject line. Maximum 998 characters.
`cc`	string[]	CC recipient email addresses.
`bcc`	string[]	BCC recipient email addresses. BCC addresses are not visible to other recipients.
`bodyText`	string	Plain-text body. At least one of `bodyText` or `bodyHtml` should be provided.
`bodyHtml`	string	HTML body. AgentSend automatically generates a text fallback if only HTML is provided.
`threadId`	string (uuid)	Attach this message to an existing thread. If omitted a new thread is created.
`attachmentIds`	string[] (uuid)	IDs of pre-uploaded attachments to include. Upload files first via the Attachments API.

Request Example

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"],
      cc: ["manager@example.com"],
      subject: "Your order is confirmed",
      bodyText: "Hi, your order #1234 has been confirmed.",
      bodyHtml: "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
      attachmentIds: ["att_01hx9k2v3w4x5y6z7a8b9c0d"],
    }),
  }
);

const message = await res.json();
console.log(message.id, message.status); // "msg_...", "queued"

Response — 202 Accepted

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": ["manager@example.com"],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "queued",
  "attachments": [
    {
      "id": "att_01hx9k2v3w4x5y6z7a8b9c0d",
      "filename": "invoice.pdf",
      "contentType": "application/pdf",
      "size": 204800
    }
  ],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Liệt Kê Tin Nhắn

GET /inboxes/{inboxId}/messages

Trả về danh sách có phân trang of messages in an inbox, ordered by createdAt descending. Use the status filter to retrieve only messages in a specific delivery state — for example, status=received to fetch inbound messages your agent should process.

Path Parameters

Parameter	Type	Description
`inboxId` bắt buộc	string (uuid)	The inbox to list messages from.

Query Parameters

Parameter	Type	Description
`limit`	integer	Số lượng messages to return. Default `20`. Maximum `100`.
`offset`	integer	Số lượng messages to skip for pagination. Default `0`.
`status`	enum	Lọc theo delivery status. One of `queued`, `sending`, `sent`, `delivered`, `failed`, `bounced`, `complained`, `received`.

Request Example

javascript

const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/messages?status=received&limit=50`,
  {
    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);
}

Response — 200 OK

json

{
  "data": [
    {
      "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
      "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
      "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
      "direction": "inbound",
      "fromAddress": "customer@example.com",
      "toAddresses": ["agent@yourdomain.com"],
      "ccAddresses": [],
      "subject": "Re: Your order is confirmed",
      "bodyText": "Thanks! Can I change the delivery address?",
      "bodyHtml": null,
      "status": "received",
      "attachments": [],
      "messageIdHeader": "<abc123@mail.example.com>",
      "createdAt": "2026-04-16T10:45:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Lấy Tin Nhắn

GET /messages/{id}

Retrieve a single message by its ID. Use this to poll for delivery status updates after sending.

Path Parameters

Parameter	Type	Description
`id` bắt buộc	string (uuid)	The ID of the message to retrieve.

Request Example

javascript

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

const message = await res.json();
console.log(message.status); // "delivered"

Response — 200 OK

Trả về một single Message object.

json

{
  "id": "msg_01hx9k2v3w4x5y6z7a8b9c0d",
  "inboxId": "ibx_01hx9k2v3w4x5y6z7a8b9c0d",
  "threadId": "thr_01hx9k2v3w4x5y6z7a8b9c0d",
  "direction": "outbound",
  "fromAddress": "agent@yourdomain.com",
  "toAddresses": ["customer@example.com"],
  "ccAddresses": [],
  "subject": "Your order is confirmed",
  "bodyText": "Hi, your order #1234 has been confirmed.",
  "bodyHtml": "<p>Hi, your order <strong>#1234</strong> has been confirmed.</p>",
  "delivery": "email",
  "status": "delivered",
  "attachments": [],
  "messageIdHeader": "<msg_01hx9k2v3w4x5y6z7a8b9c0d@agentsend.io>",
  "createdAt": "2026-04-16T10:23:00.000Z"
}

Xóa Tin Nhắn

DELETE /messages/{id}

Permanently delete a message. This action cannot be undone. Deleting a message does not unsend it — if the email has already been dispatched to recipients it cannot be recalled.

⚠

Deleting a message that is the only message in a thread will also delete that thread.

Path Parameters

Parameter	Type	Description
`id` bắt buộc	string (uuid)	The ID of the message to delete.

Request Example

javascript

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

Response — 204 No Content

Returns an empty body on success.

Trạng Thái Giao Hàng

The status field progresses through the following states for outbound messages. Inbound messages arrive with status: "received".

Status	Description
`queued`	Message accepted and waiting to be dispatched.
`sending`	Currently being transmitted to the recipient mail server.
`sent`	Accepted by the recipient mail server.
`delivered`	Confirmed delivery to the recipient mailbox (where supported).
`failed`	Permanent delivery failure. Check webhook events for details.
`bounced`	Hard bounce — the address does not exist or the server rejected delivery.
`complained`	The recipient marked the message as spam.
`received`	An inbound message received into the inbox.

💡

Subscribe to webhooks to receive real-time status transitions instead of polling the GET endpoint.

← Trước API: Hộp Thư Tiếp → API: Chuỗi Hội Thoại