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.
Consulta sobre la factura
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 coldingPide al dueño del workspace que abra Agentes › 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.
Conecta una app de IA, un script o tu propio código
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.mjsUna 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. setupConfigurar el workspace- Agregar o quitar dominios de seguimiento, guardar la dirección postal al pie de los correos de campaña, conectar buzones con sus datos de acceso, cambiar esos datos y confirmar la dirección de un buzón con el código que le enviamos. Si también marcas Leer, la clave podrá configurar el webhook, salvo que una persona ya lo haya hecho. La clave conecta cada buzón en nombre del dueño. El dueño elige este permiso en Agentes › Claves de API o al conectar un cliente MCP. Abarca todo el workspace:
mailboxIds,readMailboxIdsycampaignIdsdeben sernull. Los límites de envío y la fecha de vencimiento siguen vigentes. La clave pierde el permiso de configuración si quien la creó deja de ser el dueño. Para enviar correo, marca también un permiso de envío.
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. Solo el dueño conecta un buzón con el inicio de sesión de Microsoft o Google, desconecta 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
Con setup, tu clave puede agregar o quitar dominios de seguimiento, guardar la dirección postal, conectar buzones con sus datos de acceso, cambiar esos datos y confirmar sus direcciones sin una solicitud. Con read también, puede configurar el webhook, salvo que una persona ya lo haya hecho. El inicio de sesión con Microsoft o Google y la desconexión de un buzón todavía necesitan al dueño. Las claves, la facturación y la aceptación de la política siempre quedan en manos de una persona.
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. Sin setup, solo el dueño, con la sesión iniciada, conecta un buzón o cambia sus datos de acceso. Solo el dueño desconecta un buzón, inicia sesión con Microsoft o Google y gestiona las claves. Sin setup y read, solo el dueño guarda el webhook. Un admin también puede hacer otras, como quitar una dirección de la lista de supresión.
Si tu clave no puede confirmar una dirección por sí sola, usa confirm_mailbox_address con mailboxId. La solicitud termina cuando la dirección queda confirmada: con un código, con un inicio de sesión de Microsoft o Google, con un dominio de correo verificado o por nuestro equipo. Si la dirección ya está confirmada, la llamada responde 409. Usa manage_tracking_domains para pedir a un dueño o admin que agregue o quite un dominio de seguimiento, manage_webhook para pedir al dueño que guarde o elimine el webhook y manage_settings para pedir a un dueño o admin que guarde la dirección postal. Indica lo que necesitas en note. Cada enlace abre los controles que ya existen. Una solicitud de seguimiento termina cuando una persona con la sesión iniciada agrega o quita un dominio de seguimiento. Las de webhook y de dirección postal solo terminan con el guardado correspondiente desde su enlace. Cambiar solo la zona horaria no completa una solicitud de dirección postal.
Si no puedes editar el DNS, usa add_dns_records con exactamente uno entre mailboxId y trackingDomainId. El primero pide los registros del dominio de envío de un buzón que conectaste: SPF y DMARC, o solo DMARC en uno solo de envío. El segundo pide el CNAME de un dominio de seguimiento. Lee primero los records del destino. Publica solo una fila marcada como not_verified o wrong que tenga un valor no nulo. Si el DNS no respondió, comprueba de nuevo antes de cambiar algo. Solo una lectura nueva de nuestro DNS que confirme los registros completa la solicitud, en la misma transacción que guarda la lectura. Decir que los registros se agregaron no la completa. Varias solicitudes pendientes para ese mismo destino pueden terminar juntas. Una clave con una lista de lectura no puede pedir algo sobre un dominio de seguimiento, que pertenece a todo el workspace. Una solicitud no da nuevos permisos ni habilita funciones de nuestros servidores.
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 tipoaccept_aupy 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
retryAfterodetails.resetAtantes 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 Agentes › Claves de API. 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ó.