Un sistema externo envía un correo a un contacto a través del CRM: queda registrado en la actividad del contacto y lleva un píxel que cuenta cuántas veces lo abrió. Envía mensajes reales, por eso nace apagada y su permiso se da de forma explícita.
Permisos#
| Permiso | Para qué sirve | Tipo |
|---|---|---|
correos:enviar | Enviar correos a contactos | escritura |
correos:leer | Consultar cuántas veces se abrió un correo enviado por la API | lectura |
Endpoints#
POST /correos/enviar#
Envía un correo al contacto. El correo sale por la conexión SMTP de notificaciones del sistema, lleva el píxel de lectura y queda en la actividad del contacto (asunto, contenido y lecturas). El HTML se limpia (sin scripts, iframes ni manejadores de eventos). Devuelve un «id» para consultar después cuántas veces se abrió.
Permiso: correos:enviar · escritura
Cuerpo (JSON)#
| Campo | Descripción |
|---|---|
destinatario | obligatorio: el correo del destinatario (o {"email": "…", "nombre": "…"}). Debe ser el correo de un contacto del CRM. |
asunto | obligatorio, hasta 300 caracteres |
cuerpo_html | obligatorio: el contenido del correo en HTML (hasta 500 KB) |
contacto_id | opcional: id del contacto, si ya 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 (si no, responde 404 contacto_no_encontrado) |
sin_contacto | opcional: true para solo enviar el correo, sin buscar ni crear contactos, sin píxel y sin dejar actividad (para códigos de verificación y avisos a quien aún no es contacto) |
{
"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>"
}curl -X POST "https://TU_SUBDOMINIO.connecto.lat/api/v1/correos/enviar" \
-H "Authorization: Bearer cnx_TU_LLAVE" \
-H "Content-Type: application/json" \
-d '{"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>"}'const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/correos/enviar", {
method: "POST",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"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>"
})
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/correos/enviar");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(array (
'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>',
)),
]);
$datos = json_decode(curl_exec($ch), true);GET /correos/consultar#
Cuántas veces se abrió un correo enviado por la API: cantidad de lecturas, primera y última y el detalle de las más recientes. Solo ve correos enviados por la API.
Permiso: correos:leer · lectura
Parámetros de la consulta#
| Parámetro | Descripción |
|---|---|
id | el «id» que devolvió /correos/enviar |
curl "https://TU_SUBDOMINIO.connecto.lat/api/v1/correos/consultar?id=valor" \
-H "Authorization: Bearer cnx_TU_LLAVE"const respuesta = await fetch("https://TU_SUBDOMINIO.connecto.lat/api/v1/correos/consultar?id=valor", {
method: "GET",
headers: { "Authorization": "Bearer " + process.env.CONNECTO_API_KEY }
});
const datos = await respuesta.json();$ch = curl_init("https://TU_SUBDOMINIO.connecto.lat/api/v1/correos/consultar?id=valor");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY")],
]);
$datos = json_decode(curl_exec($ch), true);Respuesta#
enviar: {"datos": {"enviado": true, "id": 57, "contacto_id": 12, "contacto_creado": false, "destinatario": "…", "con_pixel": true}}. consultar: {"datos": {"id", "destinatario", "asunto", "enviado_at", "aperturas": 2, "primera_apertura_at", "ultima_apertura_at", "lecturas": [{"at"}]}}. Errores: 404 contacto_no_encontrado, 422 dato_invalido / correo_no_pertenece, 502 envio_fallido (no hay SMTP configurado o el servidor lo rechazó), 503 api_deshabilitada.