Enviar email

El correo transaccional es el mensaje que se dispara en respuesta a una acción del usuario: confirmación de cuenta, restablecimiento de contraseña, recibo de compra, notificación de entrega. A diferencia del marketing masivo, cada envío es individual y está vinculado a un evento concreto. Usa este canal cuando necesites entregarle un mensaje puntual a una persona específica.

Endpoint

POST https://api.mailerdash.com/v1/mail/send

Respuesta exitosa — 202 Accepted:

{
  "message": "accepted",
  "app": "<key-id>"
}

El 202 indica que el servidor aceptó el mensaje y lo encoló para entrega. No garantiza que el destinatario lo reciba (eso depende del MTA y del servidor remoto), pero sí que el payload pasó validación y está en cola.

Payload

{
  "personalizations": [
    {
      "to": [
        { "email": "destinatario@example.com", "name": "Nombre Opcional" }
      ]
    }
  ],
  "from": {
    "email": "no-reply@tu-dominio.com",
    "name": "Tu Servicio"
  },
  "subject": "Confirma tu cuenta",
  "content": [
    {
      "type": "text/html",
      "value": "<p>Haz clic <a href=\"https://example.com/verify\">aquí</a> para confirmar.</p>"
    },
    {
      "type": "text/plain",
      "value": "Visita https://example.com/verify para confirmar tu cuenta."
    }
  ]
}

Campos

Campo	Tipo	Requerido	Descripción
personalizations	array	sí	Lista de grupos de destinatarios. Al menos un elemento.
personalizations[].to	array	sí	Destinatarios del grupo. Cada item: { email, name? }.
from	object	sí	Remitente. { email, name? }. Debe ser un dominio verificado en tu cuenta.
subject	string	sí	Asunto del correo.
content	array	sí	Cuerpos del mensaje. Al menos uno. Cada item: { type, value }.
content[].type	string	sí	"text/plain" o "text/html". Se recomienda incluir ambos.
content[].value	string	sí	Contenido del cuerpo en el tipo indicado.

Múltiples destinatarios

Para enviar el mismo mensaje a varios destinatarios en un solo request, agrega más objetos al array to dentro de personalizations[0]:

{
  "personalizations": [
    {
      "to": [
        { "email": "ana@example.com", "name": "Ana" },
        { "email": "beto@example.com", "name": "Beto" },
        { "email": "carlos@example.com" }
      ]
    }
  ],
  "from": { "email": "no-reply@tu-dominio.com" },
  "subject": "Actualización de tu cuenta",
  "content": [{ "type": "text/plain", "value": "Tu cuenta ha sido actualizada." }]
}

Cada dirección en to recibe el mensaje de forma independiente.

Canal transaccional

Incluye el header X-Md-Channel: trans en todos tus requests. Aunque el canal transaccional es el comportamiento por defecto, declararlo explícitamente es buena práctica: deja clara la intención y facilita el debugging si el routing del MTA cambia en el futuro.

-H "X-Md-Channel: trans"

Validación de destinatarios

Antes de encolar cualquier mensaje, MailerDash valida cada dirección de destinatario en tres capas:

1. Sintaxis — la dirección debe tener formato RFC válido.
2. Dominios desechables — se rechaza una lista de más de 5,000 dominios de email temporal (mailinator, guerrillamail, etc.).
3. Lookup MX — se verifica que el dominio tenga registros MX activos (resultado en caché por 24 horas).

Si alguna dirección falla cualquiera de las tres capas, el request completo es rechazado con 400 Bad Request. Valida tus listas antes de enviar a volúmenes grandes.

Idempotencia

Si incluyes el header Idempotency-Key con un UUID único por intento, el servidor deduplica los reintentos automáticamente:

-H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000"

• Dentro de la ventana de 24 horas, un segundo request con la misma key devuelve exactamente la misma respuesta sin volver a encolar el mensaje.
• Si reutilizas la misma Idempotency-Key con un payload diferente, recibirás 422 Unprocessable Entity.

Usa idempotencia en cualquier lógica de retry para evitar duplicados.

Ejemplo completo

curl -X POST https://api.mailerdash.com/v1/mail/send \
  -H "Authorization: Bearer $MAILERDASH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Md-Channel: trans" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "personalizations": [
      {
        "to": [
          { "email": "cliente@example.com", "name": "Cliente Ejemplo" }
        ]
      }
    ],
    "from": {
      "email": "no-reply@tu-dominio.com",
      "name": "Tu Servicio"
    },
    "subject": "Confirma tu cuenta en Tu Servicio",
    "content": [
      {
        "type": "text/html",
        "value": "<p>Hola <strong>Cliente Ejemplo</strong>,</p><p>Haz clic <a href=\"https://tu-dominio.com/verify?token=abc123\">aquí</a> para confirmar tu cuenta.</p><p>El enlace expira en 24 horas.</p>"
      },
      {
        "type": "text/plain",
        "value": "Hola Cliente Ejemplo,\n\nVisita el siguiente enlace para confirmar tu cuenta:\nhttps://tu-dominio.com/verify?token=abc123\n\nEl enlace expira en 24 horas."
      }
    ]
  }'

Respuesta esperada:

{
  "message": "accepted",
  "app": "<key-id>"
}

Tu token solo se muestra una vez

Al crear una API key, el token completo se muestra una única vez. Después, el sistema solo guarda un hash y no es posible recuperarlo. Si lo pierdes, debes rotarlo desde el dashboard: la key anterior se invalida y recibirás un token nuevo.

Referencia

Para el esquema completo de request/response, códigos de error y parámetros adicionales, consulta la referencia de API transaccional.