La API de Linkeia E-Transactional te permite enviar correos desde tu propia aplicación con una petición HTTPS. Sirve para cualquier lenguaje que pueda hacer peticiones HTTPS. La documentación completa también está dentro de la plataforma, en API Docs.
Lo que necesitas
- Un dominio verificado y activo para E-Transactional.
- Una clave de API, que creas en Claves de API. Empieza con
lk_live_.
Enviar un correo
Envía una petición POST a https://api.linkeiaemail.com/v1/send con tu clave en el encabezado Authorization y el mensaje en JSON:
curl https://api.linkeiaemail.com/v1/send \
-H "Authorization: Bearer lk_live_..." \
-H "Content-Type: application/json" \
-d '{
"from": "Mi Tienda <avisos@mitienda.com>",
"to": "cliente@ejemplo.com",
"subject": "Tu pedido #1024 fue enviado",
"html": "<p>Hola, tu pedido ya va en camino.</p>",
"text": "Hola, tu pedido ya va en camino.",
"tags": { "tipo": "envio", "pedido": "1024" }
}'
Respuesta (HTTP 202): el mensaje quedó en cola y sale en segundos. La respuesta trae el ID del mensaje para seguirlo en el registro:
{ "id": "msg_4f1c0a9b2e7d6c5b4a3f2e1d0c", "status": "queued" }
Campos del mensaje
Los campos con * son obligatorios.
| Campo | Descripción |
|---|---|
from * | «Nombre <dirección>» o {"email", "name"}. La dirección debe ser de un dominio verificado de tu servicio. |
to *, cc, bcc | Una dirección o una lista. Hasta 50 destinatarios en total; cada uno cuenta como un envío. |
subject * | Hasta 255 caracteres. |
html, text | Al menos uno de los dos; hasta 2 MB juntos. Envía ambos para la mejor entrega. |
reply_to | Una dirección o una lista (hasta 5). |
headers | Hasta 10 encabezados: X-*, List-Unsubscribe, List-Unsubscribe-Post, In-Reply-To y References. |
tags | Hasta 10 etiquetas {"nombre": "valor"} para encontrar el mensaje en el registro. |
attachments | Hasta 10 archivos [{"filename", "content" en base64, "content_type"}], 7 MB en total. No se aceptan ejecutables. |
Varios mensajes en una llamada
Con POST https://api.linkeiaemail.com/v1/batch envías hasta 100 mensajes distintos dentro de "messages". Cada uno se valida por separado: la respuesta (HTTP 207) trae un resultado por mensaje, en el mismo orden.
{ "messages": [ { "from": "...", "to": "...", "subject": "...", "html": "..." }, ... ] }
{ "data": [ { "id": "msg_...", "status": "queued" }, { "error": "invalid_to", "message": "..." } ] }
Consultar un mensaje
Con GET https://api.linkeiaemail.com/v1/messages/{id} (con tu clave en Authorization) obtienes el estado actual y los avisos de entrega (entregado, rebote, queja) de un mensaje que todavía está en el registro.
Estados: queued (en cola), sent (enviado), delivered (entregado), bounced (rebotó), complained (queja), failed (no enviado), suppressed (todos los destinatarios estaban suprimidos).
Reintentos sin duplicados
Si tu sistema reintenta una petición, envía el encabezado Idempotency-Key con un valor único por mensaje (por ejemplo, el número de pedido). Si ya recibimos esa clave, respondemos con el mismo mensaje en lugar de enviarlo otra vez. Admite hasta 100 letras, números y los signos _ . : -.
-H "Idempotency-Key: pedido-1024-envio"
Reglas
- Las direcciones que rebotaron, se quejaron o bloqueaste se omiten y no cuentan; la respuesta las lista en
"suppressed". Una baja de tus campañas no bloquea los correos transaccionales. - Úsalo solo para mensajes que el destinatario espera por una acción suya o una relación contigo. Para boletines y promociones usa E-Marketing.
Errores
Cuando algo falla, la respuesta trae {"error": código, "message": texto}.
| HTTP | error | Qué pasó |
|---|---|---|
| 401 | invalid_key | La clave no existe o fue revocada. |
| 422 | foreign_domain, domain_not_verified, domain_not_ready | El remitente no es de un dominio tuyo verificado y activo. |
| 422 | invalid_*, missing_*, too_many_recipients… | Un campo falta o no es válido; el mensaje explica cuál. |
| 423 | service_suspended | Tu servicio está suspendido. |
| 423 | plan_suspended | Tu plan de E-Transactional está suspendido. Revisa tus facturas en el Panel Clientes de Linkeia. |
| 429 | quota_exceeded | Llegaste al límite de envíos del mes de tu plan. |
| 5xx | internal, sending_unavailable | Un problema nuestro: reintenta en unos minutos con el mismo Idempotency-Key. |
Si recibes domain_not_ready, tu dominio se está activando para E-Transactional: intenta de nuevo en unos minutos.
