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 ejemploorder-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": "..." },namees 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
htmlytext. Consulta la sección «Envío con plantilla»; - variables — valores para los marcadores del tipo
{{name}}. Se sustituyen en la plantilla, enhtml,text,subjectypreviewText; - 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,ccybccen 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
429con el encabezadoRetry-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 encabezadosList-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
suppressedobouncedy un motivo: el correo no se le envía; - el encabezado de respuesta
X-Quota-Remaining— la cuota de correos restante.
Posibles respuestas
| Status | Descripción |
|---|---|
| 202 | Correo aceptado para el envío |
| 400 | Bad Request — formato de solicitud incorrecto; los campos se indican en error.details |
| 401 | Unauthorized — token incorrecto o ausente |
| 402 | Payment Required — la cuota no alcanza para todos los destinatarios del correo |
| 403 | Forbidden — el token no tiene el permiso email.send, o el acceso a la API está desactivado |
| 404 | Not Found — no se encontró la clave de envío, el dominio del remitente o la plantilla |
| 409 | Conflict — 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 |
| 422 | Unprocessable 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 |
| 429 | Too Many Requests — límite de solicitudes excedido |
| 500, 503 | Error 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:
- Send a transactional email — envío de un correo transaccional
- Templates and aliases — plantillas y alias
- Idempotency and quota — idempotencia y cuota
- Email statuses and events — estados y eventos del correo
- Send error codes — códigos de error
- Email webhooks — webhooks de correos
- Migrating to the Email API — migración a la Email API