REST API

Envíe correos electrónicos transaccionales mediante POST /v1/transactional/send. Esta es la forma principal de enviar correo electrónico a través de MailLand.

AutenticaciónCopiar enlace de la sección

Incluya su clave API en el encabezado X-API-Key:

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

Las credenciales deben tener el canal Api habilitado y ser credenciales de producto Sending.

Enviar un correo electrónico únicoCopiar enlace de la sección

POST https://api.mail.land/v1/transactional/send

curl -X POST https://api.mail.land/v1/transactional/send \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Hello from MailLand",
    "htmlContent": "<p>Your email content here</p>"
  }'

Cuerpo de la solicitudCopiar enlace de la sección

{
  "from": {
    "email": "[email protected]",
    "name": "Your App"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "Jane Doe",
      "variables": {
        "firstName": "Jane",
        "orderNumber": "ORD-12345"
      }
    }
  ],
  "subject": "Your order #{{orderNumber}} has shipped",
  "htmlContent": "<h1>Hi {{firstName}},</h1><p>Your order #{{orderNumber}} is on its way.</p>",
  "textContent": "Hi {{firstName}}, Your order #{{orderNumber}} is on its way.",
  "replyTo": "[email protected]",
  "tags": ["order-shipped", "transactional"],
  "customHeaders": {
    "X-Entity-Ref-ID": "order-12345"
  },
  "tracking": {
    "opens": true,
    "clicks": true
  },
  "priority": "High",
  "idempotencyKey": "order-12345-shipped-v1"
}

Referencia de camposCopiar enlace de la sección

Archivos adjuntosCopiar enlace de la sección

Cada archivo adjunto requiere tres campos:

{
  "attachments": [
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "content": "JVBERi0xLjQKJ...",
      "inline": false
    },
    {
      "fileName": "logo.png",
      "contentType": "image/png",
      "content": "iVBORw0KGgoAAAA...",
      "contentId": "company-logo",
      "inline": true
    }
  ]
}

RespuestaCopiar enlace de la sección

Estado: 202 Accepted

{
  "success": true,
  "jobId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [],
  "queuedAt": "2026-02-17T10:30:00Z",
  "isSandboxed": false
}

Destinatarios rechazadosCopiar enlace de la sección

Los destinatarios pueden ser rechazados por varias razones:

{
  "success": true,
  "jobId": "...",
  "acceptedRecipients": ["[email protected]"],
  "rejectedRecipients": [
    {
      "email": "[email protected]",
      "reason": "Suppressed"
    },
    {
      "email": "[email protected]",
      "reason": "domain_typo",
      "suggestion": "[email protected]"
    }
  ]
}

Razones comunes de rechazo:

• Suppressed: la dirección está en la lista de supresión (rebotes/quejas previas)
• disposable_domain: proveedor de correo desechable detectado
• domain_typo: probable error tipográfico en el dominio (incluye campo suggestion)

Verificación previaCopiar enlace de la sección

Verifique su capacidad de envío antes de realizar la solicitud real:

GET https://api.mail.land/v1/transactional/send/check?recipientCount=1

curl https://api.mail.land/v1/transactional/send/check?recipientCount=1 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

{
  "canSend": true,
  "rateLimitStatus": {
    "currentSecond": 2,
    "limitPerSecond": 50,
    "currentHour": 450,
    "limitPerHour": 5000,
    "currentDay": 8200,
    "limitPerDay": 50000
  },
  "monthlyUsed": 125000,
  "monthlyLimit": 500000
}

Si canSend es false, el campo reason explica el motivo (límite de velocidad, cuota, estado de la cuenta, etc.).

IdempotenciaCopiar enlace de la sección

Reintentar un envío tras un tiempo de espera de red no debe entregar el correo dos veces. Con una clave de idempotencia, el reintento reproduce la respuesta original en lugar de volver a enviar.

Envía la clave como cabecera (recomendado):

X-Idempotency-Key: order-12345-shipped-v1

O usa el campo idempotencyKey del cuerpo. Ambos se aceptan, y puedes enviar ambos solo si los valores son idénticos.

ReglasCopiar enlace de la sección

• Alcance. X-Idempotency-Key solo se acepta en POST /v1/transactional/send y POST /v1/transactional/send-batch. Ningún otro endpoint la lee.
• Formato. 1–255 caracteres: letras, dígitos, _ y -. Las claves se comparan exactamente, sin recortes ni cambios de mayúsculas.
• Ventana. Una clave permanece reproducible durante 24 horas. Después, la misma clave se trata como una petición nueva.
• Reproducción. Un reintento dentro de la ventana devuelve la respuesta original tal cual (mismos ID, mismo estado) y no envía nada.
• Unicidad. Las claves son únicas por cuenta. Reutilizar una clave en otro endpoint se rechaza con 409; usa una clave distinta por operación.

ID de correlaciónCopiar enlace de la sección

Rastree solicitudes entre sistemas incluyendo un ID de correlación:

X-Correlation-ID: my-app-order-12345

o

X-Request-ID: my-app-order-12345

El ID de correlación aparece en los registros y en el flujo de actividad.

Encabezados de límite de velocidadCopiar enlace de la sección

Las respuestas exitosas incluyen información de límite de velocidad por IP:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295

Cuando el motor de políticas de envío aplica el límite (429), un encabezado Retry-After indica los segundos a esperar:

Retry-After: 30

Una solicitud transaccional puede incluir hasta 5 destinatarios, y cada uno cuenta en sus límites de velocidad. Si eso supera su límite por segundo (por ejemplo, 1 por segundo en un plan de 60 por minuto), la solicitud se acepta cuando no se aceptó ninguna otra en el mismo segundo; de lo contrario recibe 429 con Retry-After: 1 y tiene éxito al reintentarla en el segundo siguiente, dentro de su límite por minuto. Consulte Límites de Velocidad.

Un 429 a nivel de IP también incluye X-RateLimit-Reset como hora UTC en formato ISO-8601.

Respuestas de errorCopiar enlace de la sección

Todos los errores devuelven un cuerpo JSON:

{
  "code": "ERROR_CODE",
  "message": "Human-readable description",
  "timestamp": "2026-02-17T10:30:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Códigos de errorCopiar enlace de la sección

Límite de destinatarios transaccionalesCopiar enlace de la sección

Las credenciales transaccionales imponen un máximo de 5 destinatarios por solicitud de envío. Esto previene el uso indebido de flujos transaccionales para envíos masivos. Si necesita más destinatarios, use una credencial de Marketing con envío por lotes.

Uso de plantillasCopiar enlace de la sección

En lugar de HTML en línea, haga referencia a una plantilla almacenada:

{
  "from": { "email": "[email protected]" },
  "to": [
    {
      "email": "[email protected]",
      "variables": {
        "firstName": "Jane",
        "resetLink": "https://app.example.com/reset?token=abc123"
      }
    }
  ],
  "templateId": "t8x2m4q9zk7wpr",
  "variables": {
    "companyName": "Acme Inc"
  }
}

El subject proviene de la plantilla. Ante una clave superpuesta, el valor propio del destinatario en to[].variables anula las variables globales: la misma regla que con el contenido en línea. Consulte Plantillas para crear y administrar plantillas.

Próximos pasosCopiar enlace de la sección

• Envío por lotes: enviar a múltiples destinatarios a la vez
• Relay SMTP: enviar vía SMTP en lugar de REST
• Plantillas: crear plantillas de correo reutilizables
• Correos programados: programar correos para entrega futura