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.

Puedes leer información detallada sobre la creación de API key en nuestra Base de conocimientos.

Ruta de envío de correo (con HTML listo)

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

En el encabezado «X-Api-Key» es necesario pasar como cadena la clave API para autenticación.

Ejemplo de cuerpo de solicitud

{
   "idempotencyKey": "unique-key-string",
   "mail": {
        "to": {
            "email": "user@example.com",
            "name": "string"
        },
        "from": {
             "email": "user@example.com",
             "name": "string"
        },
        "subject": "string",
        "previewTitle": "string",
        "headers": {
        },
        "cc": "string",
        "bcc": "string",
        "html": "string",
        "text": "string"
   }
}

Descripción de campos

subject* (tema) — contiene el tema o título del correo;
previewTitle — preheader del correo, hasta 255 caracteres;
html*, text — si se pasan tanto la versión de texto como la versión HTML simultáneamente, el cliente de correo del destinatario decidirá qué versión mostrar al usuario según su configuración y capacidades. Por lo general, los clientes de correo muestran en formato HTML si admiten esta función. Nuestro servicio genera automáticamente text similar a html si text no se pasa (o se pasa una cadena vacía);

name (to/from) — nombre del destinatario/remitente del correo;
headers — encabezados del sistema del correo (campo opcional, para usuarios experimentados). https://nodemailer.com/message/custom-headers;
cc y bcc — es la dirección del destinatario de copia y la dirección del destinatario de copia oculta;
- cc (Carbon Copy) — es el campo «copia» o «enviar copia». El destinatario especificado en CC recibirá una copia del mensaje, pero todos los destinatarios podrán ver a quién más se enviaron copias del mensaje;
- bcc (Blind Carbon Copy) — es el campo «copia oculta». Esto puede ser útil si deseas enviar una copia del mensaje a alguien sin revelar su dirección a otros destinatarios.
  Si se especifican destinatarios en cc o bcc, en la respuesta estará presente un campo adicional — additionalRecipients. Contiene información sobre cada uno de esos destinatarios.
attachments — adjunto en el correo (archivo), en formato de matriz de archivos con estructura del tipo:

{ "nombre_archivo.extensión": "cuerpo del archivo codificado en base64"};

idempotencyKey (String) — clave de idempotencia del usuario para prevenir la duplicación de solicitudes.

Envío usando clave de idempotencia

Si dentro de una hora llega una solicitud repetida para enviar un correo con parámetros completamente coincidentes:

From (remitente);
To (destinatario);
Body (cuerpo del correo);
Subject (título);
Attachments (adjuntos).

Entonces:

sin clave de idempotencia la API responde con el código 200 y devuelve el mismo uuid del correo que en la primera solicitud, el reenvío no crea un nuevo correo;
con clave de idempotencia (idempotencyKey, se pasa fuera del bloque mail) los correos se consideran diferentes cuando los valores de la clave difieren y se enviarán nuevamente.

Recomendaciones de uso

Recomendamos encarecidamente pasar siempre tu idempotencyKey único.

El uso de la clave de idempotencia del usuario se considera necesario para una gestión confiable de solicitudes repetidas.

El mecanismo de detección automática de repeticiones sin clave existe solo para compatibilidad hacia atrás y protección básica contra duplicación, pero no garantiza la ausencia de envíos omitidos o adicionales.

Notas

El servicio limita la frecuencia de solicitudes: se permiten no más de 10 solicitudes por segundo desde una dirección IP.
No se puede especificar la codificación, siempre se usa UTF-8;
La solicitud acepta cualquier encabezado del sistema, pero los que establecemos tienen prioridad, a saber: Return-Path, List-Unsubscribe, Errors-To, X-Complaints-To, Precedence, Feedback-ID, X-SenderName-MailID, X-Mailru-Msgtype, X-Postmaster-Msgtype.

Posibles respuestas

Estado	Descripción
`200 OK`	El email fue aceptado para procesamiento
`400 Bad Request`	Error de validación de la solicitud
`401 Unauthorized`	Clave API inválida
`402 Payment Required`	No hay recursos suficientes en el saldo del usuario
`403 Forbidden`	La clave API no está activa
`404 Not Found`	No se encontró un recurso necesario
`422 Unprocessable Entity`	El destinatario no está disponible
`500 Internal Server Error`	Error interno del servidor
`503 Service Unavailable`	El servicio de procesamiento de emails no está disponible temporalmente

200 OK

El email fue aceptado para procesamiento.

Campos de respuesta:

