Saltar al contenido

Conecta y sigue un buzón

Un buzón es la conexión de correo desde la que envías o recibes mensajes. Lee sus datos primero. Estar conectado no significa, por sí solo, que pueda enviar.

Lee su estado

import { Colding } from "colding";

const colding = new Colding("cd_your_key");
const mailboxId = "22222222-2222-4222-8222-222222222222";
const mailbox = await colding.mailboxes.get({ mailboxId });
console.log(mailbox.state, mailbox.ownership.state);

mailboxes.get pide read y no cambia nada. Cambia mailboxId por un ID de mailboxes.list() o de mailboxIds en una conversación. La primera guía muestra cómo conseguir una clave de API.

Ejemplo de un buzón ficticio. Está conectado y la dirección remitente está confirmada.
connected proven
connected
El buzón no está en pausa y sus datos de acceso no están marcados para reemplazo. La confirmación de la dirección y las demás comprobaciones de envío siguen vigentes.
needs_reconnect
El proveedor rechazó el acceso. Pide al dueño que actualice los datos de acceso en la consola, con la solicitud de abajo.
paused
El envío está en pausa. La recepción continúa mientras los datos de acceso funcionen. Consulta sync para ver si se está leyendo el correo.

La respuesta completa también trae provider, purpose, dailyCap, minGapSeconds, problems, domainAuth, sync, warmup y sendState. ownership dice si la dirección remitente está confirmada. sendState es una espera para campañas, no permiso para un mensaje suelto.

Las contraseñas nunca se devuelven. Un buzón solo de envío también oculta el usuario SMTP, porque puede ser un secreto. smtp e imap pueden ser null según la conexión del buzón.

Conéctalo o pide al dueño que lo conecte

Con setup, una clave conecta el buzón por sí sola con mailboxes.connect o mailboxes.connectSendOnly y cambia sus datos de acceso con mailboxes.updateCredentials. Conecta cada buzón en nombre del dueño. El inicio de sesión con Microsoft o Google y la desconexión siguen en manos del dueño, en la consola. El enlace de una solicitud no aprueba un envío. Con setup, mailboxes.previewBatch comprueba un archivo CSV sin guardar ni probar accesos. mailboxes.connectBatch pone las filas listas en la cola. Síguelas con mailboxes.getBatch, busca archivos anteriores con mailboxes.listBatches y detén las filas en cola con mailboxes.cancelBatch. Una fila que ya se está comprobando termina; los buzones conectados siguen conectados. Las cinco llamadas necesitan setup, no read ni send. Las direcciones y celdas abarcan todo el workspace, así que una clave con una lista de lectura de buzones no puede usarlas.

Antes de conectarla o pedírselo al dueño, consulta la dirección. mailboxes.detectSettings dice quién gestiona su correo (name), qué servidores usa y qué contraseña necesita (password): normal, app_password (una contraseña aparte que el proveedor crea para una sola aplicación), app_password_with_2fa (contraseña de aplicación solo si la verificación en dos pasos está activa) o secure_mail_key (el nombre que AT&T da a su contraseña de aplicación). Pide read, solo consulta el DNS y nunca inicia sesión en el buzón.

import { Colding } from "colding";

const colding = new Colding("cd_your_key");
const found = await colding.mailboxes.detectSettings({ email: "ana@example.com" });
console.log(found.name, found.password);
Ejemplo de una dirección en Google Workspace.
Google app_password

accessSwitch indica una opción que el dueño tiene que activar antes en el proveedor: imap (acceso IMAP) o third_party (acceso de otras apps de correo). signIn indica un proveedor cuyo propio inicio de sesión conecta el buzón en lugar de la contraseña, y unavailable dice por qué ninguno de nuestros accesos llega a él. Si no se encuentra nada, servers es nulo y source es none. Entonces unresolved dice por qué: dns_unanswered (el DNS no respondió, así que vuelve a intentarlo) o not_published (el dueño escribe los servidores en la consola). Cada workspace puede consultar 20 direcciones por minuto.

