Lee tu workspace, el equipo y las alertas

Una clave trabaja en un workspace. Estas llamadas dicen cuál es, quién está en él y qué necesita a una persona. Solo leen, salvo la que marca alertas como leídas. Empieza por el workspace. Esto no cambia nada.

Tu workspace

import { Colding } from "colding";

const colding = new Colding("cd_your_key");
const workspace = await colding.workspace.get();
console.log(workspace.name, workspace.plan);

Cambia la clave por la tuya. Muestra el nombre y el plan del workspace.

Acme Studio free

La respuesta trae también el slug, el locale y el timezone del workspace, y senderPostalAddress, la dirección postal que se imprime bajo cada correo de campaña.

role es el rol de quien creó la clave, tal como está hoy: owner, admin o member.

aup.required es la versión de la política de uso aceptable que pedimos, y aup.version es la que aceptó un dueño, o null. Mientras sean distintas, una llamada que envía correo o llega a otro servidor responde 403 AUP_REQUIRED. Solo un dueño puede aceptarla. Pídelo con un handoff accept_aup.

posture es null mientras nada limite lo que envía el workspace. Cuando algo lo limita, trae el level y, si hay un motivo, un reasonCode o un reason. En restricted, las campañas, los mensajes y el correo transaccional quedan en espera, y el calentamiento sigue. En suspended, no sale nada, ni siquiera el calentamiento. En los dos, la lectura y la recepción de correo siguen. El evento workspace.posture_changed avisa cuando esto cambia.

deletion es null salvo que un dueño haya pedido eliminar el workspace. Entonces trae requestedAt y purgeAt, con 30 días entre uno y otro, y no sale nada hasta que el dueño lo cancele.

Una clave no puede renombrar el workspace, cambiar su zona horaria, su idioma o su dirección postal, aceptar la política, descargar todos sus datos ni pedir su eliminación. Una clave nunca tiene manage, así que una persona lo hace en la consola. Solo un dueño acepta la política, descarga los datos y elimina el workspace.

Equipo

team.get cuenta los lugares que usa el workspace frente a su plan. team.listMembers lista a los miembros, del más reciente al más antiguo.

const team = await colding.team.get();
console.log(team.occupiedSeats, team.seatLimit);

const page = await colding.team.listMembers({ limit: 20 });
for (const member of page.items) console.log(member.email, member.role);

occupiedSeats suma los miembros y las invitaciones pendientes, porque una invitación ocupa un lugar hasta que se acepta, se revoca o vence. seatLimit es el límite del plan, o null cuando el plan no fija ninguno. La respuesta trae también members, pendingInvitations, el plan y el rol de quien creó la clave.

Cada miembro tiene userId, email, name (o null), role y joinedAt. Cualquier clave que pueda leer ve los correos de los miembros. La lista va paginada: devuelve el nextCursor como cursor.

Una clave no puede invitar a alguien, cambiar un rol, quitar a un miembro ni transferir la propiedad. Eso necesita manage, y un dueño o un admin lo hace en Configuración. Solo un dueño invita a un admin o cambia el rol de un admin, y solo un dueño transfiere la propiedad. Para pedir una de esas acciones, abre un handoff manage_team y di qué quieres en note:

const request = await colding.handoffs.create({
  kind: "manage_team",
  note: "Invite [email protected] as a member.",
});
console.log(request.url);

Se completa cuando la persona hace el cambio, y dura 24 horas. Vuelve a leer el equipo para ver el resultado.

El enlace de una invitación es de la persona invitada. Lo abre en la consola, con la sesión iniciada en el correo verificado que nombra la invitación, y la acepta ahí. El SDK no tiene una llamada para eso, porque una clave no puede aceptar una invitación en nombre de nadie. Para agregar a alguien, pide un handoff manage_team.

Alertas

Una alerta avisa de que algo necesita a una persona: un buzón con problemas, una campaña que pausamos, una respuesta, una solicitud. Cada persona tiene sus alertas, y una clave lee las de quien la creó. Este código lista las no leídas y las marca como leídas:

const page = await colding.alerts.list({ unread: true });
console.log(page.unread);
for (const alert of page.items) console.log(alert.kind, alert.createdAt);

const newest = page.items[0];
if (newest) await colding.alerts.markRead({ through: newest.id });

Las alertas llegan de la más nueva a la más antigua. unread en la respuesta cuenta todas las alertas no leídas, no solo las de esta página. Listar no marca ninguna como leída.

kind dice qué pasó, y params trae qué abrir: un buzón, una campaña, una conversación, un borrador, un handoff, un dominio de seguimiento o una importación, por ID.

