E-mails planifiés

Planifiez des e-mails pour un envoi futur avec prise en charge des fuseaux horaires

Planifier un e-mail

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

Champs de la requête

Champ	Type	Requis	Description
`from`	object	Oui	Adresse de l'expéditeur (`email` et `name` facultatif)
`to`	object	Oui	Destinataire unique (`email` et `name` facultatif)
`subject`	string	Oui	Ligne d'objet de l'e-mail
`html`	string	Conditionnel	Contenu HTML (`html` ou `text` requis)
`text`	string	Conditionnel	Contenu en texte brut
`replyTo`	string	Non	Adresse de réponse
`cc`	array	Non	Destinataires en CC (`email` et `name` facultatif)
`bcc`	array	Non	Destinataires en CCI (`email` et `name` facultatif)
`attachments`	array	Non	Pièces jointes (même format que l'envoi unique)
`headers`	object	Non	En-têtes d'e-mail personnalisés
`tags`	array	Non	Étiquettes pour les analyses
`scheduledAt`	datetime	Oui	Heure d'envoi. Toujours interprétée en UTC : envoyez-la avec `Z` ou un décalage explicite
`timeZone`	string	Non	Fuseau horaire IANA (ex. `America/New_York`). Stocké et renvoyé pour l'affichage uniquement : n'affecte pas le moment réel de l'envoi

scheduledAt doit être dans le futur et au plus 7 jours à l'avance. Définir timeZone ne convertit pas scheduledAt dans ce fuseau : l'horodatage est toujours lu en UTC. Un horaire dans le passé est rejeté avec 400 VALIDATION_FAILED ; plus de 7 jours à l'avance est rejeté avec 400 INVALID_REQUEST ("Cannot schedule email more than 7 days in advance"). La même fenêtre de 7 jours s'applique que la planification soit créée ici, via le point de terminaison d'envoi, ou par replanification.

Notez les différences de noms de champs par rapport au point de terminaison d'envoi : les e-mails planifiés utilisent html/text (et non htmlContent/textContent) et to est un objet unique (non un tableau).

Réponse

Statut : 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
}

Statuts des e-mails planifiés

Statut	Description
`pending`	En file d'attente pour une livraison future
`processing`	En cours de traitement pour l'envoi
`sent`	Envoyé avec succès
`failed`	Échec de l'envoi (vérifiez le champ `error`)
`cancelled`	Annulé avant l'envoi

Lister les e-mails planifiés

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

Filtrer par statut :

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
}

Paramètres de requête :

Paramètre	Type	Défaut	Description
`cursor`	string	-	Curseur opaque issu du `nextCursor` de la page précédente. À omettre pour la première page.
`limit`	int	20	Éléments par page (max 100)
`status`	string	-	Filtrer par statut : `pending`, `processing`, `sent`, `failed`, `cancelled`

Obtenir un e-mail planifié

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
}

Après envoi, la réponse inclut processedAt (quand il a été envoyé) et messageId (pour suivre les événements de livraison).

Annuler un e-mail planifié

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

Renvoie 204 No Content en cas de succès. Vous ne pouvez annuler que les e-mails avec le statut pending. Tenter d'annuler un e-mail processing, sent ou failed renvoie 400 Bad Request.

Replanifier un e-mail

Modifiez l'heure de livraison d'un e-mail en attente :

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
}

Les mêmes contraintes de planification s'appliquent : le nouveau temps doit être dans le futur et au plus 7 jours à partir de maintenant, sinon la requête est rejetée avec 400 INVALID_REQUEST.

Gestion des fuseaux horaires

scheduledAt est toujours interprété en UTC, que vous fournissiez ou non un timeZone : envoyez-le avec Z ou un décalage explicite. timeZone est stocké et renvoyé dans les réponses uniquement pour l'affichage ; MailLand ne convertit pas scheduledAt dans ce fuseau. Utilisez les identifiants de fuseau horaire IANA si vous voulez qu'il soit enregistré pour l'affichage :

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

Planification via le point de terminaison d'envoi

Vous pouvez également planifier des e-mails directement via le point de terminaison d'envoi ordinaire en incluant le champ 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 réponse 202 du point de terminaison d'envoi inclut scheduleId et scheduledAt. Cette planification est le même type de ligne que celles sur lesquelles opèrent les points de terminaison de cette page : elle peut être listée, récupérée, annulée et replanifiée avec les points de terminaison décrits ci-dessus, exactement comme une planification créée directement via /v1/transactional/scheduled. La fenêtre de 7 jours (voir l'encadré ci-dessus) s'applique également ici : un scheduledAt de plus de 7 jours à l'avance est rejeté avec 400 INVALID_REQUEST.

Étapes suivantes

API REST : envoi d'e-mails immédiat
Modèles : utiliser des modèles via /v1/transactional/send avec scheduledAt
Envoi par lots : planifier des envois par lots

E-mails planifiés

Planifier un e-mailCopier le lien de la section

Champs de la requêteCopier le lien de la section

RéponseCopier le lien de la section

Statuts des e-mails planifiésCopier le lien de la section

Lister les e-mails planifiésCopier le lien de la section

Obtenir un e-mail planifiéCopier le lien de la section

Annuler un e-mail planifiéCopier le lien de la section

Replanifier un e-mailCopier le lien de la section

Gestion des fuseaux horairesCopier le lien de la section

Planification via le point de terminaison d'envoiCopier le lien de la section

Étapes suivantesCopier le lien de la section

Sur cette page