SMTP envía correo e IMAP lo lee. Una clave sin setup pide esa conexión con una solicitud que da al dueño un enlace a la consola, llamada handoff en la API. Crear una pide operate. Dale url al dueño. Quien recibe el enlace inicia sesión e introduce los datos de acceso en la consola, no en un chat con el agente.

const request = await colding.handoffs.create({
  kind: "connect_mailbox",
});
console.log(request.url);

Lee la misma solicitud con handoffs.get, que pide read. Una solicitud completada identifica el buzón en resultMailboxId. Lee ese buzón para ver su estado actual.

const now = await colding.handoffs.get({ handoffId: request.id });
console.log(now.status);
if (now.status === "completed" && now.resultMailboxId) {
  const mailbox = await colding.mailboxes.get({ mailboxId: now.resultMailboxId });
  console.log(mailbox.ownership);
}

Una solicitud está en pending, completed, cancelled o expired. Las pendientes caducan a las 24 horas. Si caduca, crea una nueva. Para retirar una que ya no necesitas, llama a handoffs.cancel con handoffId. Cancelar pide operate y nunca desconecta un buzón que ya se conectó.

Sin setup, pide nuevos datos de acceso con un handoff update_mailbox_credentials que indique el mailboxId. El dueño introduce los nuevos en la consola. Una comprobación aprobada los reemplaza, pero no deshace una pausa del buzón.

const request = await colding.handoffs.create({
  kind: "update_mailbox_credentials",
  mailboxId,
});
console.log(request.url);

Antes de guardar una conexión o nuevos datos de acceso, comprobamos el acceso por conexiones cifradas. Si falla la comprobación, no se guarda nada y la llamada responde 400 VALIDATION_ERROR, con el campo y el motivo en details. rate_limited significa que el proveedor limitó el acceso por un tiempo, no que la contraseña sea incorrecta: espera unos minutos y vuelve a intentarlo. Para otros fallos, corrige el problema indicado y reintenta. Superar la comprobación prueba que el acceso funcionó en ese momento, no que el correo llegará ni que la dirección es tuya.

Si la comprobación no termina en 15 segundos, o el worker no está disponible, responde 503 SERVICE_UNAVAILABLE, que permite reintentar, con messageKey: serverErrors.mailboxCheckUnavailable. No se guarda nada. No hay cabecera Retry-After. Reintenta la comprobación, o pide al dueño que la reintente.

Usa SMTP para los correos de tu app

Un buzón solo de envío usa los datos de acceso SMTP de un servicio de envío, sin IMAP. Con setup, conéctalo con mailboxes.connectSendOnly. Sin ese permiso, pide al dueño en la solicitud de conexión que elija Servicio de envío (solo envío). Aparece como provider: smtp_only y purpose: transactional.

Envía el correo transaccional de tu app, como un recibo o un enlace de acceso. Nunca envía campañas, inicia mensajes sueltos ni hace calentamiento. Necesita un plan con correo transaccional y cuenta para el límite de buzones del plan. El servicio debe pedir acceso SMTP antes de que guardemos el buzón.

No podemos leer el correo enviado a esa dirección. Las respuestas van adonde ya va el resto del correo de tu dominio. Define replyTo en el buzón con mailboxes.update, o en el correo transaccional, para elegir una dirección que alguien lea. Conecta un buzón que reciba mensajes si necesitas esas respuestas en esta bandeja de entrada.

Los rebotes y las denuncias de spam que llegan después necesitan el webhook de informes del servicio de envío. Con setup, llama a mailboxes.setReportHook para activarlo o cambiar el secreto, y a mailboxes.disableReportHook para desactivarlo. En Mailgun, Resend y SendGrid, envía el secret del servicio. En Amazon SES, envía topicArn en su lugar. En Postmark, no envíes ninguno: la primera respuesta incluye una contraseña. Cópiala en ese momento; las consultas y las respuestas repetidas no la muestran. Tanto mailboxes.reportHook como mailboxes.reports necesitan read. Sin setup, pídeselo al dueño con un handoff manage_report_hook y el id de este buzón. Un cambio hecho por el dueño completa todas las solicitudes pendientes de este buzón que no hayan caducado, en la misma transacción, incluso sin su enlace. Un cambio hecho por una clave no completa ninguna.

