Coda dei messaggi in attesa

Nessuna email viene mai scartata in silenzio. Quando Frontmail non può inviare subito un messaggio – perché la tua organizzazione ha finito i crediti o perché il tuo servizio email ha rifiutato le credenziali – il messaggio viene accettato, conservato al sicuro nella coda dei messaggi in attesa (Messaggi in attesa nella dashboard) e inviato automaticamente non appena il problema è risolto.

Quando i messaggi vanno in attesa

Motivo	Stato	Causa
Crediti esauriti	held	Nessuna assegnazione con crediti rimanenti (quota, pacchetti e scoperto tutti esauriti) e l’organizzazione usa la modalità `hold`
Errore del servizio	held_service_error	Il provider ha rifiutato le credenziali (errore di autenticazione) e il modello non ha un servizio di riserva funzionante

Per le attese dovute ai crediti l’API risponde subito:

HTTP/1.1 202 Accepted

{ "message_id": "msg_01J9Z3K7Q2", "status": "held", "status_token": "…" }

Gli SDK si risolvono con status: 'held': è un successo, non un errore. Mostra al visitatore una normale conferma; l’email partirà non appena ci saranno crediti disponibili.

Le attese per errore del servizio avvengono più tardi, nel sender: il messaggio è stato accettato come queued, il provider ha rifiutato le credenziali, il credito è stato rimborsato e il messaggio è passato a held_service_error.

Per quanto restano in attesa i messaggi

Piano	Durata dell’attesa
Free	3 giorni
Starter, Pro, Business	14 giorni

La durata si conta dal momento in cui il messaggio è andato in attesa, in base al piano attivo in quel momento. Quando dei messaggi in attesa stanno per scadere entro 24 ore, proprietario, admin e membri con ruolo fatturazione ricevono un’email «le email in attesa stanno per scadere» (al massimo una volta al giorno). I messaggi che raggiungono la fine della durata dell’attesa vengono scartati (stato discarded) e le stesse persone ricevono un’email con il loro elenco e un link per scaricare l’elenco completo in CSV. Un messaggio in attesa non viene mai scartato senza che nessuno ne sia informato.

Limite della coda dei messaggi in attesa

Un’organizzazione può avere in attesa al massimo il 10% della quota mensile del suo piano – almeno 1.000 e al massimo 10.000 messaggi (Free, Starter, Pro: 1.000; Business 50k: 5.000; Business 100k e 200k: 10.000). Quando la coda è piena, le nuove richieste senza crediti vengono rifiutate con 402 insufficient_credits e details.reason: "hold_queue_full" invece di essere messe in attesa. Così chi ha copiato la tua chiave pubblica non può riempire la coda di messaggi spazzatura che – rilasciati dal più vecchio – consumerebbero ogni nuovo credito prima dei tuoi messaggi veri. Per liberare spazio, rilascia o scarta i messaggi in attesa oppure acquista crediti.

Rilascio automatico

Frontmail rilascia la coda automaticamente ogni volta che compaiono crediti:

viene acquistato un pacchetto di crediti,
una ricarica automatica va a buon fine,
passi a un piano superiore,
inizia un nuovo periodo di fatturazione (rinnovo dell’abbonamento; Free: nuovo mese solare),
l’assistenza Frontmail aggiunge crediti bonus.

…e, per i messaggi held_service_error, quando il servizio torna a funzionare (credenziali aggiornate, OAuth ricollegato o un controllo di stato riuscito).

Il rilascio elabora i messaggi in attesa dal più vecchio. Per ogni messaggio riserva un credito, lo riporta a queued e lo passa al sender. Si ferma al primo messaggio per cui non c’è credito: gli altri restano in attesa, sempre in ordine. Il rilascio può girare in parallelo senza problemi: un messaggio non viene mai inviato due volte.

