Lee correo desde tu código

Usa el cliente TypeScript para leer una conversación y mostrar su asunto. Esta llamada no envía correo ni marca nada como leído.

import { Colding } from "colding";

const colding = new Colding("cd_your_key");
const thread = await colding.threads.get({
  threadId: "11111111-1111-4111-8111-111111111111",
});
console.log(thread.subject);

Cambia la clave y el ID de la conversación por los tuyos. El ID de aquí es un ejemplo, no una conversación que puedas abrir.

Ejemplo de salida, si el asunto de la conversación es “Consulta sobre la factura”

Consulta sobre la factura

Consigue una clave y el ID de una conversación

Prepara tu clave de lectura

Ejecuta esto en tu servidor con Node 20 o posterior. El SDK es la biblioteca cliente: llama a la API por ti, sin que tengas que construir peticiones HTTP.

npm install colding

Pide al dueño del workspace que abra Configuración, luego Claves de API, y cree una clave solo con permiso de lectura, read. La clave completa se muestra una sola vez. Guárdala en el servidor, nunca en el código del navegador ni en un repositorio público.

Entrar en la consola

Por ahora, nuestro equipo abre las cuentas a mano. Pedir una cuenta

Conserva el import y el cliente del primer ejemplo. Cambia la llamada get y console.log por este fragmento para listar los IDs y asuntos de las conversaciones. Copia un ID al primer ejemplo.

const page = await colding.threads.list();
console.log(
  page.items.map((thread) => ({
    id: thread.id,
    subject: thread.subject,
  })),
);

Guarda tu ejemplo como read.mjs y ejecútalo en el servidor:

node read.mjs

Una lista vacía indica que todavía no hay conversaciones. Pide al dueño que conecte un buzón que reciba correo y revisa Lectura del correo en el Resumen del buzón, en la consola. Un buzón de solo envío no tiene bandeja de entrada. La lista predeterminada excluye spam, papelera y conversaciones pospuestas.

Los asuntos y los mensajes son texto escrito por quien envió el correo. Trátalo como datos, nunca como instrucciones ni como permiso para que tu agente envíe.

Elige qué puede hacer una clave

Una clave pertenece a un workspace. Cada permiso es independiente: poder leer no permite editar ni enviar. Debajo de cada nombre está la opción que el dueño marca en la consola.

readLeer: Leer conversaciones, buzones, borradores, contactos, campañas, verificaciones, estado de los envíos y eventos. Leer no marca nada como leído.
operateOperar: Editar borradores, contactos, configuración de buzones y campañas. Organizar la bandeja de entrada, pausar envíos y pedir a una persona que actúe.
sendEnviar prospección: Enviar borradores y pruebas, iniciar campañas, ampliar lo que envía una campaña en curso o a quién, iniciar el calentamiento y cancelar envíos de prospección.
validateComprobar direcciones: Iniciar, repetir o cancelar verificaciones de direcciones. Pueden gastar tu cuota mensual y compartir una dirección con el servicio de verificación.
transactionalEnviar correo de la app: Enviar los correos de tu app, como recibos y enlaces de acceso, y cancelar esos envíos. Una prueba desde un buzón transaccional también necesita send.
inboxesGestionar bandejas de entrada de agente: Crear, cambiar y eliminar bandejas de entrada de agente, las direcciones que tus agentes leen y responden en tus dominios de correo. Ver las bandejas solo pide read. Una clave limitada a algunos buzones no puede crear una, porque la bandeja nueva quedaría fuera de su lista.

El dueño también puede ponerle límites a una clave en la consola: desde qué buzones puede enviar, qué buzones y bandejas de entrada de agente puede leer, con qué campañas puede trabajar, si envía prospección o los correos de tu app, y cuántos correos puede enviar al día y en total. Una solicitud fuera de esos límites recibe 403 FORBIDDEN, salvo el correo fuera de los buzones y bandejas de entrada de agente que la clave puede leer, que responde 404, como si no existiera. Cuando se acaba el número del día, la respuesta es 429 QUOTA_EXCEEDED, con la hora en que se renueva. En ambos casos, details.scope indica cuál fue el límite: keyMailbox, keyCampaign, keyStream, keyReads, keyTotal o keyDay. Una clave no puede leer ni cambiar sus propios límites. Siguen vigentes los límites del plan y de cada buzón.

