# Invio programmato

Invia un messaggio adesso, fallo arrivare dopo. Aggiungi `send_at` o `delay` a qualsiasi richiesta [Create Message](https://info.pocketalert.app/api/messages/create.md) e Pocket Alert lo conserva cifrato fino all'orario di invio, poi lo spedisce come una normale notifica push.

Nessun cron job da parte tua, nessun queue worker, nessun processo che deve restare attivo fino a martedì.

## Due modi per indicare quando

| Parametro | Accetta | Esempi |
|-----------|---------|--------|
| `send_at` | RFC3339, timestamp Unix o `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200`, `2026-08-15 09:00` |
| `delay` | Durata in stile Go o secondi semplici | `30m`, `2h`, `90s`, `3600` |

Usane uno solo: passarli entrambi restituisce `400`.

Un `send_at` senza offset di fuso orario viene interpretato nel **fuso orario del tuo account**, quindi `2026-08-15 09:00` significa le nove del mattino dove ti trovi tu, non in UTC. Impostalo nelle [impostazioni dell'account](https://pocketalert.app/account).

## Programmare un messaggio

**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 messaggio programmato restituisce `201` con `"scheduled": true` invece di un messaggio già consegnato:

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

Conserva il `tid`: è quello che usi per annullare.

## Elencare i messaggi programmati (GET)

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

Restituisce per impostazione predefinita i messaggi in attesa, dal più imminente.

| Parametro query | Valori | Descrizione |
|-----------------|--------|-------------|
| `status` | `pending`, `sending`, `sent`, `canceled`, `failed`, `all` | Filtra per stato. Il valore predefinito è `pending`. |

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

Ogni elemento contiene `tid`, `title`, `message`, `priority`, `status`, `deliver_at`, `deliver_at_utc`, `tz`, `application`, `device`, `created_at` e `actions` quando il messaggio ha dei pulsanti.

## Annullare (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"
```

| Stato | Significato |
|:------:|---------|
| `200` | Annullato. Eventuali allegati vengono eliminati con esso. |
| `404` | Nessun messaggio programmato con quel `tid` nel tuo account |
| `409` | Già inviato, già in invio o già annullato |

L'annullamento gestisce in sicurezza la concorrenza con il dispatcher: se la consegna è già iniziata, ottieni `409` invece di un messaggio annullato a metà.

## Regole da conoscere

**L'orizzonte è di 30 giorni.** Tutto ciò che va oltre viene rifiutato.

**Gli orari passati restituiscono `400`**, con una tolleranza di 60 secondi per il disallineamento dell'orologio. Entro questa finestra il messaggio viene semplicemente inviato subito.

**Livello e piano vengono risolti al momento della programmazione, non della consegna.** Un messaggio programmato come `critical` con un piano a pagamento arriva comunque come `critical`, anche se il piano scade nel frattempo. Una programmazione è una promessa.

**Il limite giornaliero viene conteggiato al momento della programmazione.** Un messaggio programmato conta nel [limite giornaliero di messaggi](https://info.pocketalert.app/features/daily-limits.md) del giorno in cui lo programmi, non del giorno in cui viene consegnato, e la consegna non viene mai bloccata dal limite. Oltre il limite, la richiesta di programmazione stessa restituisce `429`. Annullare non restituisce la quota.

**Gli allegati vengono caricati al momento della programmazione** e collegati al messaggio alla consegna. Annullando, il file salvato viene rimosso.

**I messaggi in ritardo vengono consegnati in ritardo, non scartati.** Se il servizio si riavvia dopo un orario di consegna, il messaggio parte al ciclo successivo invece di sparire.

**Il contenuto è cifrato a riposo** con la tua chiave personale dal momento della programmazione, come per i messaggi normali.

> **Warning: Funzionalità a pagamento**
>
> L'invio programmato è disponibile nei piani a pagamento. Una richiesta sul piano gratuito con `send_at` o `delay` restituisce `403`: non viene scartato nulla in silenzio.

## Vedi anche

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — riferimento completo della richiesta
- [Livelli di priorità](https://info.pocketalert.app/features/priority-levels.md) — come si comporta l'avviso consegnato
- [Pulsanti di azione](https://info.pocketalert.app/features/action-buttons.md) — i messaggi programmati mantengono i loro pulsanti
- [Limiti giornalieri di messaggi](https://info.pocketalert.app/features/daily-limits.md) — come vengono conteggiati i messaggi programmati
