Conecta tu agente
Una app de IA, un script o tu propio código trabaja en un workspace, con una clave que tiene solo los permisos y límites que eligió el dueño del workspace. Cada llamada pasa por las mismas reglas, el mismo registro de envíos y la misma bandeja de entrada de la consola.
Antes de empezar
Necesitas una cuenta en colding abierta por nuestro equipo y un workspace del que seas dueño. Solo el dueño del workspace puede conectar un agente o crear una clave de API.
Las llamadas de lectura funcionan al momento. Las llamadas que envían correo o consultan otro servidor esperan hasta que el dueño del workspace acepte la política de uso aceptable en Configuración. Hasta entonces, esas llamadas responden 403 AUP_REQUIRED.
Cualquier app con MCP
Agrega esta dirección MCP en tu app de IA y elige Conectar:
https://api.colding.app/mcpCuando la app te lo pida, inicia sesión en tu cuenta de colding, elige el workspace del que seas dueño, marca los permisos y pon los límites que quieras. El permiso Leer (read) viene marcado para empezar. La conexión crea una clave en Agentes › Claves de API con lo que elegiste.
Si tu cliente MCP no admite inicio de sesión con OAuth, envía peticiones Streamable HTTP sin sesión a la misma dirección con Authorization: Bearer cd_your_key en cada llamada.
Un script sin navegador
Cuando tu script corre en un servidor o en una terminal sin retorno en el navegador, pide un código de dispositivo en https://api.colding.app/oauth/device_authorization con client_id=colding-cli y resource=https://api.colding.app/mcp.
Tu script muestra un código corto. Abre https://console.colding.app/auth/device en tu navegador, inicia sesión, escribe el código y elige el workspace, los permisos y los límites. Aprueba solo un código que acabes de pedir tú mismo. El script consulta https://api.colding.app/oauth/token con el intervalo indicado hasta que lo apruebes.
Tu propio código
Abre Agentes › Claves de API en la consola y crea una clave solo con los permisos que necesita tu código. La clave cd_ completa se muestra una sola vez. Guárdala en tu servidor, nunca en el código del navegador ni en un repositorio público.
Instala el SDK en TypeScript con Node 20 o posterior, o llama a la API REST en https://api.colding.app/v1 con Authorization: Bearer cd_your_key:
npm install coldingPermisos por tarea
Dale a cada clave solo los permisos que necesita su tarea. A la izquierda está la tarea y, a la derecha, los nombres de los permisos tal como aparecen en la consola, con su código en la API:
- Leer tu bandeja de entrada
- Leer (
read). Lee conversaciones, mensajes, buzones, contactos, campañas, verificaciones, estado de los envíos y eventos sin marcar nada como leído. - Responder a los correos
- Leer y Enviar prospección (
read,send). Marca también Operar (operate) cuando el agente cree o edite borradores antes de enviar. - Lanzar campañas
- Leer, Operar y Enviar prospección (
read,operate,send). Prepara contactos y pasos, inicia campañas y las pausa o finaliza. - Comprobar direcciones
- Leer y Comprobar direcciones (
read,validate). Inicia, repite o cancela verificaciones de direcciones y lee los resultados. - Enviar correo de la app
- Enviar correo de la app (
transactional). Envía recibos, enlaces de acceso y restablecimientos de contraseña desde un buzón que reservas para eso, y cancela envíos pendientes. Marca Leer (read) para seguirlos después. - Conectar buzones y configurar dominios
- Configurar el workspace (
setup). Conecta buzones con sus datos de acceso, cambia esos datos, confirma la dirección de un buzón con el código que le enviamos, agrega o quita dominios de seguimiento y guarda la dirección postal. Con Leer (read) también, puede configurar y gestionar un webhook que ninguna persona haya guardado.
En Agentes › Claves de API, o en la pantalla de autorización OAuth, el dueño también puede limitar una clave a ciertos buzones para leer o enviar, a campañas concretas, solo a prospección o solo al correo de la app, a un tope de envíos al día o en total, y a una fecha de vencimiento.
Pasos que quedan en manos de una persona
Ninguna clave de API puede iniciar sesión con Microsoft o Google, desconectar un buzón, crear o cambiar claves de API, gestionar la facturación, aceptar la política de uso aceptable ni cambiar o eliminar un webhook que una persona haya guardado en la consola. Esos pasos siempre necesitan a una persona con la sesión iniciada.
Cuando un agente llega a un paso que necesita a una persona, una clave con Operar (operate) y Leer (read) puede abrir una solicitud con handoffs.create y pasar el enlace de la consola al dueño o admin.
Cómo detener un agente
Para detener un agente al instante, abre la página Agentes en la consola y pulsa Revocar en su clave, en Agentes › Claves de API. Toda llamada nueva con esa clave se rechaza de inmediato, y cualquier correo suyo que aún no haya empezado a salir se cancela antes de la entrega.
Para frenar el correo sin revocar la clave, baja sus límites de envío en Agentes › Claves de API, pausa un buzón o una campaña, o cancela un envío pendiente con sends.cancel antes de que salga.
Qué no hace colding hoy
colding no le da a tu agente una dirección de correo propia en nuestros servidores, no envía el correo de tu app desde nuestros servidores en ningún plan a la venta, no escribe correos por su cuenta con un modelo de lenguaje integrado ni ofrece un SDK en Python.
En los buzones que conectas, ya puedes adjuntar archivos a borradores, respuestas y correos de tu app. Guarda el archivo con files.create o files.createUpload y pasa su id en fileIds. El envío desde nuestros servidores no admite adjuntos.