API de correo transaccional
Una llamada REST para cada correo que envía su producto
Envíe recibos, restablecimientos de contraseña, alertas y avisos de cuenta mediante POST /v1/transactional/send. MailLand comprueba la solicitud, firma cada mensaje con la clave DKIM de su dominio, lo entrega a sus servidores de correo e informa de lo que ocurrió con él. Los servidores funcionan en Hetzner, en Alemania.
curl -X POST https://api.mail.land/v1/transactional/send \
-H "X-API-Key: ml_pet_..." \
-H "X-Idempotency-Key: order-1042-receipt" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "[email protected]", "name": "Your App" },
"to": [{ "email": "[email protected]", "name": "Jane" }],
"subject": "Your receipt for order 1042",
"htmlContent": "<p>Thanks, Jane. Your payment was received.</p>",
"textContent": "Thanks, Jane. Your payment was received.",
"tags": ["receipt"]
}'Qué ocurre después de llamar a la API
Cuatro etapas, cada una visible para usted en la respuesta, en el registro de mensajes o en un webhook.
Comprobado
La API comprueba el dominio remitente, el alcance y los límites de su clave, y cada destinatario. Las direcciones suprimidas se rechazan y aparecen en rejectedRecipients; si la protección contra errores tipográficos y dominios desechables está activada, esas direcciones también aparecen, con una corrección sugerida en caso de error tipográfico.
En cola
Cada mensaje aceptado se escribe en la base de datos de MailLand antes de que la API responda 202 Accepted y, a continuación, pasa a la cola de entrega. La respuesta incluye el ID del trabajo, un ID de mensaje por destinatario y la hora en que se puso en cola; un envío programado devuelve en su lugar un ID de programación.
Firmado y enviado
Cada destinatario recibe una copia independiente con su propio ID de mensaje y sin Cc visible, firmada con la clave DKIM de su dominio y enviada desde las direcciones IP de envío compartidas de MailLand.
Notificado
Los eventos de entrega, aplazamiento, rebote, fallo y queja llegan a su webhook y al registro de mensajes. Cada evento lleva una versión de estado, para que pueda aplicarlos en el orden correcto.
Lo que le ofrece la API
Cada una de estas funciones es un campo, una cabecera o un endpoint, documentado con ejemplos.
Plantillas almacenadas con variables
Guarde plantillas HTML y de texto en MailLand y rellene los {{placeholders}} para cada destinatario. Si una variable no tiene valor, el mensaje no se envía con el marcador sin sustituir: la API responde 422 e indica lo que falta.
Claves de idempotencia
Incluya una cabecera X-Idempotency-Key en el envío. Un reintento con la misma clave dentro de las 24 horas devuelve la respuesta original y no envía nada, de modo que reintentar tras un tiempo de espera agotado de la red no envía una segunda copia.
Envíos programados
Añada scheduledAt para enviar con hasta 7 días de antelación. Liste, reprograme o cancele un mensaje programado a través de la API antes de que salga.
Adjuntos e imágenes en línea
Adjunte hasta 10 archivos y 10 MiB por mensaje, incluidas imágenes en línea a las que su HTML hace referencia mediante Content-ID.
Etiquetas y cabeceras personalizadas
Etiquete los mensajes para filtrarlos en análisis, registros y webhooks, añada sus propias cabeceras y defina una dirección de respuesta por mensaje.
Comprobación previa
GET /v1/transactional/send/check le indica si su cuenta puede enviar en este momento, con el uso actual del límite de velocidad y la cuota mensual. No comprueba un remitente ni un destinatario concretos.
Claves de sandbox
Una clave de sandbox acepta y registra las solicitudes sin entregarlas, o solo entrega a una lista de direcciones permitidas que usted controla, de modo que el correo de prueba solo llega a las direcciones que usted elige.
Claves con alcance limitado
Limite cada clave a un flujo, a determinados dominios de envío, a una lista de IP permitidas, a límites por minuto, por hora y diarios, y a una fecha de caducidad. Rótela desde el panel o mediante la API.
Sepa qué ocurrió con cada mensaje
Aceptar una solicitud es solo la mitad del trabajo. MailLand le informa de lo que ocurrió después.
Webhooks firmados
Suscríbase a los eventos de entrega, aplazamiento, rebote, fallo y queja. Cada solicitud se firma con HMAC-SHA256 en la cabecera X-MLND-Signature y se reintenta cuando su endpoint falla.
Registro de mensajes
Busque cualquier mensaje por su ID y consulte cada evento de su historial. Los registros se conservan durante 30, 90 o 180 días, según su plan.
Supresión automática
Los rebotes permanentes y las quejas pasan automáticamente a su lista de supresión, y los envíos posteriores a esas direcciones se rechazan antes de salir.
Una v1 que solo crece
La versión 1 de la API solo admite cambios aditivos: pueden aparecer nuevos campos y eventos, pero no se elimina nada y nada cambia de significado. Un cambio incompatible se publica como /v2, anunciado con al menos 180 días de antelación, y /v1 sigue funcionando en paralelo durante 180 días.
HTTPS sin más, en cualquier lenguaje
MailLand aún no tiene SDK. La API es JSON sobre HTTPS con una cabecera X-API-Key, y la documentación, disponible en siete idiomas, muestra cada solicitud en curl, JavaScript, Node.js, Python, PHP, C#, Java y Go.
Alojado en la UE
Los servidores de MailLand funcionan en Hetzner, en Alemania, principalmente en Núremberg, y se conserva una copia de seguridad cifrada en Varsovia, Polonia. Algunos subencargados del tratamiento, como Cloudflare y Stripe, pueden tratar datos limitados fuera de la UE en virtud de las Cláusulas contractuales tipo de la UE. El DPA los enumera uno por uno.
Leer el DPAPreguntas sobre la API de correo transaccional
¿Hay un plan gratuito?
Sí. El plan Free incluye 1.000 correos al mes sin coste, con la misma API REST y el mismo relé SMTP que los planes de pago. No necesita tarjeta de crédito para empezar.
¿Tienen SDK?
Todavía no. La API es JSON sobre HTTPS, por lo que funciona con cualquier cliente HTTP. La documentación incluye ejemplos listos para copiar en curl, JavaScript, Node.js, Python, PHP, C#, Java y Go.
¿Cómo me aseguro de que un reintento no envíe el correo dos veces?
Incluya una cabecera X-Idempotency-Key (o el campo idempotencyKey) con POST /v1/transactional/send o send-batch. Un reintento con la misma clave dentro de las 24 horas devuelve la respuesta original y no envía nada. Estos dos endpoints son los únicos que aceptan una clave.
¿Puede una solicitud ir a muchos destinatarios?
Una solicitud transaccional admite hasta 5 destinatarios, y cada uno recibe una copia independiente. Para envíos masivos, use una clave de marketing con POST /v1/transactional/send-batch, que admite hasta 10.000 destinatarios por solicitud.
¿Qué ocurre cuando un mensaje rebota?
Un rebote permanente o una queja añade la dirección a su lista de supresión y se envía a su webhook como evento. Los envíos posteriores a esa dirección se rechazan y aparecen en rejectedRecipients.
¿Cuáles son los límites de envío?
Cada plan fija un volumen mensual y una velocidad de envío por minuto, que se muestran en la página de precios. Una clave puede tener sus propios límites, más bajos. Si se supera un límite, la API responde 429 con una cabecera Retry-After.
Envíe su primer correo hoy
Cree una cuenta gratuita, verifique su dominio y llame a la API. 1.000 correos al mes son gratuitos.