Caixas de Entrada

Cada agente recebe sua própria caixa de entrada com um endereço de email único. As caixas de entrada são a unidade fundamental no AgentSend.

Visão Geral

Uma caixa de entrada é um endereço de email dedicado para um único agente. Cada email que seu agente envia ou recebe passa por uma caixa de entrada. Você pode criar quantas caixas de entrada precisar — uma por agente, uma por cliente, uma por fluxo de trabalho — sem limites.

Por padrão, as caixas de entrada são provisionadas no domínio @agentsend.io . Se você quiser que seus agentes enviem do seu próprio domínio (e.g. agent@yourcompany.com), see Domínios Personalizados.

Criando uma Caixa de Entrada

POST /inboxes

Crie uma nova caixa de entrada enviando uma requisição POST. Ambos os campos do corpo são opcionais — se você omitir displayName, a caixa de entrada é criada sem ele. Se você omitir domainId, o endereço é provisionado em @agentsend.io.

const res = await fetch("https://api.agentsend.io/inboxes", {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    displayName: "Support Agent",   // optional
    domainId: "dom_abc123",         // optional — omit for @agentsend.io
  }),
});

const inbox = await res.json();
console.log(inbox.address); // e.g. a1b2c3@agentsend.io
console.log(inbox.id);      // e.g. inb_7x9kQm2Np...

A resposta inclui o objeto completo da caixa de entrada, incluindo o address gerado automaticamente que você pode começar a usar imediatamente.

Propriedades da Caixa de Entrada

Todo objeto de caixa de entrada possui os seguintes campos:

Domínios Personalizados

Por padrão, toda caixa de entrada recebe um endereço em @agentsend.io. Se você quiser que seus agentes enviem do seu próprio domínio — por exemplo agent@support.yourcompany.com — você pode conectar um domínio personalizado e passar o domainId ao criar uma caixa de entrada.

Listando Caixas de Entrada

GET /inboxes

Recupere uma lista paginada de todas as caixas de entrada em sua conta. Use limit and offset para paginar os resultados.

const res = await fetch(
  "https://api.agentsend.io/inboxes?limit=20&offset=0",
  {
    headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
  }
);

const { data, total } = await res.json();
// data  — array of inbox objects
// total — total count across all pages

for (const inbox of data) {
  console.log(inbox.address, inbox.status, inbox.sendsToday);
}

Excluindo uma Caixa de Entrada

DELETE /inboxes/{id}

Exclui permanentemente uma caixa de entrada e todas as mensagens, conversas e webhooks associados.

await fetch(`https://api.agentsend.io/inboxes/${inboxId}`, {
  method: "DELETE",
  headers: { "x-api-key": process.env.AGENTSEND_API_KEY },
});
// Returns 204 No Content on success

Limites de Envio

Cada caixa de entrada possui um dailySendLimit que limita quantos emails pode enviar em uma janela de 24 horas. O campo sendsToday informa quantos envios foram usados na janela atual.

Se uma caixa de entrada atingir seu limite, as requisições de envio subsequentes retornam um erro 429 Too Many Requests . A janela reinicia à meia-noite UTC.

const inbox = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
).then(r => r.json());

const remaining = inbox.dailySendLimit - inbox.sendsToday;
if (remaining <= 0) {
  console.log("Daily send limit reached. Try again after midnight UTC.");
} else {
  console.log(`${remaining} sends remaining today`);
}