Send email

Transactional email is the message triggered in response to a user action: account confirmation, password reset, purchase receipt, delivery notification. Unlike bulk marketing, each send is individual and tied to a specific event. Use this channel when you need to deliver a targeted message to a specific person.

Endpoint

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

Successful response — 202 Accepted:

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

The 202 indicates that the server accepted the message and queued it for delivery. It does not guarantee that the recipient will receive it (that depends on the MTA and the remote server), but it does mean the payload passed validation and is in the queue.

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."
    }
  ]
}

Fields

Field	Type	Required	Description
personalizations	array	yes	List of recipient groups. At least one element.
personalizations[].to	array	yes	Recipients in the group. Each item: { email, name? }.
from	object	yes	Sender. { email, name? }. Must be a verified domain on your account.
subject	string	yes	Email subject line.
content	array	yes	Message bodies. At least one. Each item: { type, value }.
content[].type	string	yes	"text/plain" or "text/html". Including both is recommended.
content[].value	string	yes	Body content in the specified type.

Multiple recipients

To send the same message to several recipients in a single request, add more objects to the to array inside 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." }]
}

Each address in to receives the message independently.

Transactional channel

Include the X-Md-Channel: trans header in all your requests. Although the transactional channel is the default behavior, declaring it explicitly is good practice: it makes the intent clear and makes debugging easier if the MTA routing changes in the future.

-H "X-Md-Channel: trans"

Recipient validation

Before queuing any message, MailerDash validates each recipient address in three layers:

1. Syntax — the address must have a valid RFC format.
2. Disposable domains — a list of more than 5,000 temporary email domains (mailinator, guerrillamail, etc.) is rejected.
3. MX lookup — it verifies that the domain has active MX records (result cached for 24 hours).

If any address fails any of the three layers, the entire request is rejected with 400 Bad Request. Validate your lists before sending to large volumes.

Idempotency

If you include the Idempotency-Key header with a unique UUID per attempt, the server automatically deduplicates retries:

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

• Within the 24-hour window, a second request with the same key returns exactly the same response without re-queuing the message.
• If you reuse the same Idempotency-Key with a different payload, you will receive 422 Unprocessable Entity.

Use idempotency in any retry logic to avoid duplicates.

Full example

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."
      }
    ]
  }'

Expected response:

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

Your token is only shown once

When you create an API key, the full token is shown only once. After that, the system only stores a hash and it cannot be recovered. If you lose it, you must rotate it from the dashboard: the previous key is invalidated and you will receive a new token.

Reference

For the complete request/response schema, error codes, and additional parameters, see the transactional API reference.