mailbox_failed

Un buzón dejó de funcionar. params.code dice el motivo.

mailbox_health

La salud de un buzón en el calentamiento empeoró, o una cuarentena o un bloqueo empezó un nuevo período.

campaign_paused

Pausamos una campaña. params.reason dice el motivo. Una pausa hecha por una persona no genera alerta.

reply_received

Una persona respondió a un correo de campaña o a un mensaje enviado desde el workspace. Nunca un mensaje de fuera de la oficina, otra máquina ni una petición de baja.

draft_review

Alguien pidió a una persona que revisara un borrador.

handoff_requested

Un agente pidió a una persona lo que una clave no puede hacer.

domain_grace_ending

Un dominio de envío lleva casi todo su plazo de gracia con los registros SPF o DMARC fallando. Cuando termine, el calentamiento y las campañas dejan de enviar desde los buzones de ese dominio.

mailbox_full

Un buzón de Microsoft 365 está lleno y no envía nada hasta que alguien libere espacio.

relay_gave_up

Un cambio hecho en la bandeja de entrada, como marcar como leído o mover, que el buzón rechazó durante un día. Lo descartamos.

tracking_domain_failing

El dominio de seguimiento del workspace dejó de apuntar a nosotros. El seguimiento queda apagado hasta que vuelva a apuntar.

campaign_checks_held

Los leads nuevos de una campaña en curso esperan, porque las verificaciones de sus direcciones no pueden correr. params.reason dice el motivo.

workspace_posture

Limitamos lo que envía el workspace, o quitamos el límite.

webhook_disabled

Apagamos el webhook del workspace porque sus entregas fallaron durante días.

email_check_run_held

Un lote de verificaciones de dirección que inició una persona o una clave no avanza, y lo que queda está en espera. params.reason dice el motivo. Cada vez que un lote entra en espera sale una alerta, y las verificaciones vuelven solas.

mail_domain_problem

Un dominio de correo que agregaste tiene un problema o está en espera. params.problem es failing (sus registros dejaron de verificarse), grace_ending (el correo enviado desde el dominio se detendrá pronto), mx_moved (su registro MX ya no apunta a nosotros), under_review (los correos de todas las direcciones de remitente del dominio están en espera mientras nuestro equipo los revisa) o review_ended (la espera terminó). params.ground dice por qué empezó la espera y es null en los demás. params.endsAt es el momento en que se detiene el correo enviado desde el dominio, o null.

agent_storage_full

El correo que guardan tus bandejas de entrada de agente llegó al límite de tu plan. El correo enviado a ellas se rechaza hasta que elimines una bandeja o cambie tu plan.

mailbox_address_claimed

Un buzón que conectaste se desconectó porque otro workspace demostró que controla el dominio de la dirección. params.address es la dirección y params.domain es el dominio.

mailbox_under_review

Limitamos un buzón, o quitamos el límite. params.state es held o released (la revisión terminó y ya nada limita el buzón). En held, params.mode dice qué límite es: hold (no sale nada del buzón, y sigue recibiendo salvo que params.receiving sea true: entonces el correo que le envíen vuelve a quien lo envió) o first_contact_brake (una bandeja de entrada de agente todavía responde a quienes tu workspace ya había escrito antes, pero no a contactos nuevos). En una espera, params.ground dice el motivo: spam_reports, phishing_malware, legal_order o other cuando nuestro equipo puso el buzón en espera tras una denuncia sobre él, o complaint_rate, bounce_rate, policy_bounce_rate o policy_abuse_burst cuando demasiados correos del dominio de params.address se marcaron como spam, rebotaron o se rechazaron como spam, así que todas las bandejas de entrada de agente de ese dominio están en espera. En los demás casos, es null. params.caseNumber es el número del caso, para citarlo cuando nos escribas, y params.until es la fecha en que dijimos que lo revisaríamos.

alerts.markRead necesita operate. Pasa through con la alerta más nueva que viste, y marca esa alerta y todas las más antiguas como leídas. Una alerta que llegó después sigue sin leer. O pasa hasta 100 IDs en ids. Los IDs que no son tuyos, o que ya están leídos, se dejan como están. Pasa uno de los dos, no los dos. marked en la respuesta cuenta las alertas que cambiaron.

Una clave que marca una alerta como leída no detiene el correo que la persona recibe sobre ella. Solo lo detiene leerla en la consola.

Las alertas son para personas. Para que tu propio servidor se entere cuando algo pasa, usa eventos.

Lee cómo recibir eventos en tu servidor