Envía el correo transaccional de tu app

Confirma la dirección remitente

Un acceso que funciona no prueba la dirección remitente. ownership.state es unproven (sin confirmar), pending (esperando un código) o proven (confirmada). No se envía nada mientras esté unproven o pending, ni respuestas, pruebas, correo transaccional ni calentamiento. La lectura sigue funcionando.

El dueño confirma la dirección en la consola, en Dirección de envío, dentro del Resumen del buzón. Enviamos un código por correo a esa dirección, y el dueño pulsa el botón del correo o escribe el código. Si la dirección no recibe correo, pide a nuestro equipo que la confirme de otra forma.

Con setup, tu clave también puede confirmar la dirección. Pide un código, busca el correo que enviamos a esa dirección (el código está en el asunto) y envía el código de vuelta. Solo cuenta un código que enviamos a la dirección. Unos datos de acceso que funcionan nunca cuentan. Para cancelar un código pendiente, llama a mailboxes.cancelConfirmation.

await colding.mailboxes.requestConfirmation({ mailboxId });
// Read the code in that email's subject, then send it back.
const mailbox = await colding.mailboxes.confirmAddress({ mailboxId, code: codeFromEmail });
console.log(mailbox.ownership.state);

Pide a nuestro equipo que confirme una dirección

Si hay un código pendiente, ownership incluye expiresAt y mail, el estado del correo de ese código. Pendiente no significa confirmado. Para pedírselo al dueño, crea un handoff confirm_mailbox_address con el mailboxId.

Incluso con proven, enviar todavía requiere el permiso que corresponda, los límites de la clave que puso el dueño, la política de uso aceptable, el plan, el pago y las verificaciones del destinatario. Las pausas y otras esperas del buzón siguen vigentes. Usa la guía de envío para el mensaje que quieras enviar.

Lee las comprobaciones de envío

Comprueba la lectura y el correo importado

resync es Comprobar ahora. Pide al worker que mire el buzón antes de la comprobación normal (hoy, aproximadamente cada 60 segundos). Pide operate. La respuesta muestra el buzón en ese momento, no prueba que la nueva lectura terminó. Lee mailboxes.get de nuevo más tarde.

await colding.mailboxes.resync({ mailboxId });

const mailbox = await colding.mailboxes.get({ mailboxId });
console.log(mailbox.sync);

const folders = await colding.mailboxes.folders({ mailboxId });
console.log(folders);

sync.startedAt es cuando la lectura listó las carpetas por primera vez. lastSuccessAt es la última pasada que terminó sin dejar nada en espera. Null significa que no terminó ninguna pasada así, no que el buzón esté vacío. nextAt dice cuándo toca la siguiente. failures cuenta fallas seguidas, y pending cuenta mensajes encontrados pero aún no guardados.

sync.import describe la importación única del correo que ya existía, del más reciente al más antiguo. Su status es pending, running o complete. since y limit son el período y el límite de mensajes fijados al empezar. imported cuenta lo guardado, y completedAt dice cuándo terminó. Complete no significa que se importó todo el historial del proveedor.

sync.folders cuenta las carpetas descubiertas y vigiladas. mailboxes.folders lista la ruta del proveedor, role, watched, excludedReason, pending e importDone de cada una. Una carpeta excluida indica el motivo, sin fingir que se leyó. Esta llamada pide read.

