Messages

Send outbound emails, list messages in an inbox, retrieve a single message, and delete messages.

ⓘ

All requests require the x-api-key header. The base URL for every endpoint is https://api.agentsend.io.

The Message Object

Every endpoint that returns a message returns this shape.

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"
}

Field	Type	Description
`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[]	Array of attachment metadata objects (id, filename, contentType, size).
`messageIdHeader`	string	The RFC 5322 `Message-ID` header value.
`createdAt`	string (ISO 8601)	When the message was created.

Send a Message

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` 必填	string (uuid)	The ID of the inbox to send from.

Request Body

Parameter	Type	Description
`to` 必填	string[]	One or more recipient email addresses.
`subject` 必填	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"
}

List Messages

GET /inboxes/{inboxId}/messages

Returns a paginated list 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` 必填	string (uuid)	The inbox to list messages from.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of messages to return. Default `20`. Maximum `100`.
`offset`	integer	Number of messages to skip for pagination. Default `0`.
`status`	enum	Filter by 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
}

Get a Message

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` 必填	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

Returns a 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"
}

Delete a Message

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` 必填	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.

Delivery Statuses

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.

← 上一篇 API: Inboxes 下一篇 → API: Threads