Programma e annulla le email

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. La risposta contiene "status": "scheduled" e l’orario normalizzato in scheduled_at, e l’email di ogni destinatario genera email.scheduled invece di email.accepted.

scheduled_at accetta questi formati:

Un orario attuale o passato invia subito l’email con lo stato 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 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 (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 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"
}

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:

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

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

Un’email programmata non genera email.accepted quando arriva il suo orario di invio. Vedi Stati delle email per l’elenco completo.

Vedi anche

• Aggiorna un’email programmata
• Annulla un’email
• Invia un’email
• Stati delle email
• Perché l’email resta bloccata in Accepted o Scheduled?