Si se rechazó un acceso SMTP o IMAP, Comprobar ahora prueba primero los datos guardados. Cuando ambos pasan, limpia el error de acceso para que los envíos y el calentamiento puedan continuar, manteniendo tu pausa y otras esperas. Si el servidor sigue rechazando IMAP, o acepta IMAP y sigue rechazando SMTP después de que volvamos a leer, responde 409: pide al dueño que actualice los datos de acceso. Si las comprobaciones de ese servidor están en espera, un 429 dice cuándo reintentar. Un buzón solo de envío responde 409 porque no recibe correo que leer.

Lee el correo que llegó

Comprueba el dominio de envío

El dominio de envío es la parte después de la @. Los registros DNS dicen a los servidores que reciben quién puede enviar desde él. checkDomain lee los registros ahora y guarda el resultado en los buzones de este workspace que usan ese dominio. Pide operate.

const mailbox = await colding.mailboxes.checkDomain({ mailboxId });
for (const record of mailbox.domainAuth.records) {
  if ((record.check === "not_verified" || record.check === "wrong") && record.value !== null) {
    console.log(record.type, record.name, record.value);
    for (const old of record.replaces) console.log("  in place of:", old);
  } else if (record.reason !== null) {
    console.log(record.type, record.name, "no value:", record.reason);
  }
}

SPF y DMARC deciden si el dominio está en passing o failing. Un buzón solo de envío se evalúa solo por DMARC. SPF solo pasa con exactamente un registro, y cuando comprobar el correo de este buzón lleva como máximo 10 consultas DNS (spfLookups). Los servidores que reciben el correo comprueban SPF en orden y se detienen en el primer término que coincide, así que contamos hasta el include de tu proveedor de correo, con todas las consultas dentro de él, o el registro entero cuando no conocemos ese include. Contamos sin un mensaje real, así que es el camino que sigue el correo de tu proveedor, no una prueba con uno. DKIM aparece como encontrado o sin verificar, nunca ausente: DNS no puede listar todos los selectores, los nombres bajo los que se publican las claves DKIM. Cuando SPF o DMARC falla, domainAuth.dnsHost dice dónde está el DNS del dominio, leído de sus servidores de nombres: hosts lista los proveedores de DNS que coinciden (vacío si no conocemos el proveedor), y el valor entero viene en null si el DNS no respondió.

domainAuth.records enumera lo que debes publicar: step, type, el name completo, nameInZone relativo a dnsHost.zone (@ en la propia zona, null si no conocemos la zona), value, priority, check, observed, replaces y reason. Un buzón solo de envío no recibe una fila SPF. DMARC no aparece si ya lo cubre un registro del dominio o de uno superior. Los nombres reservados no reciben registros.

Si check es unanswered o not_checked, vuelve a llamar a checkDomain antes de cambiar el DNS. Publica solo las filas con check: not_verified o wrong y un value no nulo, con tu propio acceso al DNS, y comprueba de nuevo. Si replaces enumera registros, publica value en su lugar: edita el registro que hay, o bórralos y agrega value, para que el nombre quede con un solo registro SPF y un solo DMARC. Nunca publiques un valor null. reason dice por qué es null. include_unknown: no conocemos el include, el nombre que autoriza a tu proveedor de correo, así que pídeselo al proveedor. too_many_lookups: comprobar tu correo con este SPF lleva más de 10 consultas DNS, así que quita los include de servicios que el dominio ya no usa, o pon primero el include de tu proveedor de correo. cannot_merge: los registros SPF del dominio no se pueden unir de forma segura, así que únelos en uno solo a mano. Un registro DMARC roto se cambia por p=none, nunca por algo más estricto; nunca cambies una política que funciona por otra más débil. Configura DKIM en el proveedor de correo. Nunca pedimos tu contraseña ni tu token de DNS.

MCP de Cloudflare: usa tu propio acceso al DNS (en inglés)

