# Programma e annulla le email

> Invia un’email più tardi con scheduled_at, cambia l’orario di invio o annulla un’email programmata, accettata o in fase di nuovo tentativo, dall’API o dal pannello.

Questa pagina spiega come programmare un’email per un momento successivo con l’API email, come spostarla a un altro orario e come annullare un’email prima che parta. L’annullamento funziona anche per le email non programmate, purché non siano ancora state consegnate.

## Programma un’email

Aggiungi `scheduled_at` a una [richiesta di invio](/it/docs/email-api/send-email/). La risposta contiene `"status": "scheduled"` e l’orario normalizzato in `scheduled_at`, e l’email di ogni destinatario genera [`email.scheduled`](/it/docs/webhooks/events/email/scheduled/) invece di `email.accepted`.

`scheduled_at` accetta questi formati:

| Formato | Esempio | Note |
| --- | --- | --- |
| ISO 8601 con fuso orario | `2026-10-05T09:00:00Z`, `2026-10-05T09:00:00+02:00` | Consigliato. Includi sempre `Z` o uno scostamento. |
| Linguaggio naturale | `tomorrow at 9am`, `in 2 hours`, `next monday 10:00`, `friday 5pm` | Interpretato in UTC, quindi `tomorrow at 9am` significa alle 09:00 UTC. |

Un orario attuale o passato invia subito l’email con lo stato `accepted`.

> **Controlla lo stato nella risposta:** Se Emailit non riesce a leggere il valore di `scheduled_at`, non rifiuta la richiesta: l’email viene inviata subito. Controlla che la risposta contenga `"status": "scheduled"` e lo `scheduled_at` che ti aspettavi. I timestamp Unix non vengono riconosciuti; convertili prima in 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 prepara un’email programmata al momento della richiesta, non all’orario di invio. Il template viene elaborato, gli allegati da URL vengono scaricati e i crediti vengono addebitati subito. Per cambiare il contenuto, annulla l’email e inviane una nuova.

## Cambia l’orario di invio

Usa [Aggiorna un’email programmata](/it/docs/api-reference/emails/update/) (`POST /emails/{id}`) con un nuovo `scheduled_at`. Sono accettati gli stessi formati.

- Lo stato dell’email deve essere `scheduled`.
- L’orario di invio attuale deve essere a più di 3 minuti di distanza.
- Il nuovo orario di invio deve essere nel futuro, a più di 3 minuti di distanza.

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

A differenza di un nuovo invio, qui un orario illeggibile viene rifiutato con `422 Invalid scheduled_at`. Una richiesta che viola la regola dei 3 minuti, o che riguarda un’email non programmata, non riesce con `422 Cannot update email`. Una richiesta con più destinatari crea un’email per destinatario, quindi riprogramma ogni ID `em_` della mappa `ids`. La riprogrammazione non è disponibile nel pannello.

## Annulla un’email

Puoi annullare un’email in uscita finché ha uno di questi stati:

| Stato | Puoi annullarla? | Note |
| --- | --- | --- |
| `scheduled` | Sì | Solo finché l’orario di invio è a più di 3 minuti di distanza. |
| `accepted` | Sì, senza garanzia | L’email è in attesa nella coda di invio o sta per lasciarla. |
| `attempted` | Sì, senza garanzia | Un tentativo di consegna non è riuscito temporaneamente. L’annullamento interrompe i nuovi tentativi rimanenti. |
| Qualsiasi altro stato | No | Le email consegnate, rimbalzate, non riuscite, rifiutate, soppresse, trattenute o già annullate non si possono annullare. |

**Pannello**

  1. Vai a **Email API → Emails**.
  2. Seleziona **Cancel delivery** sulla riga dell’email, oppure apri l’email e seleziona **Cancel delivery** in alto nella pagina.
  3. Conferma. Se un tentativo di consegna era già iniziato, il pannello avvisa che il tentativo potrebbe comunque completarsi e che i nuovi tentativi rimanenti sono stati interrotti.

**API**

  Chiama [Annulla un’email](/it/docs/api-reference/emails/cancel/) (`POST /emails/{id}/cancel`). Funziona con le chiavi **Full Access** e **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."
}
```

Quando `in_flight` è `true`, l’email è stata annullata ma un tentativo di consegna potrebbe essere già in corso, e il messaggio dice «The current delivery attempt may still complete; remaining retries were stopped.» Uno stato che non si può annullare, o un’email programmata a meno di 3 minuti dall’orario di invio, restituisce `422 Cannot cancel email`.

L’annullamento non rimborsa i crediti addebitati quando l’email è stata inviata tramite l’API.

### Come funziona l’annullamento

L’annullamento toglie l’email dalla coda di invio. Non la richiama dall’inbox del destinatario.

1. Emailit controlla che l’email si possa ancora annullare.
2. Imposta lo stato su `canceled`, aggiunge una voce «Canceled» allo storico delle consegne dell’email e la rimuove dalla coda di invio.
3. Se un worker di consegna ha già preso in carico l’email, il worker ricontrolla lo stato subito prima di passare il messaggio al server del destinatario e lo salta quando vede `canceled`.
4. Emailit genera `email.canceled` con il `previous_status`.

Se il messaggio era già in viaggio verso il server del destinatario, quel tentativo può comunque riuscire. Emailit mantiene lo stato `canceled` anche se il tentativo concorrente viene consegnato o rimbalza, ma il destinatario potrebbe ricevere comunque il messaggio. Considera l’annullamento come «fermalo prima che parta», non come «annulla l’invio».

## Stati ed eventi

| Momento | Stato | Evento webhook |
| --- | --- | --- |
| Richiesta con uno `scheduled_at` futuro | `scheduled` | [`email.scheduled`](/it/docs/webhooks/events/email/scheduled/) |
| Arriva l’orario di invio | `delivered`, `attempted`, `bounced` e così via | L’evento di consegna corrispondente, come [`email.delivered`](/it/docs/webhooks/events/email/delivered/) |
| Annullata | `canceled` | `email.canceled`, con `status` e `previous_status` |

Un’email programmata non genera `email.accepted` quando arriva il suo orario di invio. Vedi [Stati delle email](/it/docs/logs/email-statuses/) per l’elenco completo.

## Vedi anche

- [Aggiorna un’email programmata](/it/docs/api-reference/emails/update/)
- [Annulla un’email](/it/docs/api-reference/emails/cancel/)
- [Invia un’email](/it/docs/email-api/send-email/)
- [Stati delle email](/it/docs/logs/email-statuses/)
- [Perché l’email resta bloccata in Accepted o Scheduled?](/it/docs/kb/email-stuck-in-scheduled-or-accepted/)

---
Fonte: https://emailit.com/it/docs/email-api/scheduling/