Saltar al contenido principal

Documentación Email API

Creación de API key​

La creación de API key está disponible en el enlace: https://app.emailmassivo.com/api.

Para enviar correos, la API key necesita el permiso «Envío de correos con Email API» (email.send) del grupo «Correo». Puedes leer información detallada sobre la creación de API key en nuestra Base de conocimientos.

También necesitas un dominio verificado y una clave de envío de ese dominio. No es obligatorio indicar la clave de envío en la solicitud: sin keyId, el correo se envía a través de la clave predeterminada del dominio del remitente.

Importante: los correos de prueba deben enviarse solo a direcciones de correo electrónico existentes, de lo contrario la clave será bloqueada.

Ruta de envío de correo​

POST https://api.emailmassivo.com/api/v1/public/emails

La misma ruta envía tanto correos con HTML o texto listos como correos con plantilla.

Encabezados de la solicitud:

  • Authorization: Bearer TU_TOKEN — el token de la API key;
  • Content-Type: application/json;
  • Idempotency-Key — una etiqueta única del correo en tu sistema, por ejemplo order-12345-confirmation. No es obligatorio, pero te recomendamos enviarlo siempre: consulta la sección «Idempotencia» más abajo.

Ejemplo de cuerpo de solicitud​

{
"data": {
"from": { "email": "noreply@tu-dominio.com", "name": "Mi tienda" },
"to": { "email": "cliente@example.com", "name": "Juan" },
"cc": [{ "email": "manager@tu-dominio.com" }],
"bcc": [{ "email": "archivo@tu-dominio.com" }],
"replyTo": { "email": "soporte@tu-dominio.com" },
"subject": "Tu pedido {{order}} está confirmado",
"previewText": "Gracias por tu pedido",
"html": "<h1>¡Gracias, {{name}}!</h1>",
"text": "¡Gracias, {{name}}!",
"variables": { "name": "Juan", "order": "#12345" },
"headers": { "X-Order-Id": "12345" },
"attachments": [
{ "fileName": "factura.pdf", "content": "JVBERi0xLjQK..." }
],
"keyId": 42
}
}

Descripción de campos​

Todos los campos van dentro del objeto data.

  • from* — el remitente: { "email": "...", "name": "..." }, name es opcional. La dirección debe pertenecer al dominio de la clave de envío, y el dominio debe estar verificado;
  • to* — los destinatarios principales: un objeto { email, name } o un array de objetos;
  • cc y bcc — copia y copia oculta, arrays de objetos { email, name };
    • cc (Carbon Copy) — el destinatario recibe una copia del correo, y todos los destinatarios pueden ver a quién más se envió;
    • bcc (Blind Carbon Copy) — el destinatario recibe una copia, y su dirección no se muestra a los demás destinatarios;
  • replyTo — la dirección para respuestas: un objeto o un array de hasta 5 direcciones;
  • subject* — el asunto del correo, hasta 255 caracteres;
  • previewText — el preheader del correo, hasta 255 caracteres;
  • html, text — las versiones HTML y de texto del correo. Si pasas ambas, el cliente de correo del destinatario decide qué versión mostrar;
  • templateId o templateAlias — una plantilla creada en EmailMassivo, por su identificador o por su alias, en lugar de html y text. Consulta la sección «Envío con plantilla»;
  • variables — valores para los marcadores del tipo {{name}}. Se sustituyen en la plantilla, en html, text, subject y previewText;
  • headers — encabezados propios del correo (campo opcional, para usuarios experimentados). No se pueden pasar encabezados del sistema;
  • attachments — archivos adjuntos al correo: { "fileName": "factura.pdf", "content": "<base64>" };
  • keyId — el identificador de la clave de envío. Si no se pasa, se usa la clave predeterminada del dominio de from.

Importante: El correo necesita contenido: html, text o una plantilla. No se puede combinar una plantilla con html o text.

Idempotencia​

Si necesitas repetir una solicitud — por ejemplo, después de un fallo de red o de un tiempo de espera agotado —, envíala de nuevo con el mismo Idempotency-Key y exactamente el mismo cuerpo:

  • con la misma clave, la API devuelve la respuesta a la primera solicitud, y el correo no se envía por segunda vez. La clave es válida durante 24 horas;
  • sin clave, cada solicitud crea un correo nuevo.

La clave tiene de 1 a 64 caracteres: letras latinas, dígitos y ., _, :, -. Vincúlala a un evento de tu sistema: un valor aleatorio en cada intento no protege contra duplicados.

Notas​

  • Hasta 50 destinatarios en to, cc y bcc en total. Una misma dirección no puede aparecer dos veces entre ellos.
  • Hasta 20 archivos adjuntos, 15 MB en total.
  • La ruta acepta hasta 600 solicitudes por minuto por API key.
  • Hasta 20 correos por segundo desde un mismo dominio remitente. Si se supera cualquiera de los dos límites, la API responde 429 con el encabezado Retry-After: los segundos que hay que esperar.
  • {{unsubscribe_url}} — el enlace para darse de baja; EmailMassivo lo sustituye y añade por sí mismo los encabezados List-Unsubscribe.

Respuesta​

Si el correo se acepta, la API responde con el código 202:

