メッセージ

メッセージは受信トレイで送受信される個々のメールを表します。リッチHTMLメールの送信、配信ステータスの追跡、受信返信の読み取りが可能です。

概要

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.

メールの送信

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.

リクエストボディ

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"

メッセージのプロパティ

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

メッセージステータス

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.

送信ライフサイクル

• 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 — 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.

受信メッセージ

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

メッセージの一覧表示

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 プレーンテキスト

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.

メッセージの削除

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