Si los registros obligatorios siguen fallando durante 72 horas, las campañas, los mensajes nuevos, las respuestas a correos tuyos y el calentamiento dejan de usar estos buzones hasta que una comprobación pase. Las respuestas a correos recibidos siguen saliendo. failingSince indica cuándo empezó ese plazo. Corrige los registros con quien administra el dominio y vuelve a llamar a checkDomain.

unknown significa sin conclusión, no aprobado ni rechazado. unknownReason dice si DNS no respondió o el dominio es un nombre reservado. Un timeout no borra una falla ya registrada. Comprueba de nuevo cuando DNS responda. Estos registros nunca prometen entrega.

Algunos proveedores de DNS pueden agregar el registro DMARC que falta: el dueño ve el registro en la propia página del proveedor y lo aprueba. Esto usa un estándar llamado Domain Connect. domainConnectLink devuelve ese enlace. Pide operate. mailboxes.spfConnectLink requiere consent: allow_mail_service después de que la persona acepte autorizar al servicio del buzón a enviar en nombre del dominio. La operación usa los ajustes de proveedores que hemos verificado y mantiene los pasos manuales cuando no hay un enlace seguro. El enlace solo crea el primer registro SPF del dominio y solo se ofrece en proveedores de DNS que hemos verificado para él; mientras no haya ninguno, url viene siempre en null y los pasos manuales siguen.

const link = await colding.mailboxes.domainConnectLink({ mailboxId });
console.log(link.url ?? link.reason);
// After the person agrees to allow the mailbox's mail service in SPF:
const spf = await colding.mailboxes.spfConnectLink({ mailboxId, consent: "allow_mail_service" });
console.log(spf.url ?? spf.reason);

La respuesta trae la url y el nombre del proveedor en provider, o la url nula y un motivo en reason: not_set_up (todavía no activamos los enlaces de un clic), not_offered (el proveedor de DNS del dominio no ofrece nuestro registro, o el dominio ya tiene un registro DMARC que quien recibe el correo ignora, y lo cambias a mano por la fila DMARC de domainAuth.records), unanswered (el DNS o el proveedor no respondió a tiempo, así que vuelve a intentarlo) o nothing_to_add (un registro DMARC ya cubre el dominio). Ningún proveedor ofrece nuestros registros todavía, así que por ahora cada respuesta trae un motivo y ningún enlace. Dale el enlace al dueño. Abre la página del proveedor, y el proveedor lo devuelve a la consola, o a la página de la consola que indiques en returnTo (una ruta como /acme/mailboxes). Volver no prueba nada, así que llama a checkDomain después. Cada workspace puede pedir 30 enlaces por minuto.

El registro CNAME de un dominio de seguimiento tiene el mismo tipo de enlace: trackingDomains.connectLink recibe un trackingDomainId y responde igual, con nothing_to_add cuando el dominio ya está verificado.

Pausa el envío o desconecta

mailboxes.pause detiene lo que sale del buzón. Las campañas y el calentamiento esperan, y los envíos nuevos se rechazan. El correo sigue llegando y se lee mientras los datos de acceso funcionen. Los ajustes y los datos de acceso se quedan. No puede recuperar un correo que ya está en camino. Pide operate.

const mailbox = await colding.mailboxes.pause({ mailboxId });
console.log(mailbox.state, mailbox.sync.lastSuccessAt);

mailboxes.resume con mailboxId quita esa pausa. También pide operate. No arregla un acceso rechazado, confirma una dirección ni quita una espera separada.

Desconectar es una acción del dueño en la consola, sin método público del SDK ni tipo de handoff. Elimina la conexión, los datos de acceso, los ajustes y los mensajes de ese buzón guardados en colding. El correo en tu proveedor no se elimina. No se puede deshacer. Las retenciones de calentamiento ligadas a la dirección se quedan, así que volver a conectar no sirve para quitarlas.

Copia el correo antiguo a nuestros servidores

