¿Te resultó útil este artículo?

Enviar correos con la API

Linkeia E-TransactionalLectura de 3 min

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.

CampoDescripción
from *«Nombre <dirección>» o {"email", "name"}. La dirección debe ser de un dominio verificado de tu servicio.
to *, cc, bccUna dirección o una lista. Hasta 50 destinatarios en total; cada uno cuenta como un envío.
subject *Hasta 255 caracteres.
html, textAl menos uno de los dos; hasta 2 MB juntos. Envía ambos para la mejor entrega.
reply_toUna dirección o una lista (hasta 5).
headersHasta 10 encabezados: X-*, List-Unsubscribe, List-Unsubscribe-Post, In-Reply-To y References.
tagsHasta 10 etiquetas {"nombre": "valor"} para encontrar el mensaje en el registro.
attachmentsHasta 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}.

HTTPerrorQué pasó
401invalid_keyLa clave no existe o fue revocada.
422foreign_domain, domain_not_verified, domain_not_readyEl remitente no es de un dominio tuyo verificado y activo.
422invalid_*, missing_*, too_many_recipients…Un campo falta o no es válido; el mensaje explica cuál.
423service_suspendedTu servicio está suspendido.
423plan_suspendedTu plan de E-Transactional está suspendido. Revisa tus facturas en el Panel Clientes de Linkeia.
429quota_exceededLlegaste al límite de envíos del mes de tu plan.
5xxinternal, sending_unavailableUn 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.

¿Te resultó útil este artículo?

Compartir

Artículos relacionados

¿No encontraste lo que buscabas?

Nuestro equipo te ayuda a resolverlo.