Enviar un correo transaccional

Enviar con una plantilla

En vez de { type: "raw", subject, html, text }, el content puede llevar una plantilla ya guardada en Templates, con type: "template":

curl -X POST https://api.e-comms.dev/v1/email \
  -H "Authorization: Bearer ek_live_<tu-clave>" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "bienvenida-plantilla-ana-2026-09-19",
    "to": ["ana@example.com"],
    "from": "hola@tuempresa.com",
    "content": {
      "type": "template",
      "templateId": "01a0ba31-6b2c-7a9f-8c3d-2e5f7a1b9c60",
      "variables": { "firstName": "Ana", "planName": "Pro" }
    }
  }'

const response = await fetch("https://api.e-comms.dev/v1/email", {
  method: "POST",
  headers: {
    Authorization: "Bearer ek_live_<tu-clave>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    idempotencyKey: "bienvenida-plantilla-ana-2026-09-19",
    to: ["ana@example.com"],
    from: "hola@tuempresa.com",
    content: {
      type: "template",
      templateId: "01a0ba31-6b2c-7a9f-8c3d-2e5f7a1b9c60",
      variables: { firstName: "Ana", planName: "Pro" },
    },
  }),
})

const body = await response.json()

import requests

response = requests.post(
    "https://api.e-comms.dev/v1/email",
    headers={"Authorization": "Bearer ek_live_<tu-clave>"},
    json={
        "idempotencyKey": "bienvenida-plantilla-ana-2026-09-19",
        "to": ["ana@example.com"],
        "from": "hola@tuempresa.com",
        "content": {
            "type": "template",
            "templateId": "01a0ba31-6b2c-7a9f-8c3d-2e5f7a1b9c60",
            "variables": {"firstName": "Ana", "planName": "Pro"},
        },
    },
)

body = response.json()

La respuesta tiene la misma forma que la de cualquier otro envío.

De dónde sale el templateId

Cópialo desde la propia plantilla. Abre la plantilla en Templates → editar y usa el botón de copiar junto al id, bajo su nombre, o abre el menú de acciones de su fila en la lista de plantillas y elige Copiar ID. Cualquier rol que pueda ver las plantillas puede copiarlo.

Solo una plantilla activa puede usarse para enviar. Una inactiva responde conflict, el mismo código que una idempotencyKey repetida con otro cuerpo.

Qué responde una variable que falta

Si el documento de la plantilla usa una etiqueta que no está entre las claves de variables, la llamada responde bad_request, con el nombre de la etiqueta en details:

{
  "code": "bad_request",
  "message": "Unknown merge tag key: planName",
  "details": {
    "keys": ["planName"]
  },
  "requestId": "01a0ba31-3fe4-7cc4-a1c6-64bdaaa5d99c"
}

No hay una sustitución parcial ni un valor por defecto silencioso: la plantilla compila entera o no envía nada.

Notas

• from tiene que coincidir exactamente con un remitente, no solo con un dominio: regístralo antes en la configuración de Envío de la app. Un remitente probado con su propio código de un solo uso envía tal cual está escrito; uno cuyo dominio todavía no está autenticado ahí igual envía, conservando la parte local y sustituyendo el dominio, con replyTo llevando la dirección real salvo que la llamada ya haya enviado una.
• Límite de solicitudes: 100 por segundo por clave, en todo /v1. Por encima responde 429 rate_limited, sin encabezado Retry-After y sin ningún encabezado de cuota — el límite no se anuncia por adelantado.
• /v1 no responde ningún encabezado CORS. Esta superficie no es invocable desde un navegador, solo desde un servidor a servidor.
• El cuerpo es estricto: un campo que no está en esta lista responde validation_failed, nunca se ignora en silencio.
• La idempotencyKey es del cuerpo, no un encabezado. La misma clave con el mismo cuerpo devuelve exactamente la respuesta ya resuelta, sin volver a encolar el envío. La misma clave con un cuerpo distinto responde 409 conflict. Dos solicitudes concurrentes con la misma clave: la que pierde la carrera también responde 409, nunca un envío duplicado.

La referencia de errores trae el resto de los códigos que esta superficie puede responder, incluidos los que ninguna ruta declara por sí sola.