Risoluzione dei problemi

Parti dal codice di errore: ogni errore dell’API include code e docs_url, e Codici di errore li spiega uno per uno. Cronologia mostra ogni messaggio accettato con la sua cronologia eventi, la risposta del provider e il contenuto generato.

La richiesta fallisce

403 origin_not_allowed – Aggiungi il dominio del tuo sito in Sicurezza → Siti consentiti (e localhost per lo sviluppo). Controlla l’host esatto, compreso www.. Con details.reason: "no_origin" la richiesta non aveva alcun Origin (app nativa, script lato server): per le app attiva Consenti app mobile, sui server usa una chiave privata. Vedi Domini consentiti.

403 private_key_in_browser – È stata usata una chiave privata da una pagina web. Nel browser usa la chiave pubblica e tieni quella privata sul tuo server. Vedi Chiavi.

403 captcha_required / captcha_failed – Il modello richiede Turnstile. Mostra il widget dentro il modulo o passa turnstileToken; reimposta il widget dopo ogni tentativo, perché i token sono monouso. captcha_failed con hostname_mismatch significa che il widget è stato risolto su un hostname diverso dall’origin della richiesta – aggiungi tutti gli hostname del tuo sito al tuo widget Turnstile. Vedi Turnstile.

403 captcha_not_configured – Il modello richiede il CAPTCHA, ma la tua organizzazione non ha aggiunto le proprie chiavi Turnstile. Crea un widget gratuito in Cloudflare e incolla la chiave del sito e la chiave segreta in Sicurezza → Protezione dai bot (Turnstile), oppure disattiva il CAPTCHA nel modello.

422 invalid_template_params – Guarda details.issues: ogni problema indica il param e la regola. Cause comuni: un campo obbligatorio è vuoto, un parametro email ha ricevuto un nome, un parametro number ha ricevuto "12 pz", un parametro list ha ricevuto una stringa che non è JSON.

403 dynamic_recipient_not_allowed – A/CC/BCC del modello usano un parametro. Per le conferme usa una risposta automatica, oppure attiva Consenti destinatario dinamico in Impostazioni → Protezione del modello.

429 rate_limited – Hai superato il limite del piano, dell’IP o della chiave. L’SDK ha già atteso e riprovato. Per gli invii massivi da un server usa gli invii in batch.

Errore CORS nella console del browser – Di solito è un altro errore travestito: la richiesta è stata bloccata da una Content-Security-Policy (connect-src), da un ad blocker, oppure è andata a un apiUrl sbagliato. L’API di Frontmail invia gli header CORS per tutte le origini; l’accesso è controllato dai domini consentiti.

La richiesta va a buon fine ma non arriva nessuna email

1. Trova il messaggio in Cronologia.
   • held – hai finito i crediti. Acquista un pacchetto (Acquista crediti) o aspetta il rinnovo; verrà inviato automaticamente. Lo trovi anche in Messaggi in attesa. Vedi Coda dei messaggi in attesa.
   • held_service_error – le credenziali del tuo servizio hanno smesso di funzionare. Apri Servizi email, sistema o ricollega il servizio; i messaggi in attesa verranno poi inviati automaticamente.
   • failed – apri il messaggio: l’errore del provider è mostrato nella cronologia eventi. Le cause tipiche sono un dominio mittente non verificato o un destinatario non valido.
   • sent – il provider l’ha accettato. Continua qui sotto.
2. Controlla lo spam. Se è lì, configura SPF, DKIM e DMARC per il dominio del mittente come descritto nella guida del tuo provider, e usa un indirizzo From su quel dominio (non un indirizzo @gmail.com tramite un provider transazionale).
3. Controlla la lista di soppressione. Gli invii a indirizzi bloccati falliscono con 451, ma se hai rimosso l’indirizzo dalla lista dopo un mancato recapito, la casella potrebbe comunque non esistere.
4. Configura i webhook per vedere gli eventi delivered / bounced invece di tirare a indovinare.

Il servizio continua a risultare non funzionante

• Gmail: Google revoca i refresh token quando cambia la password, quando l’utente rimuove l’accesso dell’app o dopo 6 mesi di inutilizzo. Ricollega il servizio.
• Provider API: la chiave è stata ruotata o i suoi permessi ridotti. Crea una chiave con il permesso di invio e aggiorna il servizio.
• SMTP: la password della casella è cambiata, oppure il provider richiede una password per le app quando la 2FA è attiva.

Aggiungi un servizio di riserva, così un servizio guasto non blocca i tuoi moduli mentre lo sistemi.

Le email hanno un aspetto sbagliato

• Stili mancanti in Gmail o Outlook → attiva CSS inline al salvataggio nelle Impostazioni del modello.
• Testo tagliato con «Visualizza intero messaggio» → l’email supera ~100 kB; rimuovi le immagini inline o gli stili pesanti.
• <b> letterale nell’email → il valore è stato sottoposto a escaping. Usa un parametro html se ti serve davvero del markup (vedi escaping).
• Date nella lingua o nel fuso orario sbagliati → imposta la lingua del modello e il fuso orario dell’organizzazione, oppure passa timeZone= a formatDate.

Ancora bloccato?

Scrivi a support@frontmail.dev indicando il message_id (oppure il code e l’ora dell’errore). Non includere mai la tua chiave privata.