メッセージ

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.

メッセージオブジェクト

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

フィールド	型	説明
`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.

メッセージの送信

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

パスパラメータ

パラメータ	型	説明
`inboxId` required	string (uuid)	The ID of the inbox to send from.

リクエストボディ

パラメータ	型	説明
`to` required	string[]	One or more recipient email addresses.
`subject` required	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.

リクエスト例

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

メッセージの一覧表示

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.

パスパラメータ

パラメータ	型	説明
`inboxId` required	string (uuid)	The inbox to list messages from.

クエリパラメータ

パラメータ	型	説明
`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`.

リクエスト例

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 /messages/{id}

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

パスパラメータ

パラメータ	型	説明
`id` required	string (uuid)	The ID of the message to retrieve.

リクエスト例

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 /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.

パスパラメータ

パラメータ	型	説明
`id` required	string (uuid)	The ID of the message to delete.

リクエスト例

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.

配信ステータス

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

ステータス	説明
`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: 受信トレイ次へ → API: スレッド