Ir al contenido
Documentación de Connecto
connecto.lat
Guía de usuarioConfiguración general e IA

API: Correos (enviar a un contacto)

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.
Envía mensajes reales, por eso esta API nace apagada y su permiso es explícito: los interruptores «Todas las APIs de lectura / escritura» no la incluyen, aunque la credencial los tenga.

Cómo activarla#

  1. 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)».
  2. 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#

Texto
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>"
}
CampoQué es
destinatarioObligatorio. El correo (o {"email": "…", "nombre": "…"}). Debe ser el correo de un contacto del CRM.
asuntoObligatorio. Hasta 300 caracteres y sin saltos de línea.
cuerpo_htmlObligatorio. El contenido en HTML, hasta 500 KB.
contacto_idOpcional. El id del contacto, si lo conoces; el correo debe ser uno de los suyos.
crear_contactoOpcional. true para crear el contacto si no existe uno con ese correo. Sin esto, un correo desconocido responde 404.

Respuesta (200):

Texto
{ "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ó#

Texto
GET https://crm.tuempresa.com/api/v1/correos/consultar?id=57
Authorization: Bearer cnx_TU_LLAVE
Texto
{ "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).

El conteo depende de que el programa de correo del destinatario cargue las imágenes. Si las bloquea, esa lectura no se cuenta. Varias cargas iguales en pocos segundos (previsualizaciones) cuentan como una sola.

Errores#

HTTPCódigoCuándo
404contacto_no_encontradoNo hay un contacto con ese correo (y no se envió crear_contacto).
422dato_invalidoCorreo, asunto o cuerpo ausentes o inválidos (por ejemplo, saltos de línea en el asunto o más de 500 KB).
422correo_no_perteneceCon contacto_id, el correo no es uno de los del contacto.
502envio_fallidoNo hay una conexión SMTP configurada o el servidor rechazó el correo. No queda registro en la actividad.
503api_deshabilitadaLa API está apagada en Configuración → APIs y Webhooks.
403sin_permisoLa 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 -->

¿Te fue útil esta página?
Última actualización: 14/11/2026