訊息

訊息代表收件匣發送或接收的個別電子郵件。發送豐富的 HTML 電子郵件、追蹤投遞狀態和讀取內送回覆。

Overview

A message is a single email associated with an inbox. When your agent sends an email it creates an outbound message. When someone replies or sends an email to your agent's address, an inbound message is created automatically.

Every message belongs to a thread — either one that already exists (for replies) or a new thread that is created automatically when a fresh conversation starts.

Sending an Email

POST /inboxes/{inboxId}/messages

Send an email from an inbox by posting to its messages endpoint. The to array and subject are required; everything else is optional.

Request Body

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"

Message Properties

Each message object returned by the API has the following fields.

Message Status

Outbound messages move through a delivery lifecycle. Check delivery first to confirm whether the environment sent real mail or only simulated it, then use status or webhooks to follow the provider-side lifecycle.

Outbound lifecycle

• queued — The message has been accepted and is waiting to be sent.
• sending — The message is actively being delivered to the recipient's mail server.
• sent — The message was accepted by the recipient's mail server.
• delivered — Delivery confirmed (where supported by the receiving server).

Failed states

• failed — A transient or permanent error prevented delivery. Check the webhook payload for the reason.
• bounced — The recipient address does not exist or the server rejected the message permanently.
• complained — The recipient marked the email as spam.

Inbound messages

• received — An email arrived at the inbox from an external sender.

Listing Messages

GET /inboxes/{inboxId}/messages

Retrieve a paginated list of messages for an inbox. Filter by status to find inbound replies, failed sends, or any other subset.

// 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);
}

HTML vs Plain Text

AgentSend supports plain-text, HTML, and multipart emails. Use bodyText for plain text and bodyHtml for HTML content.

• If you provide only bodyText, the email is sent as text/plain.
• If you provide only bodyHtml, the email is sent as text/html.
• If you provide both, the email is sent as multipart/alternative. Email clients that support HTML will show the HTML version; others fall back to the plain-text version.

Deleting Messages

DELETE /messages/{id}

Delete a message by its ID. This removes the message record from AgentSend. It does not recall an already-delivered email from the recipient's mailbox.

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