# Envoi programmé

Envoyez un message maintenant, faites-le arriver plus tard. Ajoutez `send_at` ou `delay` à toute requête [Create Message](https://info.pocketalert.app/api/messages/create.md) et Pocket Alert le stocke chiffré jusqu'à l'heure d'envoi, puis l'envoie comme une notification push normale.

Pas de tâche cron de votre côté, pas de worker de file d'attente, pas de processus qui doit rester actif jusqu'à mardi.

## Deux façons d'indiquer le moment

| Paramètre | Accepte | Exemples |
|-----------|---------|----------|
| `send_at` | RFC3339, timestamp Unix ou `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200`, `2026-08-15 09:00` |
| `delay` | Durée au format Go ou secondes brutes | `30m`, `2h`, `90s`, `3600` |

Indiquez l'un ou l'autre : en passer deux renvoie `400`.

Un `send_at` sans décalage horaire est interprété dans **le fuseau horaire de votre compte**, donc `2026-08-15 09:00` correspond à neuf heures du matin là où vous vous trouvez, et non en UTC. Définissez-le dans les [paramètres du compte](https://pocketalert.app/account).

## Programmer un message

**cURL — absolute time**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Certificate expires tomorrow",
    "message": "api.example.com — renew before 09:00 UTC",
    "send_at": "2026-08-15T09:00:00Z",
    "level": "high"
  }'
```

**cURL — relative delay**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Check the migration",
    "message": "Started at 14:02 — verify row counts",
    "delay": "2h"
  }'
```

**JavaScript**

```javascript
await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: { 'Token': 'your-api-key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Check the migration',
    message: 'Started at 14:02 — verify row counts',
    delay: '2h'
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={'Token': 'your-api-key'},
    json={
        'title': 'Check the migration',
        'message': 'Started at 14:02 — verify row counts',
        'delay': '2h'
    }
)
```

Un message programmé renvoie `201` avec `"scheduled": true` au lieu d'un message livré :

```json
{
  "tid": "n8k2vq7pxr4m",
  "scheduled": true,
  "status": "pending",
  "title": "Check the migration",
  "deliver_at": "09.08.2026 16:02:00",
  "deliver_at_utc": "2026-08-09T13:02:00Z",
  "tz": "Europe/Berlin"
}
```

Conservez le `tid` : c'est lui qui sert à annuler.

## Lister les messages programmés (GET)

```
GET https://api.pocketalert.app/v1/messages/scheduled
```

Renvoie par défaut les messages en attente, du plus proche au plus lointain.

| Paramètre de requête | Valeurs | Description |
|-----------------|--------|-------------|
| `status` | `pending`, `sending`, `sent`, `canceled`, `failed`, `all` | Filtre par état. Par défaut `pending`. |

```bash
curl -X GET "https://api.pocketalert.app/v1/messages/scheduled?status=all" \
  -H "Token: your-api-key"
```

Chaque élément contient `tid`, `title`, `message`, `priority`, `status`, `deliver_at`, `deliver_at_utc`, `tz`, `application`, `device`, `created_at`, ainsi que `actions` lorsque le message comporte des boutons.

## Annuler (DELETE)

```
DELETE https://api.pocketalert.app/v1/messages/scheduled/{tid}
```

```bash
curl -X DELETE "https://api.pocketalert.app/v1/messages/scheduled/n8k2vq7pxr4m" \
  -H "Token: your-api-key"
```

| Statut | Signification |
|:------:|---------|
| `200` | Annulé. Toute pièce jointe est supprimée avec lui. |
| `404` | Aucun message programmé avec ce `tid` sur votre compte |
| `409` | Déjà envoyé, en cours d'envoi ou déjà annulé |

L'annulation est sûre face au dispatcher : si l'envoi a déjà commencé, vous recevez `409` plutôt qu'un message annulé à moitié.

## Règles à connaître

**L'horizon est de 30 jours.** Tout ce qui est plus lointain est refusé.

**Les heures passées renvoient `400`**, avec une tolérance de 60 secondes pour le décalage d'horloge. Dans cette fenêtre, le message est simplement envoyé immédiatement.

**Le niveau et l'offre sont évalués au moment de la programmation, pas au moment de l'envoi.** Un message programmé en `critical` sur une offre payante arrive toujours en `critical`, même si l'offre expire entre-temps. Un envoi programmé est une promesse.

**La limite quotidienne est décomptée à la programmation.** Un message programmé compte dans la [limite quotidienne de messages](https://info.pocketalert.app/features/daily-limits.md) du jour où vous le programmez, et non du jour de son envoi ; l'envoi n'est jamais bloqué par la limite. Au-delà de la limite, la requête de programmation elle-même renvoie `429`. L'annulation ne rend pas le quota.

**Les pièces jointes sont téléversées au moment de la programmation** et rattachées au message lors de l'envoi. L'annulation supprime le fichier stocké.

**Les messages en retard sont envoyés tardivement, jamais abandonnés.** Si le service redémarre après une heure d'envoi, le message part au prochain cycle au lieu de disparaître.

**Le contenu est chiffré au repos** avec votre clé personnelle dès la programmation, comme pour les messages classiques.

> **Warning: Fonctionnalité payante**
>
> L'envoi programmé est disponible avec les offres payantes. Une requête avec `send_at` ou `delay` sur l'offre gratuite renvoie `403` : rien n'est supprimé en silence.

## Voir aussi

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — référence complète de la requête
- [Niveaux de priorité](https://info.pocketalert.app/features/priority-levels.md) — comportement de l'alerte livrée
- [Boutons d’action](https://info.pocketalert.app/features/action-buttons.md) — les messages programmés conservent leurs boutons
- [Limites quotidiennes de messages](https://info.pocketalert.app/features/daily-limits.md) — comptage des messages programmés
