Mensajes

Los mensajes representan emails individuales enviados o recibidos por una bandeja de entrada. Envía emails HTML enriquecidos, rastrea el estado de entrega y lee las respuestas entrantes.

Descripción General

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.

Enviar un 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"

Propiedades del Mensaje

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

Estado del Mensaje

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.

Listar Mensajes

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 Texto Plano

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.

Eliminar Mensajes

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