La Email API de EmailMassivo permite enviar correos transaccionales, como confirmaciones de pedidos, recuperación de contraseña y notificaciones, con una sola solicitud POST. El envío se realiza mediante la API pública de EmailMassivo: te autenticas con una API key e indicas qué sending key debe usarse para el correo.

Paso 1. Crea una API key

Una API key da acceso a la API pública de EmailMassivo con permisos configurables, también llamados scopes.

  1. En tu cuenta, abre Integrations -> API y crea una API key.
  2. Indica un nombre y activa el permiso external_mail.send para enviar correos transaccionales.
  3. Copia el token, por ejemplo rs_ck_v1_.... Se muestra solo una vez.

Paso 2. Crea una sending key

Una sending key es la entidad de envío que conecta un dominio verificado con la reputación del remitente. Cada correo se envía mediante una sending key concreta, y su ID numérico (key_id) se incluye directamente en la URL de la solicitud.

  1. En tu cuenta, abre Transactional emails y crea una key.
  2. Indica un nombre y selecciona un dominio verificado.
  3. Copia el ID de la key desde su tarjeta, o solicita la lista de keys con GET /api/v1/public/external-mails/keys. Esta solicitud requiere el permiso external_mail.read.

Paso 3. Envía un correo

POST https://api.emailmassivo.com/api/v1/external-mails/send/{key_id}

Pasa el token de la API key en el encabezado Authorization:

Authorization: Bearer rs_ck_v1_...

Ejemplo de cuerpo de solicitud

{
  "idempotencyKey": "order-12345-confirmation",
  "mail": {
    "to": { "email": "user@example.com", "name": "Juan" },
    "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
    "subject": "Confirmación del pedido",
    "html": "<h1>¡Gracias por tu pedido!</h1>"
  }
}

Campos de la solicitud

Campo Tipo Obligatorio Descripción
mail.to.email string sí Dirección del destinatario
mail.to.name string no Nombre del destinatario
mail.from.email string sí Dirección del remitente en el dominio de la sending key
mail.from.name string no Nombre del remitente
mail.subject string <= 255 sí Asunto del correo
mail.html / mail.text string al menos uno Contenido del correo
mail.previewTitle string <= 255 no Texto de preheader
mail.cc, mail.bcc string <= 255 no Destinatarios CC y BCC, separados por comas
mail.headers object no Encabezados personalizados X-*
mail.attachments array <= 20 no Adjuntos en formato { "filename": "base64" }
idempotencyKey string <= 150 no, recomendado Clave de idempotencia

Envío por plantilla

Para enviar un correo usando una plantilla creada en EmailMassivo, usa este endpoint:

POST https://api.emailmassivo.com/api/v1/external-mails/send-by-template/{key_id}

En lugar de html o text, pasa idTemplateMailUser y params dentro de mail.

{
  "idempotencyKey": "order-12345-confirmation",
  "mail": {
    "to": { "email": "user@example.com", "name": "Juan" },
    "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
    "subject": "Confirmación del pedido",
    "idTemplateMailUser": 123,
    "params": {
      "orderNumber": "12345",
      "customerName": "Juan"
    }
  }
}

idTemplateMailUser es el ID de la plantilla de correo. params es un objeto con valores para las variables de la plantilla. Las claves del objeto deben coincidir con las variables usadas en la plantilla.

Idempotencia

Pasa tu propio idempotencyKey en cada solicitud. Esto garantiza que, si la misma solicitud se repite después de un timeout o un error de red, el correo no se envíe dos veces.

Si no envías idempotencyKey, el servidor aplica una protección automática contra duplicados, pero no garantiza que no haya envíos omitidos o adicionales. En este caso, la respuesta puede incluir warning.

Respuestas del servidor

Una respuesta correcta es 200 OK:

{ "uuid": "018e1234-abcd-7000-8000-000000000001" }

Usa el uuid para seguir el estado del correo.

Código Cuándo ocurre
400 Cuerpo de solicitud no válido o problema con adjuntos: tipo prohibido o tamaño excedido
401 Token de API key no válido o revocado
402 Fondos insuficientes o límite de correos del plan agotado
403 La API key no tiene external_mail.send, o la sending key no está disponible o no está activa
404 Sending key o dominio del remitente no encontrado; en envío por plantilla, la plantilla no fue encontrada
422 El destinatario se dio de baja, se quejó o la dirección no está disponible
429 Límite de solicitudes excedido; repite después del tiempo indicado en Retry-After
503 El servicio no está disponible temporalmente; repite más tarde

El cuerpo del error contiene un código legible por máquina y una descripción.

Ejemplos de código

cURL

curl -X POST "https://api.emailmassivo.com/api/v1/external-mails/send/42" \
  -H "Authorization: Bearer $EMAILMASSIVO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "order-12345-confirmation",
    "mail": {
      "to": { "email": "user@example.com", "name": "Juan" },
      "from": { "email": "noreply@yourdomain.com", "name": "MyApp" },
      "subject": "Confirmación del pedido",
      "html": "<h1>¡Gracias por tu pedido!</h1>"
    }
  }'

PHP

$keyId = 42;
$payload = [
    'idempotencyKey' => 'order-12345-confirmation',
    'mail' => [
        'to' => ['email' => 'user@example.com', 'name' => 'Juan'],
        'from' => ['email' => 'noreply@yourdomain.com', 'name' => 'MyApp'],
        'subject' => 'Confirmación del pedido',
        'html' => '<h1>¡Gracias por tu pedido!</h1>',
    ],
];

$ch = curl_init("https://api.emailmassivo.com/api/v1/external-mails/send/{$keyId}");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('EMAILMASSIVO_API_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);
$response = curl_exec($ch);
echo $response;

Python

import os
import requests

key_id = 42
response = requests.post(
    f"https://api.emailmassivo.com/api/v1/external-mails/send/{key_id}",
    headers={"Authorization": f"Bearer {os.environ['EMAILMASSIVO_API_TOKEN']}"},
    json={
        "idempotencyKey": "order-12345-confirmation",
        "mail": {
            "to": {"email": "user@example.com", "name": "Juan"},
            "from": {"email": "noreply@yourdomain.com", "name": "MyApp"},
            "subject": "Confirmación del pedido",
            "html": "<h1>¡Gracias por tu pedido!</h1>",
        },
    },
)
print(response.json())

Node.js

const keyId = 42;

const response = await fetch(`https://api.emailmassivo.com/api/v1/external-mails/send/${keyId}`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EMAILMASSIVO_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    idempotencyKey: 'order-12345-confirmation',
    mail: {
      to: { email: 'user@example.com', name: 'Juan' },
      from: { email: 'noreply@yourdomain.com', name: 'MyApp' },
      subject: 'Confirmación del pedido',
      html: '<h1>¡Gracias por tu pedido!</h1>',
    },
  }),
});

console.log(await response.json());

JavaScript en el navegador

No uses una API key en código de navegador: el token será visible para los visitantes de la página. Envía correos solo desde el servidor. El ejemplo de Node.js anterior puede usarse sin cambios en entornos JavaScript del lado del servidor.

Límites

  • Cuerpo de solicitud: hasta 5 MB.
  • Adjuntos: hasta 15 MB en total, no más de 20 archivos.
  • No se permiten archivos ejecutables, archivos comprimidos ni archivos del sistema como adjuntos.
  • Límite de la API pública: 300 solicitudes por minuto por API key. Revisa los encabezados X-RateLimit-* en la respuesta.
  • Codificación de la solicitud: UTF-8.