Correos programados

Programar un correo

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

Schedule an email

curl -X POST https://api.mail.land/v1/transactional/scheduled \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "email": "[email protected]",
      "name": "Your App"
    },
    "to": {
      "email": "[email protected]",
      "name": "Jane Doe"
    },
    "subject": "Your trial expires tomorrow",
    "html": "<h1>Hi Jane,</h1><p>Your free trial expires tomorrow. Upgrade now to keep access.</p>",
    "text": "Hi Jane, Your free trial expires tomorrow. Upgrade now to keep access.",
    "scheduledAt": "2026-02-18T09:00:00Z",
    "timeZone": "America/New_York",
    "tags": ["trial-expiry", "reminder"]
  }'

Campos de la solicitud

Campo	Tipo	Requerido	Descripción
`from`	objeto	Sí	Dirección del remitente (`email` y `name` opcional)
`to`	objeto	Sí	Destinatario único (`email` y `name` opcional)
`subject`	cadena	Sí	Asunto del correo
`html`	cadena	Condicional	Contenido HTML (se requiere `html` o `text`)
`text`	cadena	Condicional	Contenido en texto plano
`replyTo`	cadena	No	Dirección de respuesta
`cc`	arreglo	No	Destinatarios en copia (`email` y `name` opcional)
`bcc`	arreglo	No	Destinatarios en copia oculta (`email` y `name` opcional)
`attachments`	arreglo	No	Archivos adjuntos (mismo formato que el envío individual)
`headers`	objeto	No	Encabezados de correo personalizados
`tags`	arreglo	No	Etiquetas para análisis
`scheduledAt`	fechahora	Sí	Cuándo enviar. Siempre se interpreta como UTC: envíelo con `Z` o un desfase explícito
`timeZone`	cadena	No	Zona horaria IANA (ej., `America/New_York`). Se almacena y se devuelve solo para mostrarla: no afecta el momento real del envío

scheduledAt debe estar en el futuro y no más de 7 días por delante. Establecer timeZone no convierte scheduledAt a esa zona: la marca de tiempo siempre se lee como UTC. Un momento en el pasado se rechaza con 400 VALIDATION_FAILED; más de 7 días por delante se rechaza con 400 INVALID_REQUEST ("Cannot schedule email more than 7 days in advance"). La misma ventana de 7 días se aplica ya sea que la programación se cree aquí, mediante el endpoint de envío o al reprogramar.

Tenga en cuenta las diferencias de nombre de campo con respecto al endpoint de envío: los correos programados usan html/text (no htmlContent/textContent) y to es un objeto único (no un arreglo).

Respuesta

Estado: 201 Created

Schedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Estados de correos programados

Estado	Descripción
`pending`	En cola para entrega futura
`processing`	En proceso de envío
`sent`	Enviado exitosamente
`failed`	Error en el envío (consulte el campo `error`)
`cancelled`	Cancelado antes del envío

Listar correos programados

GET https://api.mail.land/v1/transactional/scheduled?limit=20

List scheduled emails

curl https://api.mail.land/v1/transactional/scheduled?limit=20 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Filtrar por estado:

GET https://api.mail.land/v1/transactional/scheduled?status=pending

List scheduled emails by status

curl "https://api.mail.land/v1/transactional/scheduled?status=pending" \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

List response