{
"ok": true,
"data": {
"id": "0199b2f4-6c1e-7a3d-9f2b-4e8c1d7a5b60",
"status": "queued",
"createdAt": "2026-09-30T10:15:00.000Z",
"recipients": [
{
"id": "3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c3d9e01",
"email": "cliente@example.com",
"name": "Juan",
"type": "to",
"status": "queued",
"reason": null
}
]
},
"meta": { "requestId": "01JB2W...", "timestamp": "2026-09-30T10:15:00.120Z" }
}
  • data.id — el identificador del correo. Con él puedes consultar el estado de entrega; los webhooks lo envían como emailId;
  • data.recipients — todos los destinatarios del correo, cada uno con su propio identificador y estado. Un destinatario que se dio de baja o cuya dirección se conoce como no entregable aparece con el estado suppressed o bounced y un motivo: el correo no se le envía;
  • el encabezado de respuesta X-Quota-Remaining — la cuota de correos restante.

Posibles respuestas​

StatusDescripción
202Correo aceptado para el envío
400Bad Request — formato de solicitud incorrecto; los campos se indican en error.details
401Unauthorized — token incorrecto o ausente
402Payment Required — la cuota no alcanza para todos los destinatarios del correo
403Forbidden — el token no tiene el permiso email.send, o el acceso a la API está desactivado
404Not Found — no se encontró la clave de envío, el dominio del remitente o la plantilla
409Conflict — el dominio remitente está bloqueado; o una solicitud con este Idempotency-Key todavía se está procesando, o la clave se usó con otro cuerpo
422Unprocessable Entity — por ejemplo, la clave de envío no está activa, from no pertenece al dominio de la clave o ninguno de los destinatarios de to puede recibir el correo
429Too Many Requests — límite de solicitudes excedido
500, 503Error del servidor — repite la solicitud con el mismo Idempotency-Key

Los errores llegan en el formato { "ok": false, "error": { "code", "message", "details" }, "meta" }. Todos los códigos están en la referencia de códigos de error (en inglés).

Envío con plantilla​

Los correos con plantilla se envían por la misma ruta. En lugar de html y text, pasa templateId — el identificador de la plantilla — o templateAlias — su alias, por ejemplo order-confirmation.

Ejemplo de cuerpo de solicitud​

{
"data": {
"from": { "email": "noreply@tu-dominio.com", "name": "Mi tienda" },
"to": { "email": "cliente@example.com", "name": "Juan" },
"subject": "Tu pedido está confirmado",
"previewText": "Gracias por tu pedido",
"templateId": 123,
"variables": {
"test": "string",
"test1": "string",
"test2": "string"
}
}
}

Descripción de campos​

  • templateId* o templateAlias* — el identificador o el alias de la plantilla de correo creada en EmailMassivo. Pasa solo uno de los dos;
  • variables — objeto con variables para sustituir en la plantilla. Las claves del objeto deben coincidir con las variables utilizadas en la plantilla.

Ejemplos de uso de API con plantilla de correo EmailMassivo​

PHP​

$url = 'https://api.emailmassivo.com/api/v1/public/emails';
$data = array(
'data' => array(
'from' => array(
'email' => 'noreply@tu-dominio.com',
'name' => 'Mi tienda'
),
'to' => array(
'email' => 'cliente@example.com',
'name' => 'Juan'
),
'subject' => 'Tu pedido está confirmado',
'templateId' => 123,
'variables' => array(
'test' => 'string',
'test1' => 'string',
'test2' => 'string'
)
)
);
$headers = array(
'Content-Type: application/json',
'Authorization: Bearer TU_TOKEN',
'Idempotency-Key: order-12345-confirmation'
);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

Python​

import requests

url = 'https://api.emailmassivo.com/api/v1/public/emails'
data = {
'data': {
'from': {
'email': 'noreply@tu-dominio.com',
'name': 'Mi tienda'
},
'to': {
'email': 'cliente@example.com',
'name': 'Juan'
},
'subject': 'Tu pedido está confirmado',
'templateId': 123,
'variables': {
'test': 'string',
'test1': 'string',
'test2': 'string'
}
}
}
headers = {
'Authorization': 'Bearer TU_TOKEN',
'Idempotency-Key': 'order-12345-confirmation'
}
response = requests.post(url, json=data, headers=headers)
email_id = response.json()['data']['id']

Node.js​

const axios = require('axios');

const url = 'https://api.emailmassivo.com/api/v1/public/emails';
const data = {
data: {
from: {
email: 'noreply@tu-dominio.com',
name: 'Mi tienda'
},
to: {
email: 'cliente@example.com',
name: 'Juan'
},
subject: 'Tu pedido está confirmado',
templateId: 123,
variables: {
test: 'string',
test1: 'string',
test2: 'string'
}
}
};
const headers = {
'Content-Type': 'application/json',
'Authorization': 'Bearer TU_TOKEN',
'Idempotency-Key': 'order-12345-confirmation'
};

axios.post(url, data, { headers })
.then(response => {
// Procesamiento de la respuesta de la API: response.data.data.id
})
.catch(error => {
// Procesamiento del error: error.response.data.error.code
});

JavaScript (navegador)​

No uses la API key en el código del navegador: el token quedaría visible para cualquier visitante de la página. Envía correos solo desde tu servidor; el ejemplo de Node.js sirve también para otros entornos JavaScript de servidor.

Migración a la Email API​

Si tu integración usa los métodos de envío anteriores, siguen funcionando. Cómo pasar a la nueva ruta se explica en la guía Migrating to the Email API (en inglés).

Documentación para desarrolladores​

La documentación para desarrolladores está disponible en inglés: