Para qué sirve#
Permite que otro sistema (la tienda web, un sistema de facturación, una app) envíe un correo a un contacto a través del CRM. El correo:
- sale por la conexión SMTP de notificaciones del sistema (Configuración → Correo),
- lleva un píxel de lectura que cuenta cuántas veces se abrió,
- queda registrado en la actividad del contacto, con su asunto, su contenido y el contador de lecturas.
Cómo activarla#
- En Configuración → APIs y Webhooks, pulsa Generar API (o edita una credencial): en la tabla de permisos, debajo del nombre de cada API está el interruptor «API habilitada» y enciende «Correos (enviar a un contacto)».
- Al generar la credencial, marca de forma explícita Enviar correos a contactos (
correos:enviar) y, si quieres consultar las lecturas, Consultar cuántas veces se abrió un correo… (correos:leer).
Enviar un correo#
POST https://crm.tuempresa.com/api/v1/correos/enviar
Authorization: Bearer cnx_TU_LLAVE
Content-Type: application/json
{
"destinatario": "[email protected]",
"asunto": "Tu pedido fue recibido",
"cuerpo_html": "<h2>¡Gracias por tu compra!</h2><p>Recibimos tu pedido <b>PED-000123</b>.</p>"
}| Campo | Qué es |
|---|---|
destinatario | Obligatorio. El correo (o {"email": "…", "nombre": "…"}). Debe ser el correo de un contacto del CRM. |
asunto | Obligatorio. Hasta 300 caracteres y sin saltos de línea. |
cuerpo_html | Obligatorio. El contenido en HTML, hasta 500 KB. |
contacto_id | Opcional. El id del contacto, si lo conoces; el correo debe ser uno de los suyos. |
crear_contacto | Opcional. true para crear el contacto si no existe uno con ese correo. Sin esto, un correo desconocido responde 404. |
Respuesta (200):
{ "datos": { "enviado": true, "id": 57, "contacto_id": 12, "contacto_creado": false, "destinatario": "[email protected]", "con_pixel": true } }Guarda el id: sirve para consultar las lecturas.
Qué le pasa al HTML#
Se limpia antes de enviarlo: se quitan los scripts, los iframe, los manejadores de eventos (onclick…) y los enlaces javascript:. Se conservan los estilos, las tablas, las imágenes, los enlaces y el texto. Si el HTML trae </body>, el píxel se coloca justo antes; si no, al final.
Cuántas veces se abrió#
GET https://crm.tuempresa.com/api/v1/correos/consultar?id=57
Authorization: Bearer cnx_TU_LLAVE{ "datos": { "id": 57, "destinatario": "[email protected]", "asunto": "Tu pedido fue recibido", "enviado_at": "2026-10-22T16:20:00-05:00",
"aperturas": 2, "primera_apertura_at": "…", "ultima_apertura_at": "…", "lecturas": [ { "at": "…" }, { "at": "…" } ] } }Solo se pueden consultar los correos enviados por esta API. Las lecturas también se ven en la actividad del contacto (Resumen de su ficha).
Errores#
| HTTP | Código | Cuándo |
|---|---|---|
| 404 | contacto_no_encontrado | No hay un contacto con ese correo (y no se envió crear_contacto). |
| 422 | dato_invalido | Correo, asunto o cuerpo ausentes o inválidos (por ejemplo, saltos de línea en el asunto o más de 500 KB). |
| 422 | correo_no_pertenece | Con contacto_id, el correo no es uno de los del contacto. |
| 502 | envio_fallido | No hay una conexión SMTP configurada o el servidor rechazó el correo. No queda registro en la actividad. |
| 503 | api_deshabilitada | La API está apagada en Configuración → APIs y Webhooks. |
| 403 | sin_permiso | La credencial no tiene marcado el permiso explícito. |
Como cualquier API de Connecto, tiene límite por minuto por credencial y queda registrada en el historial de llamadas.
<!-- Fuente: shared/src/Core/Api/CorreosApi.php, shared/src/Core/Api/Catalogo.php, shared/src/Core/CorreoSeguimiento.php -->