Ir al contenido
MailerDash Docs v0.15.4

Enviar un correo

POST
/v1/mail/send
 
curl --request POST \
  --url https://api.mailerdash.com/v1/mail/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "send_at": "2026-08-15T09:00:00Z", "personalizations": [ { "to": [ { "email": "recipient@example.com", "name": "Recipient Name" } ], "cc": [ { "email": "cc@example.com", "name": "CC Name" } ], "bcc": [ { "email": "bcc@example.com", "name": "BCC Name" } ], "subject": "Asunto específico de este destinatario", "headers": { "additionalProperty": "example" } } ], "from": { "email": "no-reply@example-domain.com", "name": "Service Name" }, "subject": "Email subject", "content": [ { "type": "text/plain", "value": "Hello world" } ], "reply_to": { "email": "reply@example-domain.com", "name": "Reply Name" }, "headers": { "additionalProperty": "example" }, "attachments": [ { "content": "JVBERi0xLjQgZmFjdHVyYSBkZW1v", "url": "https://archivos.example.com/facturas/123.pdf", "filename": "invoice-123.pdf", "type": "application/pdf", "content_id": "logo@inv" } ] }'

Envía un correo usando un payload tipo SendGrid. Requiere API key en el header Authorization.

Authorizations

Sección titulada «Authorizations »

Parameters

Sección titulada « Parameters »

Header Parameters

Sección titulada «Header Parameters »
X-Xilo-Test
string

Modo sandbox. Se activa con true, 1, yes u on (sin distinguir mayusculas); cualquier otro valor envia normalmente. Valida la peticion COMPLETA (auth, dominio, formato, destinatarios, supresiones, reputacion, limite de destinatarios) y se detiene justo antes de cobrar la cuota y entregar el mensaje: no sale ningun correo, no se consume cuota y no cuenta para las estadisticas. La respuesta trae sandbox: true y un message_id con prefijo sandbox-. Solo un “si” explicito lo activa: X-Xilo-Test: false envia de verdad, para que un header vestigial no apague los envios en produccion sin que nadie lo note. Las peticiones en sandbox ignoran Idempotency-Key en los dos sentidos: no guardan su respuesta (probar con una clave y despues mandar de verdad con la misma devolveria la respuesta de la prueba y ningun correo) ni leen la de un envio real.

Request Body required

Sección titulada «Request Body required »
Media type application/json
object
send_at

Programa el envío para esa fecha (ISO 8601, hasta 90 días). Omitir para enviar de inmediato. Devuelve 202 con el id del envío programado en lugar de enviarlo. Los permisos se re-evalúan al disparar: si entre el agendado y la fecha vence la gracia del dominio o se suspende la cuenta, el envío se descarta. Programar no reserva cuota. Solo admite UNA personalización — para varios destinatarios, usar una campaña.

string format: date-time
Example 
2026-08-15T09:00:00Z
personalizations
required
Array<object>
>= 1 items <= 1000 items
object
to
required
Array<object>
>= 1 items
object
email
required
string format: email
Example 
recipient@example.com
name
string
Example 
Recipient Name
cc

Copia (CC). Misma validación, supresión y cobro de cuota que to.

Array<object>
object
email
required
string format: email
Example 
cc@example.com
name
string
Example 
CC Name
bcc

Copia oculta (BCC). Misma validación, supresión y cobro de cuota que to.

Array<object>
object
email
required
string format: email
Example 
bcc@example.com
name
string
Example 
BCC Name
subject

Override del subject para esta personalización. Si falta, se usa el subject de nivel mensaje.

string
>= 1 characters
Example 
Asunto específico de este destinatario
headers

Headers personalizados para esta personalización. X-Xilo-Channel se ignora (el canal transaccional no se puede sobrescribir).

object
key
additional properties
string
from
required
object
email
required
string format: email
Example 
no-reply@example-domain.com
name
string
Example 
Service Name
subject
required
string
>= 1 characters
Example 
Email subject
content
required
Array<object>
>= 1 items
object
type
required
string
Allowed values: text/plain text/html
Example 
text/plain
value
required
string
Example 
Hello world
reply_to
object
email
required
string format: email
Example 
reply@example-domain.com
name
string
Example 
Reply Name
headers

Headers personalizados a nivel mensaje. X-Xilo-Channel se ignora — el canal transaccional no se puede sobrescribir. Los headers por-personalización tienen precedencia sobre estos.

object
key
additional properties
string
attachments

Archivos adjuntos codificados en base64 (p.ej. facturas PDF, imágenes inline). Límites por defecto: 25MB por adjunto y 25MB en total (env MAX_ATTACHMENT_MB / MAX_TOTAL_ATTACHMENTS_MB), 413 al excederlos. El body JSON de este endpoint está topado por MAX_SEND_JSON_MB (35MB por defecto), que acomoda los 25MB de adjuntos una vez inflados por base64 (~33% → ~34MB). Si el escaneo antivirus está activo en el servidor, un adjunto infectado devuelve 422 con code virus_detected, nombrando el archivo y la firma detectada.

Array<object>
One of:
object
content
required

Contenido del archivo codificado en base64. Alternativa a url: hay que mandar uno de los dos, y mandar ambos es un 400 — no adivinamos cuál gana.

string
>= 1 characters
Example 
JVBERi0xLjQgZmFjdHVyYSBkZW1v
url

Alternativa a content: MailerDash descarga el archivo desde esta URL al recibir el envío. Evita inflar el payload ~33% con base64. HTTPS obligatorio; no se siguen redirects (un presigned de S3/GCS no redirige, pero un acortador sí, y ahí falla con un error que lo dice); rige el mismo tope por adjunto; y si la descarga falla, el envío completo devuelve 422 y no sale — un correo sin su adjunto no es el correo. La descarga ocurre en línea con tu request, así que su latencia la esperas tú, con un presupuesto compartido de 20s para todos los adjuntos del envío.

string format: uri
Example 
https://archivos.example.com/facturas/123.pdf
filename
string
>= 1 characters
Example 
invoice-123.pdf
type

MIME type del adjunto (Content-Type).

string
Example 
application/pdf
content_id

CID para adjuntos inline: referenciar como cid:<content_id> dentro del HTML.

string
Example 
logo@inv

Responses

Sección titulada « Responses »

202

Sección titulada «202 »

Accepted – message queued for delivery

Media type application/json
object
message
string
app
string
request_id
string
sandbox
boolean
items
Array<object>
object
personalization_index
integer
status
string
Allowed values: queued failed skipped suppressed rejected
message_id

En sandbox lleva prefijo sandbox-, para que se note que no corresponde a ningun correo si termina guardado.

string
sandbox
boolean
error
string
Example 
{
  "message": "accepted",
  "app": "example-app",
  "sandbox": true,
  "items": [
    {
      "status": "queued"
    }
  ]
}

400

Sección titulada «400 »

Invalid JSON or request body

Media type application/json
object
message
string
Example 
{
  "message": "Invalid JSON body"
}

401

Sección titulada «401 »

Missing or invalid API key

403

Sección titulada «403 »

From domain not authorized

500

Sección titulada «500 »

Internal server error