Sign inGet Started

Invio programmato

Imposta scheduled_at per trattenere un messaggio fino a un orario specifico. Quando quell'orario arriva, il messaggio entra nel normale ciclo di vita della consegna e produce gli stessi eventi di un invio immediato. La tua applicazione non ha bisogno di un proprio scheduler.

Programmare un invio

Aggiungi un timestamp scheduled_at a un normale invio POST /v1/email/messages. Il resto del payload non cambia.

const msg = await bird.email.send({
  from: "news@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Your weekly digest",
  html: '<p>Here is what happened this week...</p><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></p>',
  category: "marketing",
  scheduled_at: "2027-01-15T09:00:00Z",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

La chiamata restituisce subito 202 Accepted con l'ID del messaggio prefissato da em_ e status: accepted. È lo stesso oggetto messaggio restituito da un invio immediato, più scheduled_at riportato in UTC, così puoi confermare l'orario di invio senza una lettura successiva. L'accettazione è sincrona; la consegna è differita. Ometti scheduled_at dalla richiesta e il messaggio parte subito, e la risposta non contiene la chiave scheduled_at.

Le letture si aggiornano in modo asincrono. Un messaggio appena programmato può inizialmente restituire 404 tramite Recupera un messaggio e non comparire nell'elenco dei messaggi o nella dashboard. Contenuti di grandi dimensioni o allegati possono prolungare l'attesa mentre li archiviamo. Conserva l'ID e scheduled_at della risposta 202 e riprova le letture con quell'ID, lasciando una pausa tra i tentativi. Puoi anche annullare con questo ID prima che il messaggio compaia.

Quando un messaggio compare mentre è ancora in attesa di invio, le letture mostrano status: scheduled e il suo scheduled_at:

Esempio di codice
{
  "id": "em_01ky7q24hafjgvzfg02v3m177p",
  "status": "scheduled",
  "scheduled_at": "2027-01-15T09:00:00Z",
  "category": "marketing"
}

Quando arriva il momento, il messaggio viene rilasciato e il suo stato avanza attraverso gli stati consueti (accepted, poi processed, poi delivered e così via). scheduled_at resta impostato anche dopo, così puoi sempre vedere per quando era programmato un messaggio.

L'invio di un messaggio può iniziare prima che le letture si aggiornino, quindi potresti vedere prima uno stato successivo. Non esiste un intervallo fisso dopo il quale una lettura mostrerà sicuramente il messaggio.

Se il tuo piano prevede una quota di email programmate per il periodo di fatturazione, ogni invio programmato ne consuma un'unità. Il superamento di tale quota viene rifiutato con un 422 (E10003).

Programmare contenuti inline o un modello

Usa scheduled_at con contenuti inline o un modello salvato, costruito come per un invio con modello immediato. Quando accettiamo la richiesta salviamo la versione pubblicata, la lingua selezionata, i parametri del chiamante, i valori dei contatti e i link di disiscrizione, e all'orario programmato usiamo quei valori salvati. Modifiche ed eliminazioni dei contatti e cambi dei valori di fallback non alterano il messaggio accettato. Pubblicare una versione più recente non modifica la selezione. Se il modello viene eliminato prima dell'orario programmato, il messaggio viene rifiutato senza essere inviato.

Un messaggio della categoria marketing riceve un link di disiscrizione come piccolo piè di pagina alla fine del corpo. Per posizionare il link tu stesso, inserisci {{ bird.unsubscribe_url }} in ogni corpo del messaggio fornito oppure, per un invio con modello, nei corpi del modello.

Un elemento di un batch accetta scheduled_at alle stesse condizioni, quindi un singolo batch può mescolare messaggi programmati e immediati. Ogni elemento programmato consuma la propria unità della quota, e l'intero batch viene rifiutato se l'orario di un qualsiasi elemento è fuori intervallo. Ogni elemento programmato riporta il proprio scheduled_at nella risposta del batch, e un elemento inviato immediatamente non ha la chiave scheduled_at; il riferimento batch mostra entrambi in un'unica risposta.

I messaggi annullati conservano i valori dei destinatari accettati per la cronologia. Se lo snapshot salvato non è più disponibile, lo stato e l'oggetto rappresentativo restano leggibili, gli oggetti per destinatario vengono omessi e il contenuto non può essere ricostruito dai contatti attuali.

Dimensione del messaggio

Un invio programmato ha lo stesso limite di 20 MB per messaggio di un invio immediato e, se lo supera, restituisce lo stesso 413 (E04002). I corpi HTML e di testo e il contenuto dei file allegati e delle immagini inline contano ai fini di quel limite e non del limite di programmazione descritto di seguito.

Il resto di una richiesta programmata condivide un limite di 31 KB. Ne fanno parte gli indirizzi e i nomi dei destinatari, reply_to, subject, gli headers personalizzati, tags, metadata, parameters o template.parameters, più qualche centinaio di byte per allegato per il nome del file e i relativi dettagli. La maggior parte degli invii resta ben al di sotto: 150 destinatari con nomi e indirizzi tipici occupano circa 25 KB. In un invio con modello personalizzato con i dati dei contatti, ogni copia in Cc e Bcc conta come un ulteriore destinatario, mentre i valori dei contatti e i link di disiscrizione non contano. Una richiesta oltre il limite restituisce 422 con param impostato su scheduled_at. Invia a meno destinatari per messaggio, riduci le intestazioni o i parametri, oppure invia il messaggio immediatamente.

I valori dei contatti vengono salvati quando accettiamo la programmazione. Se il salvataggio non riesce, API restituisce un errore per cui puoi riprovare e non programma il messaggio. Corpi e allegati possono essere ancora in fase di archiviazione dopo la risposta 202. Se l'archiviazione continua a non riuscire, il messaggio non viene inviato e, quando lo recuperi tramite il suo ID, risulta rejected. Nessun webhook lo segnala, quindi controlla il messaggio tramite ID se devi confermare che sia stato inviato e invialo di nuovo se è stato rifiutato.

Scegliere l'orario di invio

scheduled_at è un timestamp assoluto RFC 3339. Due regole lo governano:

  • Deve essere tra 30 secondi e 30 giorni nel futuro. Meno di 30 secondi o più di 30 giorni viene rifiutato con un 422. Il limite inferiore impedisce a una programmazione di competere con un invio immediato. Trenta giorni è l'orizzonte massimo per cui tratteniamo un messaggio.
  • Fornisci un istante esatto. Includi un suffisso UTC Z (2027-01-15T09:00:00Z) o un offset esplicito (2026-07-30T09:00:00-04:00, lo stesso istante di 13:00:00Z). Confrontiamo l'istante con l'ora corrente e non interpretiamo mai un'ora locale senza offset né applichiamo il fuso orario del destinatario. Per inviare alle 9:00 nell'ora locale di ciascun destinatario, calcola tu quegli istanti e programma un invio per fuso orario.

Espressioni relative come "in 2 hours" non sono accettate. Invia un timestamp risolto.

Elencare i messaggi programmati

Filtra l'elenco dei messaggi per stato per vedere i messaggi già visibili e ancora in attesa di invio. Un invio programmato appena accettato può non comparire mentre il contenuto viene caricato o le letture si aggiornano:

for await (const message of bird.email.list({ status: "scheduled" })) {
  console.log(message.id, message.scheduled_at);
}

status=canceled elenca quelli che hai annullato prima dell'invio. Quando un messaggio programmato parte, entra nella pipeline e compare con gli stati di consegna, come qualsiasi altro invio. Il log email della dashboard offre gli stessi filtri Scheduled e Canceled.

Annullare un invio programmato

Annulla un messaggio in qualsiasi momento prima che inizi l'invio con POST /v1/email/messages/{message_id}/cancel:

await bird.email.cancel("em_abc123");

Un annullamento riuscito restituisce 204 No Content. Lo stato del messaggio diventa canceled, il messaggio non viene mai inviato e viene emesso un webhook email.canceled. Quattro cose da sapere:

  • Solo un messaggio ancora programmato può essere annullato. Un messaggio che ha già iniziato l'invio, è già stato inviato o è già stato annullato restituisce 409:

    Esempio di codice
    {
      "error": {
        "type": "conflict_error",
        "code": "E10005",
        "name": "EmailNotCancelable",
        "message": "This message cannot be canceled.",
        "remediation": "Only a scheduled message that has not started sending can be canceled. Once sending begins there is no way to pull it back."
      }
    }

    All'avvicinarsi dell'orario di invio, un annullamento può anche perdere la corsa con l'invio stesso e restituire 409 per lo stesso motivo.

  • Puoi annullare l’invio mentre il contenuto è ancora in caricamento. Un invio programmato con allegati o un corpo di grandi dimensioni potrebbe ancora memorizzare il contenuto dopo la risposta 202. Un annullamento riuscito resta valido anche se il caricamento termina in seguito.

  • L'annullamento non restituisce l'unità della quota di email programmate. L'unità consumata al momento della programmazione resta consumata: è ciò che impedisce a un ciclo programma-e-annulla di aggirare la quota. La quota di invio e il wallet non vengono toccati, perché un invio viene conteggiato e addebitato solo quando il messaggio viene effettivamente inviato.

  • L'annullamento è sicuro da riprovare con un Idempotency-Key, come qualsiasi altra scrittura.

Per spostare un invio programmato a un orario diverso, annullalo e invia un nuovo messaggio con il nuovo scheduled_at. Ottieni un nuovo ID em_.

Cosa succede al momento dell'invio

La programmazione cambia solo quando un messaggio viene rilasciato. La sua costruzione e le sue regole restano le stesse. Allegati, categoria, tag e metadati si comportano esattamente come in un invio immediato e vengono riportati negli eventi webhook allo stesso modo. Cinque controlli si dividono tra i due momenti:

  • La validazione del payload e del dominio avviene subito. Un invio programmato malformato fallisce nella chiamata API con un 422, così lo scopri ora e non alle 9 di mattina.
  • Il dominio del mittente viene ricontrollato al momento dell'invio. Se il tuo dominio from non è più verificato quando arriva l'orario programmato, il messaggio non viene inviato. I suoi destinatari vengono restituiti come rejected con un motivo, invece di ricevere email da un dominio non verificato. Mantieni il dominio verificato per tutta la finestra.
  • L'invio viene conteggiato e addebitato al momento dell'invio. La programmazione lascia invariati la quota di invio e il wallet. Quando il messaggio parte, viene conteggiato nella quota del piano Email Free oppure, con un piano Email a pagamento, addebitato sul wallet. Se la quota è esaurita o il wallet non ha più saldo né credito, i destinatari vengono rifiutati.
  • La soppressione viene valutata al momento dell'invio, in base alla tua lista di soppressione così com'è in quel momento, quindi chi si disiscrive tra la programmazione e l'invio viene comunque rispettato.
  • Un modello salvato deve esistere ancora al momento dell'invio. Se elimini il modello dopo la programmazione, il messaggio non viene inviato. I suoi destinatari vengono restituiti come rejected con generation_failure.

Errori

StatoCodiceQuando
422E10003La quota di email programmate della tua organizzazione per il periodo di fatturazione è esaurita
422scheduled_at è a meno di 30 secondi o a più di 30 giorni di distanza
422Destinatari, intestazioni, parametri e metadati superano il limite di programmazione di 31 KB
413E04002Il messaggio generato supera i 20 MB, lo stesso limite di un invio immediato
409E10005Il messaggio non può più essere annullato: ha già iniziato l'invio, è stato inviato o è stato annullato
404La lettura del messaggio non ne riflette ancora l'accettazione, oppure non esiste alcun messaggio con quell'ID in questo spazio di lavoro

Webhook

Due eventi sono specifici della programmazione, oltre ai consueti eventi di consegna:

  • email.scheduled segnala un messaggio in attesa dell'orario futuro indicato da scheduled_at. Per gli invii con un modello, la versione selezionata viene caricata di nuovo e il suo contenuto viene preparato al momento dell'invio. Questo evento può arrivare prima che la preparazione sia completata.
  • email.canceled viene emesso quando un messaggio programmato viene annullato prima dell'invio.

Quando il messaggio parte, la normale catena email.accepted prosegue invariata.

Gli eventi di programmazione vengono pubblicati in modo asincrono. Un messaggio può uscire dallo stato programmato prima che venga pubblicato email.scheduled. Ricevere un webhook non significa che gli endpoint di lettura mostrino già quello stato.

Passi successivi

Continua con la documentazione, le guide e gli esempi per questo argomento.