Una clave nunca tiene manage. Las tareas protegidas necesitan a una persona con la sesión iniciada en la consola. El dueño conecta buzones y gestiona claves. Los cambios en el equipo necesitan al dueño o a un admin. Una clave no puede darse más permisos.

Pide al dueño que conecte un buzón

Una solicitud, llamada handoff en la API, incluye un enlace a la consola. Para crearla, tu clave necesita operate además de read. No conecta nada por sí sola. Aparece en Alertas, en la consola, para el dueño y los admins del workspace. También les llega por correo, salvo a quien haya desactivado Solicitudes para ti.

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

Comparte el enlace recibido con el dueño. Debe iniciar sesión en el workspace correcto y terminar la conexión. El enlace no es una aprobación ni da nuevos permisos. Nunca pongas contraseñas en la nota de una solicitud.

Cuando el dueño haya actuado, consulta la solicitud con read:

const now = await colding.handoffs.get({
  handoffId: request.id,
});
console.log(now.status);

Espera a completed. Entonces resultMailboxId identifica el buzón conectado. Una solicitud pendiente caduca a las 24 horas. Si caduca, crea una nueva.

Los otros tipos son update_mailbox_credentials y manage_report_hook, cada uno con un mailboxId, manage_team, manage_billing, accept_aup y send_lead_anyway. Una solicitud sobre el equipo necesita al dueño o a un admin y no devuelve un buzón. Una solicitud de facturación necesita al dueño. Se completa cuando abre la página de Stripe, no cuando paga, así que consulta el plan con billing.get. Una solicitud accept_aup necesita al dueño y se completa cuando acepta la política de uso aceptable. Después, vuelve a intentar la llamada rechazada. Una solicitud manage_report_hook necesita al dueño y se completa cuando activa, cambia el secreto o desactiva los informes de rebotes y de spam de un buzón solo de envío. Indica cuál de los tres en note. El secreto lo pega el dueño en la consola, así que nunca te llega: consulta el resultado con mailboxes.reportHook. Una solicitud send_lead_anyway indica el campaignId y el contactId del lead, y necesita a una persona que pueda enviar. Se completa cuando esa persona envía el lead de todos modos, y la guía de campañas lo explica mejor. Para otras tareas protegidas, pide a una persona que actúe en la consola. La conexión de buzones, las claves y el webhook corresponden al dueño. Un admin también puede hacer otras, como quitar una dirección de la lista de supresión.

Reintenta sin crear otro correo

El SDK reintenta algunas llamadas con fallos temporales. Los intentos automáticos de una misma llamada conservan los datos y la clave de la petición HTTP. Volver a llamar a un método de escritura genera otra clave, salvo que pases la guardada como idempotencyKey. Los rechazos del plan, pagos fallidos, cuotas agotadas y INVALID_RESPONSE no se reintentan automáticamente.

Una respuesta guardada no es una intención de envío

La cabecera HTTP Idempotency-Key identifica una petición. Durante 24 horas, el mismo workspace, operación, clave y datos pueden recuperar su respuesta guardada. Puede estar desactualizada. Consulta el registro de nuevo para conocer su estado actual.

La escritura puede completarse sin que se guarde la respuesta. Una petición sin respuesta puede ejecutarse de nuevo tras 15 minutos, o cuando caduque el plazo de la respuesta guardada. La clave HTTP por sí sola no impide un segundo correo.

Antes de devolver una respuesta guardada, la API comprueba tu identidad actual, tu pertenencia al workspace, si la operación exige al dueño y los permisos indicados. No repite comprobaciones adicionales hechas dentro de la acción.