{
  "items": [
    {
      "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "pending",
      "scheduledAt": "2026-02-18T09:00:00Z",
      "timeZone": "America/New_York",
      "to": "[email protected]",
      "recipientCount": 1,
      "subject": "Your trial expires tomorrow",
      "createdAt": "2026-02-17T10:00:00Z",
      "processedAt": null,
      "messageIds": [],
      "rejectedRecipients": [],
      "reasonCode": null,
      "error": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Parámetros de consulta:

Parámetro	Tipo	Predeterminado	Descripción
`cursor`	cadena	-	Cursor opaco del `nextCursor` de la página anterior. Omitir para la primera página.
`limit`	entero	20	Elementos por página (máx. 100)
`status`	cadena	-	Filtrar por estado: `pending`, `processing`, `sent`, `failed`, `cancelled`

Obtener un correo programado

GET https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Get a scheduled email

curl https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Detail response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "sent",
  "scheduledAt": "2026-02-18T09:00:00Z",
  "timeZone": "America/New_York",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": "2026-02-18T09:00:02Z",
  "messageId": "t_a1b2c3d4e5f6...",
  "messageIds": ["t_a1b2c3d4e5f6..."],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Después del envío, la respuesta incluye processedAt (cuándo se envió) y messageId (para rastrear eventos de entrega).

Cancelar un correo programado

DELETE https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Cancel a scheduled email

curl -X DELETE https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..."

Devuelve 204 No Content en caso de éxito. Solo puede cancelar correos con estado pending. Intentar cancelar un correo con estado processing, sent o failed devuelve 400 Bad Request.

Reprogramar un correo

Cambie la hora de entrega de un correo pendiente:

PATCH https://api.mail.land/v1/transactional/scheduled/{scheduleId}

Reschedule an email

curl -X PATCH https://api.mail.land/v1/transactional/scheduled/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
  -H "X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD..." \
  -H "Content-Type: application/json" \
  -d '{
    "scheduledAt": "2026-02-19T14:00:00Z",
    "timeZone": "Europe/London"
  }'

Reschedule response

{
  "scheduleId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "pending",
  "scheduledAt": "2026-02-19T14:00:00Z",
  "timeZone": "Europe/London",
  "to": "[email protected]",
  "recipientCount": 1,
  "subject": "Your trial expires tomorrow",
  "createdAt": "2026-02-17T10:00:00Z",
  "processedAt": null,
  "messageIds": [],
  "rejectedRecipients": [],
  "reasonCode": null,
  "error": null
}

Se aplican las mismas restricciones de programación: el nuevo horario debe estar en el futuro y no más de 7 días a partir de ahora, o la solicitud se rechaza con 400 INVALID_REQUEST.

Manejo de zonas horarias

scheduledAt siempre se interpreta como UTC, proporcione o no un timeZone: envíelo con Z o un desfase explícito. timeZone se almacena y se devuelve en las respuestas solo para mostrarla; MailLand no convierte scheduledAt a esa zona. Use identificadores de zona horaria IANA si desea que quede registrada para mostrarla:

America/New_York
Europe/London
Asia/Tokyo
Australia/Sydney

Programación mediante el endpoint de envío

También puede programar correos directamente a través del endpoint de envío regular incluyendo el campo scheduledAt:

Schedule via send endpoint

{
  "from": { "email": "[email protected]" },
  "to": [{ "email": "[email protected]" }],
  "subject": "Scheduled email",
  "htmlContent": "<p>This will be sent later.</p>",
  "scheduledAt": "2026-02-18T09:00:00Z"
}

La respuesta 202 del endpoint de envío incluye scheduleId y scheduledAt. Esa programación es el mismo tipo de registro con el que operan los endpoints de esta página: se puede listar, obtener, cancelar y reprogramar con los endpoints descritos arriba, exactamente igual que una programación creada directamente mediante /v1/transactional/scheduled. La ventana de 7 días (ver el aviso arriba) también se aplica aquí: un scheduledAt con más de 7 días de antelación se rechaza con 400 INVALID_REQUEST.

Pasos siguientes

REST API: envío inmediato de correos
Plantillas: usar plantillas mediante /v1/transactional/send con scheduledAt
Envío por lotes: programar envíos por lotes

Correos programados

Programar un correoCopiar enlace de la sección

Campos de la solicitudCopiar enlace de la sección

RespuestaCopiar enlace de la sección

Estados de correos programadosCopiar enlace de la sección

Listar correos programadosCopiar enlace de la sección

Obtener un correo programadoCopiar enlace de la sección

Cancelar un correo programadoCopiar enlace de la sección

Reprogramar un correoCopiar enlace de la sección

Manejo de zonas horariasCopiar enlace de la sección

Programación mediante el endpoint de envíoCopiar enlace de la sección

Pasos siguientesCopiar enlace de la sección

En esta página