API de correo y webhooks
Además de SMTP, 2mail tiene una API REST: envía un mensaje con una sola llamada HTTPS, consulta después su estado y deja que cada evento —entregado, rebotado, abierto— se empuje automáticamente a su propio sistema mediante un webhook.
Esta página describe qué hace la API y cómo funciona el acceso. La referencia completa, con todos los campos y llamadas de ejemplo, está abierta: puede leerla antes de tener una cuenta. Si trabaja en PHP, el SDK oficial le quita de encima el trabajo con HTTP.
Lo que construye con ella
Enviar desde su aplicación
Un solo POST con remitente, destinatario, asunto y contenido. También puede programar un mensaje para más adelante y decidir mensaje a mensaje si se miden las aperturas. La respuesta incluye ya un id con el que localizar el mensaje más tarde.
Consultar el estado de un mensaje
Con ese id consulta si el mensaje está en cola, se ha enviado o ha fallado, incluido el motivo en caso de error. Así no tiene que rebuscar en archivos de registro cuando un cliente llama por un correo concreto.
Recibir los eventos automáticamente
Registre una URL y 2mail empuja hacia ella cada evento en cuanto se produce: entregado, aplazado, rebotado, rechazado, abierto o fallido. Sin consultas periódicas y sin una cola que tenga que vaciar usted.
Una clave por aplicación
Cada aplicación recibe su propia clave, que puede revocar por separado. Una clave de envío solo puede enviar y consultar el estado de sus propios mensajes, nada más, tampoco otros datos de su cuenta.
Enviar un mensaje
La llamada se ha mantenido pequeña a propósito: una clave en la cabecera Authorization y un cuerpo JSON. La dirección del remitente debe pertenecer a uno de sus propios dominios.
POST https://www.2mail.eu/2mail/api/v1/messages Authorization: Bearer 2m_live_UW_SLEUTEL Content-Type: application/json { "from": "no-reply@sudominio.be", "to": "cliente@ejemplo.be", "subject": "Su pedido ha sido enviado", "html": "<p>Gracias por su pedido.</p>" }
202 Accepted { "id": "4f3c…", "status": "queued" }
Recibe un 202 con un id. Eso significa aceptado, no entregado: la entrega en sí la sigue con una consulta de estado o, mejor, con un webhook.
¿Prefiere no escribir HTTP? El SDK de PHP
composer require jaanbv/2mail-php-api $api = new TwoMail($apiKey); $api->sendMail( 'no-reply@sudominio.be', 'cliente@ejemplo.be', 'Su pedido ha sido enviado', '<p>Gracias por su pedido.</p>' );
Para PHP existe un cliente oficial que cubre todos los endpoints de arriba. Esa misma llamada se convierte en cuatro líneas y no tiene que mantener usted las opciones de curl, la codificación JSON ni el tratamiento de errores.
El SDK separa la dirección del remitente del nombre visible, comprueba por usted las firmas de los webhooks y da a cada código de error su propia excepción, de modo que puede reaccionar al tipo de error y no a un texto que mañana puede estar formulado de otra manera.
Webhooks: la entrega la sigue de forma pasiva
Un webhook es una URL suya a la que llamamos en cuanto ocurre algo con su mensaje. Es más preciso que consultar el estado periódicamente, y detecta un rebote en menos de un minuto en lugar de en la siguiente ronda.
POST https://sudominio.be/webhooks/2mail X-2mail-Event: bounced X-2mail-Signature: t=1755417600,v1=<hmac-sha256> { "event": "bounced", "timestamp": "2026-08-17T10:04:11+02:00", "recipient": "cliente@ejemplo.be", "message_id": "<…>", "detail": "550 5.1.1 unknown", "code": "5.1.1" }
// $secret: eenmalig getoond bij aanmaak $body = file_get_contents('php://input'); parse_str(strtr($_SERVER['HTTP_X_2MAIL_SIGNATURE'], ',', '&'), $p); $ok = hash_equals( hash_hmac('sha256', $p['t'] . '.' . $body, $secret), $p['v1'] );
Cada llamada va firmada
Enviamos una firma en la cabecera X-2mail-Signature, calculada con HMAC-SHA256 sobre la marca de tiempo y el cuerpo en bruto, con una clave que solo conocemos usted y nosotros. Compruebe esa firma antes de fiarse del contenido: sin esa comprobación, cualquiera que conozca su URL puede inventarse eventos. En PHP no tiene que escribirlo usted: el SDK hace la comprobación en una línea, incluida la comprobación de la ventana temporal que impide reutilizar una llamada interceptada.
Las llamadas fallidas se repiten
Si su endpoint no responde con un 2xx, lo intentamos de nuevo con intervalos crecientes: al cabo de un minuto, cinco minutos, media hora, dos horas y seis horas. En el portal ve, intento a intento, el código de respuesta y el mensaje de error, de modo que puede localizar un endpoint que falla sin ponerse en contacto con nosotros.
Qué eventos
Entregado, aplazado, rebotado, rechazado, abierto, aceptado y fallido. Elige por webhook qué tipos quiere recibir, o lo deja vacío para recibirlos todos.
Claves y acceso
Una clave de API se muestra una sola vez y después solo se conserva como hash. Si la pierde, la revoca y crea una nueva: no podemos volver a mostrársela.
Clave de envío
Pertenece a un solo buzón y puede hacer exactamente dos cosas: enviar un mensaje y consultar el estado de sus propios mensajes. Cualquier otro endpoint responde con un 403. Esta es la clave que pone en una tienda online o en una aplicación.
Clave de administración
Para quien quiera crear buzones, dominios y usuarios SMTP de forma programática, por ejemplo un socio que despliega clientes por su cuenta. Esta clave se crea en el portal, no mediante la API.
Las claves de envío las crea y gestiona usted mismo en el portal de clientes, en Ajustes. Ahí ve también cuándo se usó por última vez cada clave.
La documentación completa
Cada endpoint, cada campo y cada código de error están en la referencia interactiva. Ahí también puede probar al momento: pulse Authorize, pegue su clave y ejecute una llamada real.
La especificación es pública e importable en Postman o Insomnia, o se puede usar para generar un cliente. La referencia interactiva también es de acceso libre: solo necesita una clave cuando quiera ejecutar una llamada de verdad.
Manos a la obra
La API va incluida en todos los planes de 2mail; no hay ninguna licencia ni módulo aparte. Si tiene alguna duda sobre una integración o quiere saber si su escenario encaja, háganoslo saber: nos gusta pensarlo con usted antes de que empiece a construir.