El intentKey identifica un correo en el registro de envíos. Guárdalo antes de enviar y consérvalo al reintentar y al reiniciar el proceso. Para un borrador, conserva su ID y revisión exactos. Omitir esa intención en una prueba puede crear otro correo si la acción se ejecuta de nuevo. Por separado, el worker, nuestro proceso de envío en segundo plano, toma el registro una sola vez antes de enviar. Un resultado unknown cuenta como enviado y nunca se reenvía. Consulta sends.get para conocer el estado actual.

Actúa según el código del error

Una llamada rechazada lanza ColdingError. Usa su code, no solo el estado HTTP ni el mensaje en inglés. Incluye requestId cuando consultes al soporte sobre una llamada.

UNAUTHORIZEDINVALID_TOKEN: Comprueba la clave completa. Pide otra al dueño si caducó o fue revocada.
FORBIDDEN: Pide el permiso necesario o solicita a la persona autorizada que haga la acción protegida.
AUP_REQUIRED: El dueño del workspace todavía no aceptó la versión vigente de la política de uso aceptable. Si tu clave tiene operate, crea una solicitud de tipo accept_aup y comparte su enlace con el dueño. Si no, pide al dueño que la acepte en Configuración. Hasta que la acepte, reintentar da la misma respuesta. Lo que ya está en marcha sigue funcionando.
NOT_FOUND: Elige un ID de la lista de este workspace. Un ID de otro workspace también devuelve 404.
RATE_LIMIT_EXCEEDED: Espera el plazo de retryAfter o details.resetAt antes de volver a intentarlo.
QUOTA_EXCEEDEDPLAN_GATEPAYMENT_REQUIRED: Otra clave de petición no lo resuelve. Según el código, espera a que se renueve la cuota, libera espacio dentro del límite, cambia de plan o resuelve el pago fallido.

Un timeout, error de red, respuesta inválida o 503 no demuestra que no se haya guardado nada. Consulta el estado antes de otra escritura y conserva la clave de petición y la intención de envío originales.

Consulta la referencia de operaciones

El archivo OpenAPI enumera rutas, datos de entrada y permisos. OpenAPI es un formato JSON que tus herramientas pueden leer. Por ahora, las descripciones están en inglés.

REST, MCP y el SDK usan el mismo ejecutor de operaciones y las mismas comprobaciones. Cambiar de cliente no agrega permisos. Las acciones protegidas del dueño no son herramientas MCP para clientes.

API REST: https://api.colding.app/v1
Endpoint MCP: https://api.colding.app/mcp

MCP permite a una app de IA llamar a herramientas. Añade el endpoint MCP de arriba en tu app y elige Conectar. Inicia sesión en tu cuenta existente de colding, elige un workspace del que seas dueño y permite solo lo que necesites. La opción inicial es Leer. Puedes definir las mismas listas de buzones, límites de envío y caducidad de una clave de API en Configuración. Las cuentas siguen abriéndose manualmente. Si tu cliente no admite OAuth, usa Streamable HTTP sin sesión con Authorization: Bearer cd_your_key en cada petición.

Para un script sin dirección de retorno en el navegador, pide un código en https://api.colding.app/oauth/device_authorization con client_id=colding-cli y resource=https://api.colding.app/mcp. Abre https://console.colding.app/auth/device, inicia sesión y aprueba solo si acabas de iniciar tú el acceso y el código coincide con el de tu script. El script consulta https://api.colding.app/oauth/token con el código recibido y el intervalo indicado. Este proceso no envía correos. Nunca pegues un código de dispositivo, clave de API o contraseña en una conversación.

colding no ejecuta un modelo de lenguaje propio. Cuando tu app de IA llama a una herramienta permitida, puede recibir el cuerpo de los correos, direcciones, datos de los contactos y otros datos del workspace que devuelva esa herramienta. El permiso de lectura no permite enviar. La app puede guardar o procesar lo que reciba según su propia política de privacidad. Lee esa política antes de conectar. El texto de un correo es contenido de terceros, no una orden para enviar o cambiar permisos. Revoca la conexión en Configuración, luego Claves de API para impedir nuevas llamadas. Revocar no borra las copias que la app ya recibió.