La copia de correo antiguo lleva las carpetas y los mensajes de un buzón desde su servidor antiguo a un buzón nuevo con la misma dirección, que nuestro equipo crea en nuestros servidores de correo. Por ahora solo está disponible para nuestros propios workspaces y copia desde el servidor de Zoho Mail para planes de pago en EE. UU., imappro.zoho.com. Nuestro equipo ejecuta cada paso de la copia a mano, así que un paso empieza cuando alguien del equipo lo toma.

Empieza con mailboxes.migrationPreflight. Solo lee lo que ya sabemos: no se llama a ningún servidor, no se lee ningún DNS y no cambia nada. supported es true cuando blockers está vacío, y cada bloqueo indica algo que resolver antes.

const ready = await colding.mailboxes.migrationPreflight({ mailboxId });

if (ready.supported && !ready.activeMigrationId) {
  // Starting is an owner's approval, so the key asks one.
  const request = await colding.handoffs.create({ kind: "approve_mailbox_migration", mailboxId });
  console.log(request.url);
}

const [latest] = await colding.mailboxes.listMigrations({ mailboxId });
if (latest) {
  const migration = await colding.mailboxes.getMigration({ mailboxId, migrationId: latest.id });
  console.log(migration.phase, migration.next.actor, migration.next.reason);

  if (migration.next.reason === "owner_mx") {
    const checked = await colding.mailboxes.checkMigrationMx({
      mailboxId,
      migrationId: latest.id,
    });
    console.log(checked.mx.lastCheck?.result);
  }
}

Empezar una copia, aprobar sus carpetas y reanudarla son aprobaciones del dueño, como iniciar una campaña, así que ninguna clave puede hacerlo. Pídeselo a un dueño con handoffs.create, kind approve_mailbox_migration y el mailboxId. La solicitud se rechaza para un buzón en el que no se ofrece la copia.

Después, lee la copia con mailboxes.listMigrations y mailboxes.getMigration. next.actor dice quién actúa ahora: owner, team, time o none. next.reason dice sobre qué. Una copia todavía no envía eventos, así que vuelve a leerla cuando necesites saber cómo va.

Cuando el dueño cambia los datos de acceso al buzón nuevo, cambia el registro MX del dominio en su proveedor de DNS. mailboxes.checkMigrationMx lee el registro y guarda lo que encontró. Nunca cambiamos un registro DNS. Cuando el registro solo apunta a nuestro servidor, esperamos 10 minutos para que los remitentes vean el cambio, y después nuestro equipo copia el correo que llegó al servidor antiguo mientras tanto. Desde ahí, todas las direcciones y alias del dominio reciben su correo en nuestros servidores.

Desde el cambio de datos de acceso hasta que se copia el último correo, no sale nada del buzón: ningún paso de campaña, mensaje nuevo, respuesta ni calentamiento. El campo hold de la copia lo indica.

mailboxes.cancelMigration detiene la copia después del paso en curso. Pide operate. El correo ya copiado queda en el buzón nuevo, no se elimina nada en ninguno de los dos servidores y ningún dato de acceso ni registro DNS vuelve atrás.

Una copia acepta hasta 512 carpetas y mensajes de hasta 64 MiB. Al pasar un límite, se detiene y dice por qué: nunca se salta un mensaje. El correo copiado queda en el buzón nuevo, y la bandeja de entrada de colding sigue mostrando solo el correo antiguo que ya muestra.

Inicia y lee el calentamiento

El calentamiento intercambia correo con un grupo de buzones, llamado pool. Envía correo real, así que startWarmup pide send. El dueño también debe haber aceptado la política de uso aceptable. Puede habilitarse antes de confirmar la dirección remitente, pero no envía nada hasta confirmarla. Los límites de la clave para buzones y flujos siguen vigentes. Una clave limitada a correo transaccional no inicia calentamiento. Los buzones solo de envío y los buzones por la API de Gmail nunca hacen calentamiento.

const mailbox = await colding.mailboxes.startWarmup({ mailboxId });
console.log(mailbox.warmup.state, mailbox.warmup.blockedBy);
console.log(mailbox.warmup.sentToday, mailbox.warmup.todayCap);

