Bandejas de Entrada

Cada agente obtiene su propia bandeja de entrada con una dirección de email única. Las bandejas de entrada son la unidad fundamental en AgentSend.

Descripción General

Una bandeja de entrada es una dirección de email dedicada para un solo agente. Cada email que tu agente envía o recibe fluye a través de una bandeja de entrada. Puedes crear tantas bandejas de entrada como necesites — una por agente, una por cliente, una por flujo de trabajo — no hay límites.

Por defecto, las bandejas de entrada se aprovisionan en el dominio @agentsend.io. Si quieres que tus agentes envíen desde tu propio dominio (ej. agent@yourcompany.com), consulta Dominios Personalizados.

Crear una Bandeja de Entrada

POST /inboxes

Crea una nueva bandeja de entrada enviando una solicitud POST. Ambos campos del cuerpo son opcionales — si omites displayName, la bandeja se crea sin uno. Si omites domainId, la dirección se aprovisiona en @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...

La respuesta incluye el objeto completo de la bandeja de entrada, incluyendo la address generada automáticamente que puedes empezar a usar inmediatamente.

Propiedades de la Bandeja de Entrada

Cada objeto de bandeja de entrada tiene los siguientes campos:

Dominios Personalizados

Por defecto, cada bandeja de entrada obtiene una dirección en @agentsend.io. If you want your agents to send from your own domain — for example agent@support.yourcompany.com — puedes conectar un dominio personalizado y pasar el domainId al crear una bandeja de entrada.

Listar Bandejas de Entrada

GET /inboxes

Recupera una lista paginada de todas las bandejas de entrada en tu cuenta. Usa limit y offset para paginar los 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);
}

Eliminar una Bandeja de Entrada

DELETE /inboxes/{id}

Elimina permanentemente una bandeja de entrada y todos los mensajes, hilos y webhooks asociados.

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

Límites de Envío

Cada bandeja de entrada tiene un dailySendLimit que limita cuántos emails puede enviar en una ventana de 24 horas. El campo sendsToday te dice cuántos envíos se han usado en la ventana actual.

Si una bandeja de entrada alcanza su límite, las solicitudes de envío posteriores devuelven un error 429 Too Many Requests. La ventana se reinicia a medianoche 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`);
}