Apartado 15 de 15 · Apps y canales
Conectar un buzón de correo
Conecta un buzón de correo a la bandeja de Chatendo por IMAP y SMTP con contraseña de aplicación: las rutas, los motivos de fallo y cómo contestar por la API.
En esta página (6)
El correo es un canal más de la bandeja: lo que llega a un buzón entra como conversaciones en la misma bandeja que WhatsApp, Instagram o Messenger, y lo que se contesta sale por el servidor de salida (SMTP) del propio buzón, desde su dirección y colgando del mismo hilo. Se conecta con la dirección y una contraseña —una contraseña de aplicación, en los proveedores que la exigen—, sin instalar nada. Trae ya puestos los servidores de Gmail, Yahoo, iCloud, Zoho, IONOS, OVH, Hostinger y GoDaddy, y sirve para el correo de cualquier dominio que ofrezca IMAP y SMTP. Microsoft 365, Outlook.com y Hotmail no llevan contraseña, como se cuenta aquí abajo.
Los buzones de Microsoft (Microsoft 365, Outlook.com, Hotmail y Live) se conectan con el inicio de sesión de Microsoft, sin contraseña. discover responde supported: true, auth_method: "oauth_microsoft" y microsoft_account (personal o work); el resto de buzones, auth_method: "password" y microsoft_account: null. POST /channels/email/oauth/microsoft/start (con email) devuelve la authorize_url, que se abre en el navegador de la persona; a la vuelta, GET /channels/email/oauth/microsoft/pending/{pending} dice qué se autorizó, sin tokens, y POST /channels/email/test y POST /channels/email se llaman con oauth_pending en lugar de imap y smtp. En una cuenta de empresa, el administrador de Microsoft 365 aprueba la aplicación una vez, y el buzón necesita IMAP y SMTP autenticado activos.
Si la empresa no deja ni eso, queda Power Automate (POST /channels/email/power-automate, en §15.1): el canal sale con email.auth_method: "power_automate". Contesta dentro del hilo de Outlook, con adjuntos, y la copia de lo enviado ya queda en Outlook, así que no hay «Traer Enviados» (sync_sent: true da 422).
Chatendo lee el buzón por IMAP cada minuto, y solo los correos que lleguen a partir de la conexión: no importa el histórico. Los boletines, las listas de correo y los remitentes de sistema sin Reply-To no se convierten en conversaciones (cuentan en sync.ignored_total).
Conectar un buzón lo hace una persona, desde el panel (Canales → Conectar correo). Las rutas que lo conectan y lo mantienen (§15.1) piden el permiso de token channels:manage («Gestionar canales») y, además, que el rol de quien creó el token tenga la clave canales.gestionar (§3). El panel no ofrece channels:manage al crear un token (§2), a propósito: conectar un buzón entrega a Chatendo una contraseña. Con un token de Desarrolladores → Tokens de API esas rutas contestan 403 y no hacen nada:
{"message": "Insufficient token scope.", "code": "TOKEN_SCOPE_DENIED", "required": ["channels:manage"]}Lo que un token de integración sí hace con un buzón ya conectado: leerlo (channels:read), leer sus conversaciones y mensajes (conversations:read), contestar (messages:send) y recibir los avisos de siempre (§5). Eso es §15.4 y §15.5. Las rutas de conectar (§15.1 a §15.3) se cuentan igual porque son las del panel, las que usaría un token acuñado en el servidor (§2) y las que explican lo que ves en el canal.
Los campos de las respuestas de este apartado son los que manda Chatendo, vistos en una prueba con un servidor de correo propio; los valores (direcciones, servidores, números, fechas) son de ejemplo.
15.1 · Las rutas
| Ruta | Para qué |
|---|---|
POST /channels |
Paso 1. De la dirección (email) a los servidores propuestos. Responde siempre 200, aunque sea una suposición (source: "guess", confident: false): nunca 404 por un dominio que no conoce. supported: false quiere decir que ese buzón no se puede conectar. Hasta 20 por minuto |
POST /channels |
Paso 2. Prueba IMAP y SMTP por separado y no guarda nada. Responde 200 con el resultado de cada uno (ok es «los dos en verde»); si IMAP falla por un motivo permanente, SMTP se prueba igual, para verlo todo junto. Con channel_id prueba un buzón ya conectado reutilizando su contraseña guardada. Hasta 10 por minuto, y 12 por hora y buzón: 429 EMAIL_TEST_RATE_LIMIT |
POST /channels |
Paso 3. Conectar. Prueba IMAP y SMTP otra vez y, si cualquiera falla, 422 EMAIL_CONNECTION_FAILED y no se guarda nada. Si pasan, crea el canal —activo y con la IA apagada— y responde 201. Lo que falte de smtp (servidor, usuario, contraseña) sale de imap o del servidor propuesto. 409 EMAIL_ADDRESS_TAKEN si ese buzón ya está conectado; 422 EMAIL_CHANNEL_LIMIT si la cuenta ha llegado a su máximo de buzones (10 de serie). Hasta 10 por minuto |
PATCH /channels |
Editar el buzón: name, from_name, signature, sync_sent, max_per_hour, save_sent_copy, is_active y la conexión (imap, smtp). Solo cambia lo que mandas. La dirección no se cambia (422: otra dirección es otro buzón). Cambiar la conexión la prueba antes de guardar, y si cambias el servidor o el usuario de un bloque tienes que mandar también su password (422 con el error en imap.password o smtp.password): la guardada no se reutiliza. Hasta 30 por minuto |
POST /channels |
Sincronizar ahora: una lectura inmediata, sin esperar a la vuelta del minuto ni a la espera por fallos. 202 {"data":{"queued":true}}; 409 EMAIL_CHANNEL_INACTIVE si el buzón está desactivado. Hasta 6 por minuto |
POST /channels |
Microsoft 365 de empresa por Power Automate, cuando la empresa no deja IMAP ni la aplicación de Microsoft: Chatendo lee el buzón con un flujo «leer correos» y contesta con un flujo «enviar correo» (email, read_flow y send_flow, cada uno con su url de Power Platform y su key, que viaja en la cabecera X-Chatendo-Key). Antes de guardar lee un correo por el flujo de lectura: si falla, 422 EMAIL_CONNECTION_FAILED y no se guarda nada. Las dos direcciones y claves se guardan cifradas y no vuelven nunca. Si el buzón ya está conectado: 409 EMAIL_ADDRESS_TAKEN. Hasta 10 por minuto. Se lee cada 3 minutos (por el tope diario de llamadas de Power Automate); «sincronizar ahora» lee al momento |
GET · PUT /channels |
La firma del buzón, con formato y logo. Piden channels:manage |
GET /channels · GET /channels |
El canal, con su bloque email (§15.4). Basta channels:read |
GET /channels |
La salud del buzón. En un correo no abre ninguna conexión: lee el estado de la última lectura. ok: true si va bien o se acaba de conectar; si no, error.code es EMAIL_ (por ejemplo EMAIL_LOGIN_RECHAZADO) o EMAIL_DISCONNECTED si está desactivado. Para ir a mirar de verdad, «Sincronizar ahora». Basta channels:read |
PATCH /channels · DELETE /channels |
Los de siempre: el nombre, activar o desactivar y el modo de IA, y borrar. Borrar un buzón borra también sus conversaciones y mensajes (los contactos se quedan, y tu correo de siempre no se toca); si tiene oportunidades que conservar o demasiado historial, no toca nada y responde 409 (CHANNEL_HAS_BUSINESS_RECORDS o CHANNEL_TOO_LARGE_TO_DELETE): desactívalo con is_active: false. POST /channels rechaza platform: "email": un buzón se crea solo con POST /channels |
Los topes por minuto son por persona del token y por ruta: probar no gasta el tope de sincronizar. Pasarse da 429 con Retry-After.
15.2 · Conectar un buzón, paso a paso
1 · De la dirección a los servidores.
curl -X POST https://TU-DOMINIO/api/v1/channels/email/discover \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"email":"tu-correo@gmail.com"}'{"data": {"email": "tu-correo@gmail.com", "domain": "gmail.com",
"provider": "gmail", "provider_name": "Gmail", "source": "preset", "confident": true,
"supported": true, "unsupported_reason": null,
"needs_app_password": true, "app_password_url": "https://myaccount.google.com/apppasswords",
"imap": {"host": "imap.gmail.com", "port": 993, "security": "ssl",
"username": "tu-correo@gmail.com", "verify_cert": true},
"smtp": {"host": "smtp.gmail.com", "port": 465, "security": "ssl",
"username": "tu-correo@gmail.com", "verify_cert": true}}}source dice de dónde sale la propuesta: preset (un proveedor conocido), mx (por el MX del dominio), ispdb (la base de configuraciones de Thunderbird) o guess (una suposición: mail.<dominio>, con SSL/TLS en 993 y 465, y confident: false: comprueba esos datos antes de seguir). Con needs_app_password: true (Gmail, Yahoo, iCloud, Zoho) la contraseña normal no vale: hay que crear una contraseña de aplicación en app_password_url.
2 · Probar, sin guardar nada.
curl -X POST https://TU-DOMINIO/api/v1/channels/email/test \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"email":"ventas@mi-tienda.example",
"imap":{"host":"imap.mi-tienda.example","port":993,"security":"ssl",
"username":"ventas@mi-tienda.example","password":"LA-CONTRASEÑA"},
"smtp":{"host":"smtp.mi-tienda.example","port":465,"security":"ssl"}}'{"data": {"ok": true,
"imap": {"ok": true, "mailbox": "INBOX", "messages": 1286, "sent_folder": "Sent"},
"smtp": {"ok": true}}}Si un paso falla, dice por qué (los motivos, en §15.3). Aquí, una contraseña mal escrita:
{"data": {"ok": false,
"imap": {"ok": false,
"error": {"reason": "login_rechazado",
"message": "El servidor no acepta el usuario o la contraseña. Revisa que el usuario sea la dirección completa y que la contraseña esté bien escrita.",
"hint": null, "permanent": true}},
"smtp": {"ok": true}}}3 · Conectar. Lleva lo mismo que la prueba y, si quieres, el nombre del canal, el del remitente y la firma:
curl -X POST https://TU-DOMINIO/api/v1/channels/email \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"email":"ventas@mi-tienda.example", "name":"Correo de ventas",
"from_name":"Tienda Ejemplo", "signature":"Tienda Ejemplo · mi-tienda.example",
"imap":{"host":"imap.mi-tienda.example","port":993,"security":"ssl",
"username":"ventas@mi-tienda.example","password":"LA-CONTRASEÑA"},
"smtp":{"host":"smtp.mi-tienda.example","port":465,"security":"ssl"}}'Responde 201 con el canal (se omiten los campos de Meta, que en un buzón van a null):
{"data": {
"id": 12, "platform": "email", "name": "Correo de ventas", "is_active": true, "ai_mode": "off",
"phone_number_id": null, "waba_id": null,
"email": {
"address": "ventas@mi-tienda.example", "provider": "generic", "provider_name": null,
"from_name": "Tienda Ejemplo", "signature": "Tienda Ejemplo · mi-tienda.example",
"sync_sent": true, "save_sent_copy": null, "max_per_hour": 60,
"imap": {"host": "imap.mi-tienda.example", "port": 993, "security": "ssl",
"username": "ventas@mi-tienda.example", "verify_cert": true},
"smtp": {"host": "smtp.mi-tienda.example", "port": 465, "security": "ssl",
"username": "ventas@mi-tienda.example", "verify_cert": true},
"has_password": true, "has_smtp_password": false,
"sync": {"status": "ok", "last_success_at": "2026-10-19T09:12:31Z",
"last_attempt_at": "2026-10-19T09:12:30Z", "next_attempt_at": "2026-10-19T09:13:25Z",
"failures": 0, "received_total": 0, "ignored_total": 0, "sent_folder": null, "error": null}}}}La primera lectura fija desde dónde se lee —solo lo que llegue a partir de ahora—; si esa primera lectura falla, el canal queda creado y Chatendo lo reintenta solo. El canal nace activo y con la IA apagada (ai_mode: "off"): la IA se enciende aparte, en Chatbot e IA → Agente IA.
4 · Mantenerlo.
# Cambiar el nombre del remitente y el tope de envíos por hora (no toca la conexión)
curl -X PATCH https://TU-DOMINIO/api/v1/channels/12/email \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"from_name":"Tienda Ejemplo","max_per_hour":40}'
# Leer el buzón ya, sin esperar a la vuelta del minuto
curl -X POST https://TU-DOMINIO/api/v1/channels/12/email/sync \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json"
# Dejar de leerlo sin perder sus conversaciones
curl -X PATCH https://TU-DOMINIO/api/v1/channels/12/email \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-d '{"is_active":false}'Volver a activar un buzón (is_active: true) empieza sin los fallos de antes. Una password que no mandas es «la que había», pero solo mientras no cambies el servidor ni el usuario de ese bloque.
15.3 · Cuando algo falla
Un paso que falla trae error: {reason, message, hint, permanent}. message y hint llegan en español y en lenguaje de persona; tu código decide por reason. permanent: true es «no se arregla esperando, revisa los datos»; false, «Chatendo lo reintenta solo». Si lo que falla es conectar o cambiar la conexión, la respuesta es 422 EMAIL_CONNECTION_FAILED con esos mismos campos y step (imap, smtp o host), y no se guarda nada.
reason |
Qué pasó | permanent |
|---|---|---|
host_no_permitido |
El servidor no es de Internet (una dirección interna, localhost…): Chatendo solo abre conexiones a nombres cuyas IP sean todas públicas |
sí |
puerto_no_permitido |
Ese puerto no es de correo: IMAP 143 o 993; SMTP 25, 465, 587 o 2525 | sí |
host_no_resuelve |
El nombre del servidor no existe | no |
sin_conexion |
No se puede conectar con ese servidor y puerto | no |
tiempo_agotado |
El servidor no contesta a tiempo | no |
tls_certificado |
El certificado no vale (autofirmado, caducado, de otro nombre). En un servidor propio se puede mandar verify_cert: false |
sí |
tls_fallo |
No se pudo cifrar la conexión en ese puerto: suele ser el puerto o la seguridad (ssl / starttls) |
sí |
seguridad_no_permitida |
Sin cifrar no se admite: ssl o starttls |
sí |
login_rechazado |
El servidor no acepta el usuario o la contraseña (el usuario suele ser la dirección completa) | sí |
contrasena_de_aplicacion |
El proveedor no acepta la contraseña normal de la cuenta: hay que crear una «contraseña de aplicación» | sí |
imap_desactivado |
El buzón tiene apagado el acceso IMAP en su proveedor | sí |
carpeta_no_encontrada |
No encuentra la carpeta del correo en ese servidor | sí |
smtp_rechazado |
El servidor de salida no aceptó el mensaje, o no deja iniciar sesión en ese puerto | no |
destinatario_rechazado |
El servidor de salida rechazó la dirección de destino | sí |
limite_del_proveedor |
El proveedor ha limitado los envíos por ahora: se reintenta más tarde | no |
desconocido |
Otra cosa: el message la cuenta |
no |
El estado del buzón es email.sync.status:
connecting— recién conectado, sin una vuelta completa todavía.ok— todo bien.degraded— fallos pasajeros (red, tiempo) que Chatendo reintenta solo, con una espera cada vez mayor.attention— un fallo que no se arregla solo (contraseña rechazada, IMAP apagado) tras tres seguidos: hace falta una persona. Se avisa una vez a quien puede gestionar canales y se reintenta cada hora.disconnected— el canal está desactivado.
sync.error trae el último fallo con los mismos campos de arriba (code es un reason), sync.failures cuántos van seguidos, y next_attempt_at cuándo volverá a mirar.
15.4 · El canal y el mensaje de correo
Un canal de correo es un canal más (platform: "email"), con su bloque email como el de arriba. La contraseña no sale nunca, ni en una respuesta ni en un registro: solo has_password y has_smtp_password (el servidor de salida tiene una contraseña propia guardada; false es «envía con la de lectura», lo normal cuando el usuario es el mismo). sync_sent: true lee también la carpeta «Enviados», para que lo que el equipo escribe desde su programa de correo aparezca en el hilo; save_sent_copy: null deja que lo decida el proveedor (Gmail, Outlook, Yahoo y Zoho guardan la copia solos); max_per_hour es el tope de correos por hora del buzón (60 de serie, hasta 500).
Quien escribe por correo es un contacto sin teléfono: platform: "email", email_id (su dirección, en minúsculas) y email, con phone_e164: null. Su conversación sale en GET /conversations con platform: "email", window_expires_at: null (no hay ventana de 24 h) y outbound.free_form: true, y latest_message.email_subject trae el asunto. Un mensaje de correo (GET /conversations/{id}/messages) lleva, además de lo de siempre, email_subject y un bloque email; los mensajes de las demás plataformas no llevan ninguno de los dos:
{"id": 40231, "conversation_id": 8123, "direction": "in", "sender_type": "contact",
"type": "text", "status": "delivered",
"body": "Hola, ¿me confirmáis el precio del tratamiento y si hay hueco el jueves por la mañana?",
"wamid": "em:12:presupuesto-0001@cliente.example",
"email_subject": "Presupuesto de la limpieza facial",
"email": {"subject": "Presupuesto de la limpieza facial",
"from": {"address": "lucia.ferrer@cliente.example", "name": "Lucía Ferrer"},
"to": [{"address": "ventas@mi-tienda.example", "name": null}], "cc": [],
"quoted": null, "has_quoted": false, "automatic": false,
"attachments_omitted": 0, "too_large": false, "unreadable": false}}bodyes solo lo que se ha escrito ahora, sin el hilo citado y sin el asunto. El hilo anterior, si el cliente lo citó, va enemail.quoted(has_quoteddice si lo hay).wamidde un correo esem:<id del canal>:<Message-ID>: Chatendo no lee dos veces el mismo correo.email.automatic: truees una respuesta automática («fuera de la oficina»): solo se anota en un hilo que ya existe y no abre una conversación nueva.- Un adjunto es un mensaje hijo del correo (
typeimage,audio,videoodocument) y suemailes solo{"attachment_of": 40231, "inline": false}(inline: truees una imagen incrustada, como el logo de una firma).attachments_omittedcuenta los que no se guardaron (logos de firma, o los que pasaban del tope). too_large: truees un correo gigante del que solo se guardó la cabecera y un aviso enbody;unreadable: true, uno que el servidor de correo no dejó traer entero tras varios intentos.- Un correo rebotado queda
status: "failed"conerror.code: "EMAIL_BOUNCED"(másstatuscon el código SMTP,5.1.1…, yrecipient), solo cuando el aviso de rebote cita el correo nuestro y el fallo es definitivo.
15.5 · Leer y contestar
Leer y contestar usan las rutas de siempre (§4.2, §6.2); lo que cambia es lo que el correo admite:
curl -X POST https://TU-DOMINIO/api/v1/conversations/8123/messages \
-H "Authorization: Bearer $TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
-H "Idempotency-Key: respuesta-presupuesto-0001" \
-d '{"type":"text","email_subject":"Re: Presupuesto de la limpieza facial",
"body":"Hola Lucía: la limpieza facial son 45 €. Tenemos hueco el jueves a las 10:30. ¿Te lo reservamos?"}'Responde 201 con el mensaje (status: "sent": el servidor de salida lo aceptó), con su email (from es el buzón y su nombre de remitente; to, el contacto).
- Texto:
type: "text",bodyde hasta 20 000 caracteres (en WhatsApp son 4 096), en texto plano; se le añade la firma del canal.email_subjectes opcional (hasta 300 caracteres, se limpia y se acorta a 200): sin él, el asunto esRe:y el del último correo del cliente. El correo cuelga del hilo (In-Reply-ToyReferences). - Archivos:
POST /conversations/{id}/media-messages: un correo por archivo, concaptioncomo texto de la carta (hasta 20 000). Vale cualquier tipo —un.zipo un.xlsxque WhatsApp rechazaría—, hasta 15 MB y dentro del cupo de almacenamiento de la cuenta, salvo ejecutables y scripts evidentes (los que bloquea Gmail) y archivos vacíos: 422EMAIL_TYPE_UNSUPPORTEDconreasonadjunto_ejecutable,adjunto_vaciooadjunto_demasiado_grande. - Lo que el correo no sabe hacer —plantillas, botones, reacciones, ubicación, productos, y las rutas
cta-linkyappointments/offer, que son de WhatsApp—: 422EMAIL_TYPE_UNSUPPORTED, antes de abrir ninguna conexión. - No hay ventana de 24 h ni plantillas. Lo que escribes por la API sale como de una persona (la del token) y puede salir cuando quieras. La ventana solo frena a las máquinas de Chatendo —la IA, los seguimientos, las campañas y los recordatorios—: contestan únicamente a un correo del cliente de las últimas 24 h que nadie haya contestado, y si no, 422
WINDOW_EXPIRED. - Tope por hora y buzón (
max_per_hour): 429EMAIL_RATE_LIMITconRetry-After,limityretry_after(segundos hasta poder volver a escribir). Es aparte de los 60 envíos por minuto del §8. - Si el servidor de salida rechaza el envío (contraseña caducada, buzón lleno…), el mensaje queda en el hilo como
failed, conerror.code: "EMAIL_SEND_FAILED"(másreason,hintypermanent), y la respuesta es 422EMAIL_CONNECTION_FAILED: quien escribe ve que no salió. - Los envíos llevan la cabecera
Idempotency-Key, como todos (§6.2).
Los avisos (§5) sirven igual. message.received sale por cada correo que entra, con el sobre de siempre: el bloque contact lleva email (la dirección) en vez de teléfono, y conversation lleva channel_id. No trae el asunto: lo lees en GET /conversations/{id}/messages. message.sent sale por cada correo que sale, también por los que el equipo escribe desde su programa de correo (entran por «Enviados»), y message.failed cuando uno rebota. No hay message.delivered ni message.read: el servidor de salida solo dice que aceptó el correo. Y el estado del buzón no avisa a tu sistema: léelo con GET /channels/{id}/healthcheck.
15.6 · Lo que el correo todavía no hace
- El histórico: solo entra lo que llega a partir de la conexión.
- Escribir a una dirección sin conversación: se contesta en el hilo que ya existe.
- Copia (Cc) y «responder a todos»: se contesta al remitente; los
ccde un correo se ven, pero no se escriben. - Ver el correo con su formato: el texto sale en plano, sin el HTML original.
- Un aviso a tu sistema cuando el buzón necesita atención: hoy se lee con
healthcheck. - Que un correo entre al instante: se lee cada minuto; «Sincronizar ahora» lo adelanta.