const days = await colding.mailboxes.warmupStats({ mailboxId });
console.log(days);

Lee warmup.state, blockedBy, sentToday y todayCap en la respuesta. Running significa habilitado, no que envía en este momento. todayCap es el límite real de hoy, considerando el tamaño del pool, los días y la salud. dailyTarget es la meta de la rampa, no una cantidad prometida de mensajes.

day cuenta tiempo de calentamiento, no días del calendario desde la conexión. rampHeldUntil dice cuándo termina una espera por haber caído en spam. health trae la banda de salud y sus lecturas, o null si no hay lectura. Una lectura de denuncias ausente es sin datos, no cero. health.probation puede reducir el calentamiento después de una cuarentena o un bloqueo, incluso si la banda dice saludable.

blockedBy indica el primer motivo que debes resolver: suspensión del workspace, retención de nuestro equipo, dirección sin confirmar, acceso rechazado, pausa del buzón, espera por salud, dominio o falta de buzones compañeros. La retención de nuestro equipo tiene su motivo en staffBlock. Pide una revisión con mailboxes.appealWarmup, pasando mailboxId y reason. Pide operate y no levanta la retención por sí sola. Solo una apelación puede esperar a la vez.

mailboxes.pauseWarmup con mailboxId pausa el envío de calentamiento, pero mantiene el buzón en el pool y conserva su rampa. Los buzones compañeros aún pueden escribirle. Reanuda con startWarmup. mailboxes.stopWarmup sale del pool. La próxima ronda empieza la rampa desde el primer día. Pausar y finalizar piden operate y conservan las horas, los días y la tasa de respuesta guardados. Ninguno quita la espera por salud ni la retención del equipo ligada a la dirección.

await colding.mailboxes.pauseWarmup({ mailboxId });

await colding.mailboxes.stopWarmup({ mailboxId: otherMailboxId });

const appealed = await colding.mailboxes.appealWarmup({
  mailboxId,
  reason: "We fixed the domain's records on 5 October.",
});
console.log(appealed.warmup.blockedBy);

receiveOnly: true en el primer inicio permite que los buzones compañeros escriban al buzón sin que este envíe calentamiento. Reanuda con el mismo valor. Para cambiar de modo, finaliza primero. window y days usan el reloj del workspace.

warmupStats pide read y devuelve 30 días por defecto, incluido hoy. Pasa days para leer hasta 90. Cada día dice qué salió, su límite, qué encontraron los buzones compañeros en spam y qué llegó aquí. El calentamiento no aparece en la bandeja de entrada ni genera eventos send.*. No promete en qué carpeta caerá el correo.

Lee dónde llega tu correo

deliverability.get pide read y responde en una sola llamada, sin nota. Pasa days como 7, 14 o 30, contando hoy, en el calendario del workspace. Si no lo pasas, vale 7. Lee todos los buzones y campañas del workspace, así que una clave limitada a algunos buzones recibe 403 keyReads.

const answer = await colding.deliverability.get({ days: 14 });

for (const domain of answer.placement.domains) {
  for (const row of domain.providers) {
    console.log(domain.domain, row.provider, row.counts.arrived, row.counts.spam);
  }
}

for (const mailbox of answer.attention.mailboxes) {
  const worst = mailbox.reasons[0];
  console.log(mailbox.email, worst?.reason, worst?.stops, worst?.until);
}

placement es el calentamiento, por dominio de envío y proveedor de destino. Cada fila de proveedor cuenta los correos que arrived (llegaron), los que el buzón compañero encontró en spam (parte de los arrived), los que neverArrived (nunca llegaron), los que el servidor de tu buzón rechazó (bounced), los que todavía están tooSoon para juzgarlos y los que dejamos fuera (leftOut). La suma da sent. atTestInboxes cuenta cuántos de los correos que llegaron fueron a un buzón de prueba nuestro.

