Programmer et annuler des e-mails

Cette page explique comment programmer un e-mail pour plus tard avec l’API e-mail, comment le décaler à une autre heure et comment annuler un e-mail avant son départ. L’annulation fonctionne aussi pour les e-mails qui n’étaient pas programmés, tant qu’ils n’ont pas encore été livrés.

Programmer un e-mail

Ajoutez scheduled_at à une requête d’envoi. La réponse contient "status": "scheduled" et l’heure normalisée dans scheduled_at, et l’e-mail de chaque destinataire émet email.scheduled au lieu de email.accepted.

scheduled_at accepte ces formats :

Une heure égale à maintenant ou passée envoie l’e-mail immédiatement avec le statut accepted.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z"
  }'

const email = await emailit.emails.send({
  from: 'Acme <reminders@acme.com>',
  to: 'ada@example.com',
  subject: 'Your appointment is tomorrow',
  text: 'See you at 14:00.',
  scheduled_at: '2026-10-05T09:00:00Z',
});

email = client.emails.send({
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z",
})

$email = $emailit->emails()->send([
    'from' => 'Acme <reminders@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Your appointment is tomorrow',
    'text' => 'See you at 14:00.',
    'scheduled_at' => '2026-10-05T09:00:00Z',
]);

Emailit prépare un e-mail programmé au moment de la requête, pas à l’heure d’envoi. Le rendu du modèle est effectué, les pièces jointes par URL sont téléchargées et les crédits sont débités dès la requête. Pour modifier le contenu, annulez l’e-mail et envoyez-en un nouveau.

Changer l’heure d’envoi

Utilisez Mettre à jour un e-mail programmé (POST /emails/{id}) avec un nouveau scheduled_at. Les mêmes formats sont acceptés.

• Le statut de l’e-mail doit être scheduled.
• Son heure d’envoi actuelle doit être à plus de 3 minutes.
• La nouvelle heure d’envoi doit se situer à plus de 3 minutes dans le futur.

curl https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-10-05T15:00:00Z" }'

await emailit.emails.update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', {
  scheduled_at: '2026-10-05T15:00:00Z',
});

client.emails.update("em_33VtK8mRq1xZp7LwN4cY2bHsDfa", {
    "scheduled_at": "2026-10-05T15:00:00Z",
})

$emailit->emails()->update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', [
    'scheduled_at' => '2026-10-05T15:00:00Z',
]);

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "scheduled",
  "scheduled_at": "2026-10-05T15:00:00.000Z",
  "updated_at": "2026-10-01T10:02:44.193027Z",
  "message": "Email schedule has been updated successfully"
}

Contrairement à un nouvel envoi, une heure illisible est ici rejetée avec 422 Invalid scheduled_at. Une requête qui enfreint la règle des 3 minutes, ou qui vise un e-mail non programmé, échoue avec 422 Cannot update email. Une requête avec plusieurs destinataires crée un e-mail par destinataire : reprogrammez donc chaque ID em_ de l’objet ids. La reprogrammation n’est pas disponible dans le tableau de bord.

Annuler un e-mail

Vous pouvez annuler un e-mail sortant tant qu’il a l’un de ces statuts :

curl -X POST https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa/cancel \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "canceled",
  "in_flight": false,
  "message": "Email has been canceled and removed from the send queue."
}

Quand in_flight vaut true, l’e-mail a été annulé mais une tentative de livraison est peut-être déjà en cours, et le message indique « The current delivery attempt may still complete; remaining retries were stopped. » Un statut qui ne peut pas être annulé, ou un e-mail programmé à moins de 3 minutes de son heure d’envoi, renvoie 422 Cannot cancel email.

L’annulation ne rembourse pas les crédits débités lors de l’envoi de l’e-mail via l’API.

Fonctionnement de l’annulation

L’annulation retire l’e-mail de la file d’envoi. Il ne s’agit pas d’un rappel depuis la boîte de réception du destinataire.

1. Emailit vérifie que l’e-mail peut encore être annulé.
2. Il passe le statut à canceled, ajoute une entrée « Canceled » à l’historique de livraison de l’e-mail et le retire de la file d’envoi.
3. Si un processus de livraison a déjà pris l’e-mail en charge, il vérifie de nouveau le statut juste avant de remettre le message au serveur du destinataire et l’ignore s’il voit canceled.
4. Emailit émet email.canceled avec le previous_status.

Si le message était déjà en route vers le serveur du destinataire, cette tentative peut encore réussir. Emailit conserve le statut canceled même si la tentative concurrente aboutit à une livraison ou à un rebond, mais le destinataire peut tout de même recevoir le message. Considérez l’annulation comme « arrêter l’e-mail avant son départ », et non comme « annuler l’envoi ».

Statuts et événements

Un e-mail programmé n’émet pas email.accepted quand son heure d’envoi arrive. Pour la liste complète, consultez Statuts des e-mails.

Voir aussi

• Mettre à jour un e-mail programmé
• Annuler un e-mail
• Envoyer un e-mail
• Statuts des e-mails
• Pourquoi mon e-mail reste-t-il bloqué en Accepted ou Scheduled ?