I messaggi inviati con la chiave pubblica vengono rilasciati automaticamente solo con crediti diversi dallo scoperto, a meno che tu non consenta al traffico con chiave pubblica di usarlo in Fatturazione → Acquista crediti → Spesa dal traffico con chiave pubblica. Se resta solo lo scoperto, questi messaggi restano in attesa mentre gli altri vengono rilasciati. Un Rilascia manuale nella dashboard può usare lo scoperto anche per loro.

I messaggi in attesa vengono generati con la versione del modello che era attuale al momento dell’accettazione.

Rilascio e scarto manuali

Messaggi in attesa nella dashboard elenca ogni messaggio in attesa, dal più vecchio, con le colonne In attesa dal, modello (con l’oggetto), destinatario, Motivo e Scadenza. Le righe che scadono entro 24 ore sono evidenziate. Filtra per motivo con Tutti / Crediti esauriti / Errore del servizio. Proprietari, admin e sviluppatori possono:

Rilascia N – rilascia i messaggi selezionati. Utile dopo aver sistemato un servizio, o per inviare prima i messaggi più importanti quando hai pochi crediti. I messaggi vengono rilasciati dal più vecchio finché ci sono crediti; gli altri restano in attesa e la dashboard te lo segnala.
Rilascia tutte – rilascia tutti i messaggi in attesa, dal più vecchio, finché i crediti lo consentono.
Scarta N – scarta i messaggi selezionati dopo una conferma. Non vengono mai inviati e non usano crediti. L’operazione non si può annullare.

Proprietari e membri con ruolo fatturazione vedono nella pagina anche il pulsante Acquista crediti. Se la tua organizzazione usa la modalità reject, la pagina mostra una nota che indica che le nuove richieste vengono rifiutate invece di andare in attesa.

La barra superiore della dashboard mostra sempre quanti crediti restano (Restano N richieste). Cliccaci sopra per vedere la suddivisione per origine (abbonamento, pacchetti di crediti, bonus, scoperto) e la scadenza più vicina. Quando ci sono messaggi in attesa, accanto compare un badge rosso con il loro numero che porta a Messaggi in attesa.

Modalità `hold` e `reject`

Ogni organizzazione sceglie cosa succede quando non ci sono crediti, in Sicurezza → Quando finisci i crediti (proprietari e admin):

Modalità	Risposta	Quando usarla
Metti le email in attesa (`hold`, predefinita, consigliata)	`202` con `status: "held"`, messaggio conservato e inviato più tardi	Meglio consegnare in ritardo che mai: moduli di contatto, ordini, prenotazioni
Rifiuta le richieste (`reject`)	`402` `insufficient_credits`, nulla viene conservato	Una consegna in ritardo è peggio di nessuna consegna (codici monouso, avvisi urgenti) e il tuo codice gestisce l’errore

In modalità reject gli SDK lanciano un InsufficientCreditsError. Le attese per errore del servizio (held_service_error) avvengono in entrambe le modalità, perché la richiesta era già stata accettata.

Notifiche

Email	Quando	Destinatari
Ci sono email in attesa – hai esaurito i crediti	La prima volta che un messaggio va in attesa in un mese solare	proprietario, admin, fatturazione
Le email in attesa stanno per scadere	Al massimo una volta al giorno, finché ci sono messaggi in attesa che scadono entro 24 ore	proprietario, admin, fatturazione
Email in attesa scartate	Dopo la scadenza, con l’elenco dei messaggi scartati e un link al CSV	proprietario, admin, fatturazione
Il servizio non funziona / funziona di nuovo	Quando un servizio non supera l’autenticazione / torna a funzionare	proprietario, admin

Tutte le email sono descritte in Notifiche.

Controllare lo stato dal codice

const res = await send('svc_01J9…', 'tpl_order', params);
if (res.status === 'held') {
  // Accettato e al sicuro: verrà inviato automaticamente.
}

// Più tardi (i client con chiave pubblica hanno bisogno dello status token restituito dall'invio):
const status = await getStatus(res.messageId, { token: res.statusToken });
console.log(status.status); // "held" → "queued" → "sent" …