fromOurServers es lo que respondieron los servidores de destino sobre los correos que salieron de nuestros servidores, por stream (cold o transactional) y proveedor. Aceptado significa que el servidor recibió el correo, no que llegara a la bandeja de entrada. noWordYet cuenta los correos que todavía no tienen respuesta. El valor es null cuando el workspace no tiene bandeja de entrada de agente ni dirección de remitente y no envió nada por nuestros servidores en la ventana.

attention lista los buzones y las campañas que una de nuestras reglas pausó o frenó. Cada uno trae su motivo, lo que el motivo impide (sending, first_contact, campaigns, warmup, nothing_yet o slows_warmup) y cuándo empezó y cuándo termina. La pausa que hizo una persona no aparece. Las listas guardan 100 elementos como máximo, y more cuenta el resto.

Un porcentaje llega como { pct, of, bound }, y bound es under1 u over99 cuando la cifra está cerca de 0 o de 100, pero no es exactamente ese número. El porcentaje solo aparece a partir de 20 correos de calentamiento (placement.floor) o de 50 mensajes (floor). Por debajo recibes { tooFew, floor }.

Las denuncias de spam son un conteo, nunca un porcentaje, porque la mayoría de los proveedores no envía ninguna. source: false quiere decir un proveedor que no le cuenta nada al remitente, y eso no es 0. days trae una entrada por día de la ventana, con cero donde no pasó nada.

Responde a una revisión

Nuestro equipo puede poner un buzón en revisión, por ejemplo después de denuncias sobre su correo. Mientras dura, review en mailboxes.get, mailboxes.list y en las lecturas de bandeja de entrada de agente no es null. Sin revisión, es null.

Lee primero review.caseNumber y cítalo cuando nos escribas. since dice cuándo empezó la revisión, y until es la fecha en que dijimos que la revisaríamos. Nada se levanta cuando pasa until, y overdue pasa a true. reason trae las palabras de nuestro equipo, o null si fue el sistema quien puso el buzón en revisión. answeredAt es null hasta que nos cuentes qué pasó.

const mailbox = await colding.mailboxes.get({ mailboxId });

if (mailbox.review) {
  const review = await colding.mailboxes.answerReview({
    mailboxId,
    whatHappened: "Our 3 September campaign went to a list we bought. Some people had not asked.",
    whatChanged: "We deleted that list and paused the campaign.",
    howItStaysFixed: "From now on we only write to people who signed up on our site.",
  });
  console.log(review.caseNumber, review.answeredAt);
}

Cuéntanos qué pasó con mailboxes.answerReview. Pasa mailboxId y tres respuestas con tus propias palabras: whatHappened, whatChanged y howItStaysFixed. Cada una tiene de 1 a 2000 caracteres. Pide operate, y una clave limitada a algunos buzones solo puede responder por ellos. La respuesta es la revisión, con answeredAt ya puesto.

Nuestro equipo lee las tres respuestas junto con el caso. Si las envías otra vez, reemplazan la respuesta anterior. Esto no levanta nada: solo nuestro equipo termina una revisión. Un buzón que no está en revisión responde 409, así que lee review antes. También funciona mientras el workspace espera su eliminación.

Sirve también para una bandeja de entrada de agente. Pasa el id de la bandeja como mailboxId. Las lecturas de bandeja de entrada de agente traen el mismo campo review.

Sigue los cambios del buzón

Lee mailbox.failed, mailbox.recovered, mailbox.address_confirmed y mailbox.warmup_health_changed por events.list o un webhook. Identifican el buzón y el cambio, sin datos de acceso. Un evento de llegada es de correo nuevo después del inicio de la lectura, nunca de correo antiguo importado.

const page = await colding.events.list({
  types: [
    "mailbox.failed",
    "mailbox.recovered",
    "mailbox.address_confirmed",
    "mailbox.warmup_health_changed",
  ],
});
console.log(page.items);

Recibe eventos y lee los que te faltaron