Campo	Tipo	Descripción
`uuid`	`string`	UUID del email enviado
`additionalRecipients`	`array`	Resultados para destinatarios adicionales de `cc` y `bcc`. Cada elemento contiene `uuid` si el destinatario fue aceptado correctamente o `error` si la dirección de email no es válida
`warning`	`string`	Se devuelve si no se envió `idempotencyKey`

400 Bad Request

Mensajes posibles:

Mensaje	Descripción
`Attachments parse failed`	No se pudieron procesar los archivos adjuntos
`Attachments size more than allowed`	El tamaño total de los adjuntos supera el límite permitido
`Attachments type forbidden`	El tipo de archivo adjunto no está permitido
`HTML template is not valid`	La plantilla HTML no es válida para `/send-by-template`

404 Not Found

Mensajes posibles:

Mensaje	Descripción
`ExternalMailApiKey not found`	No se encontró la clave API
`User Domain not found`	No se encontró el dominio del remitente o no está vinculado al usuario
`TemplateMailUser not found by id`	No se encontró la plantilla de email para `/send-by-template`
`MailUuid not found`	No se encontró el UUID del email

422 Unprocessable Entity

Mensajes posibles:

Mensaje	Descripción
`Email receiver unsubscribed from this API key mails`	El destinatario se dio de baja de los emails enviados con esta clave API
`Email receiver complained from this API key mails`	El destinatario marcó como queja emails enviados con esta clave API
`Email receiver doesn't exist`	El email del destinatario no existe
`Email receiver unavailable`	El email del destinatario no está disponible temporalmente
`Template not found by templateId`	No se encontró la plantilla para `/send-by-template`

Ruta de envío de correo con plantilla

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

En el encabezado «X-Api-Key» es necesario pasar como cadena la clave API para autenticación.

Ejemplo de cuerpo de solicitud

{
   "idempotencyKey": "unique-key-string",
   "mail": {
        "to": {
            "email": "user@example.com",
            "name": "string"
        },
        "from": {
             "email": "user@example.com",
             "name": "string"
        },
        "subject": "string",
        "previewTitle": "string",
        "idTemplateMailUser": number,
        "params": {
            "test": "string",
            "test1": "string",
            "test2": "string"
        }
   }
}

Descripción de campos

idTemplateMailUser* — identificador de la plantilla de correo creada en EmailMassivo;
params — 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/external-mails/send-by-template';
$data = array(
   'idempotencyKey' => 'unique-key-string',
   'mail' => array(
       'to' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'from' => array(
           'email' => 'user@example.com',
           'name' => 'string'
       ),
       'subject' => 'string',
       'previewTitle' => 'string',
       'idTemplateMailUser' => number,
       'params' => array(
           'test' => 'string',
           'test1' => 'string',
           'test2' => 'string'
       )
   )
);
$headers = array(
   'Content-Type' => 'application/json',
   'X-Api-Key' => 'YOUR_API_KEY'
);
$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
import json

url = 'https://api.emailmassivo.com/api/v1/external-mails/send-by-template'
data = {
    'idempotencyKey': 'unique-key-string',
    'mail': {
        'to': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'from': {
            'email': 'user@example.com',
            'name': 'string'
        },
        'subject': 'string',
        'previewTitle': 'string',
        'idTemplateMailUser': number,
        'params': {
            'test': 'string',
            'test1': 'string',
            'test2': 'string'
        }
    }
}
headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
}
response = requests.post(url, json=data, headers=headers)

Node.js

const axios = require('axios');

const url = 'https://api.emailmassivo.com/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};

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

JavaScript

const url = 'https://api.emailmassivo.com/api/v1/external-mails/send-by-template';
const data = {
    idempotencyKey: 'unique-key-string',
    mail: {
        to: {
            email: 'user@example.com',
            name: 'string'
        },
        from: {
            email: 'user@example.com',
            name: 'string'
        },
        subject: 'string',
        previewTitle: 'string',
        idTemplateMailUser: number,
        params: {
            test: 'string',
            test1: 'string',
            test2: 'string'
        }
    }
};
const headers = {
    'Content-Type': 'application/json',
    'X-Api-Key': 'YOUR_API_KEY'
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
    .then(response => response.json())
    .then(data => {
        // Procesamiento de respuesta API
    })
    .catch(error => {
        // Procesamiento de error
    });

Si la solicitud devuelve un error: «Clave API incorrecta», reemplaza el código de transmisión de API key por:
$headers = array( 'Content-Type: application/json', 'X-Api-Key: YOUR_API_KEY');