Mensagens

Mensagens representam emails individuais enviados ou recebidos por uma caixa de entrada. Envie emails HTML ricos, acompanhe o status de entrega e leia respostas recebidas.

Visão Geral

Uma mensagem é um único email associado a uma caixa de entrada. Quando seu agente envia um email, cria uma mensagem de saída. Quando alguém responde ou envia um email para o endereço do seu agente, uma mensagem de entrada é criada automaticamente.

Toda mensagem pertence a uma conversa — seja uma que já existe (para respostas) ou uma nova conversa que é criada automaticamente quando uma nova conversa começa.

Enviando um Email

POST /inboxes/{inboxId}/messages

Envie um email de uma caixa de entrada postando para seu endpoint de mensagens. O array to e o subject são obrigatórios; todo o resto é opcional.

Corpo da Requisição

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"

Propriedades da Mensagem

Cada objeto de mensagem retornado pela API possui os seguintes campos.

Status da Mensagem

As mensagens de saída passam por um ciclo de vida de entrega. Check delivery first to confirm whether the environment sent real mail ou apenas simulou, then use status or webhooks para acompanhar o ciclo de vida no lado do provedor.

Ciclo de vida de saída

• queued — A mensagem foi aceita e está aguardando para ser enviada.
• sending — A mensagem está sendo ativamente entregue ao servidor de email do destinatário.
• sent — A mensagem foi aceita pelo servidor de email do destinatário.
• delivered — Entrega confirmada (quando suportado pelo servidor receptor).

Estados de falha

• failed — Um erro transitório ou permanente impediu a entrega. Verifique o payload do webhook para o motivo.
• bounced — O endereço do destinatário não existe ou o servidor rejeitou a mensagem permanentemente.
• complained — O destinatário marcou o email como spam.

Mensagens recebidas

• received — Um email chegou na caixa de entrada de um remetente externo.

Listando Mensagens

GET /inboxes/{inboxId}/messages

Recupere uma lista paginada de mensagens de uma caixa de entrada. Filtre por status para encontrar respostas recebidas, envios falhos ou qualquer outro subconjunto.

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

O AgentSend suporta emails em texto simples, HTML e multipart. Use bodyText para texto simples e bodyHtml para conteúdo HTML.

• Se você fornecer apenas bodyText, o email é enviado como text/plain.
• Se você fornecer apenas bodyHtml, o email é enviado como text/html.
• If you provide both, o email é enviado como multipart/alternative. Clientes de email que suportam HTML mostrarão a versão HTML; outros usarão a versão em texto simples.

Excluindo Mensagens

DELETE /messages/{id}

Exclua uma mensagem pelo seu ID. Isso remove o registro da mensagem do AgentSend. Não revoga um email já entregue da caixa de entrada do destinatário.

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