# Programmer et annuler des e-mails

> Envoyez un e-mail plus tard avec scheduled_at, changez l’heure d’envoi, ou annulez un e-mail programmé, accepté ou en cours de nouvelle tentative, via l’API ou depuis le tableau de bord.

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](/fr/docs/email-api/send-email/). La réponse contient `"status": "scheduled"` et l’heure normalisée dans `scheduled_at`, et l’e-mail de chaque destinataire émet [`email.scheduled`](/fr/docs/webhooks/events/email/scheduled/) au lieu de `email.accepted`.

`scheduled_at` accepte ces formats :

| Format | Exemple | Remarques |
| --- | --- | --- |
| ISO 8601 avec fuseau horaire | `2026-10-05T09:00:00Z`, `2026-10-05T09:00:00+02:00` | Recommandé. Incluez toujours `Z` ou un décalage. |
| Langage naturel | `tomorrow at 9am`, `in 2 hours`, `next monday 10:00`, `friday 5pm` | Interprété en UTC : `tomorrow at 9am` signifie 9 h 00 UTC. |

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

> **Vérifiez le statut de la réponse:** Si Emailit ne parvient pas à lire la valeur de `scheduled_at`, il ne rejette pas la requête : l’e-mail est envoyé immédiatement. Vérifiez que la réponse contient `"status": "scheduled"` et le `scheduled_at` attendu. Les horodatages Unix ne sont pas reconnus ; convertissez-les d’abord au format ISO 8601.

**cURL**

```bash
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"
  }'
```

**Node.js**

```javascript
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',
});
```

**Python**

```python
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",
})
```

**PHP**

```php
$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é](/fr/docs/api-reference/emails/update/) (`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**

```bash
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" }'
```

**Node.js**

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

**Python**

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

**PHP**

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

```json
{
  "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 :

| Statut | Annulation possible ? | Remarques |
| --- | --- | --- |
| `scheduled` | Oui | Uniquement tant que l’heure d’envoi est à plus de 3 minutes. |
| `accepted` | Oui, au mieux | L’e-mail attend dans la file d’envoi ou est sur le point d’en sortir. |
| `attempted` | Oui, au mieux | Une tentative de livraison a échoué temporairement. L’annulation arrête les nouvelles tentatives restantes. |
| Tout autre statut | Non | Les e-mails livrés, qui ont rebondi, en échec, rejetés, bloqués, retenus ou déjà annulés ne peuvent pas être annulés. |

**Tableau de bord**

  1. Accédez à **Email API → Emails**.
  2. Sélectionnez **Cancel delivery** sur la ligne de l’e-mail, ou ouvrez l’e-mail et sélectionnez **Cancel delivery** en haut de la page.
  3. Confirmez. Si une tentative de livraison avait déjà commencé, le tableau de bord vous avertit que cette tentative peut encore aboutir et que les nouvelles tentatives restantes ont été arrêtées.

**API**

  Appelez [Annuler un e-mail](/fr/docs/api-reference/emails/cancel/) (`POST /emails/{id}/cancel`). Cet endpoint fonctionne avec les clés **Full Access** et **Sending Only**.

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

```json
{
  "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

| Moment | Statut | Événement webhook |
| --- | --- | --- |
| Requête avec un `scheduled_at` futur | `scheduled` | [`email.scheduled`](/fr/docs/webhooks/events/email/scheduled/) |
| L’heure d’envoi arrive | `delivered`, `attempted`, `bounced`, etc. | L’événement de livraison correspondant, comme [`email.delivered`](/fr/docs/webhooks/events/email/delivered/) |
| Annulé | `canceled` | `email.canceled`, avec `status` et `previous_status` |

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](/fr/docs/logs/email-statuses/).

## Voir aussi

- [Mettre à jour un e-mail programmé](/fr/docs/api-reference/emails/update/)
- [Annuler un e-mail](/fr/docs/api-reference/emails/cancel/)
- [Envoyer un e-mail](/fr/docs/email-api/send-email/)
- [Statuts des e-mails](/fr/docs/logs/email-statuses/)
- [Pourquoi mon e-mail reste-t-il bloqué en Accepted ou Scheduled ?](/fr/docs/kb/email-stuck-in-scheduled-or-accepted/)

---
Source: https://emailit.com/fr/docs/email-api/scheduling/