Risoluzione dei problemi con l'email transazionale

Questo articolo illustra i problemi più comuni con l'email transazionale Flexmail — errori di autenticazione, problemi di recapitabilità e problemi dell'API o SMTP — e come affrontarli.

Errori di autenticazione e configurazione

L'API restituisce un errore 401 Unauthorized

L'ID account o il token di accesso personale sono errati. Verificarli attentamente:

• Il nome utente è l'ID account numerico, non l'indirizzo email.
• La password è un token di accesso personale creato in Impostazioni > API > Token di accesso personali, non la password di accesso a Flexmail.
• Assicurarsi che il token sia stato copiato per intero senza spazi finali o interruzioni di riga.
• In caso di dubbio, creare un nuovo token e riprovare.

La connessione SMTP fallisce o va in timeout

Verificare quanto segue:

• Si sta usando l'host submission.flexmail.eu, porta 587, con STARTTLS.
• Il server o l'ambiente di hosting consente connessioni in uscita sulla porta 587. Alcuni provider di hosting condiviso bloccano questa porta — contattare il provider per conferma.
• Le credenziali SMTP sono il nome utente e la password forniti da Flexmail quando ha attivato l'accesso SMTP. Sono separati dall'ID account e dal token di accesso personale, che vengono usati solo per l'API HTTP.
• L'indirizzo del mittente è verificato in Flexmail.

Indirizzo del mittente non verificato

Se si tenta di inviare da un indirizzo non verificato in Flexmail, l'invio verrà rifiutato. Andare su Impostazioni > Aggiungi o rimuovi mittenti, aggiungere l'indirizzo e cliccare sul link di verifica nell'email inviata da Flexmail.

Problemi di recapitabilità

Le email finiscono nello spam

Il posizionamento nello spam delle email transazionali è quasi sempre causato da una di queste tre cose:

• L'autenticazione email non è configurata o è errata. Verificare che i record SPF, DKIM e DMARC siano presenti per il dominio di invio. Anche un solo record mancante o configurato in modo errato può causare il posizionamento nello spam. Le istruzioni di configurazione sono nella documentazione API su email-api.flexmail.eu/documentation sotto Autenticazione email.
• La reputazione del mittente è bassa. Se il dominio o l'IP ha una storia di reclami spam o tassi di bounce elevati — da qualsiasi piattaforma di invio, non solo Flexmail — i provider di posta in arrivo potrebbero instradare l'email nello spam. Si consulti "Capire la reputazione del mittente" per come valutare e migliorare la reputazione.
• Il contenuto attiva i filtri spam. Determinati pattern nella riga dell'oggetto, link eccessivi o email ricche di immagini con poco testo possono attivare i filtri spam. Testare le email transazionali con uno strumento come Mail-Tester (mail-tester.com) per identificare problemi a livello di contenuto.

Le email non arrivano affatto

Se l'API restituisce una risposta di successo ma l'email non arriva:

• Verificare gli eventi webhook (se configurati) — un evento di bounce subito dopo l'invio indica un errore di consegna.
• Verificare che l'indirizzo del destinatario esista e sia scritto correttamente.
• Chiedere al destinatario di controllare la cartella spam.
• Verificare se il dominio del destinatario ha una policy DMARC restrittiva — senza DKIM configurato correttamente, le email potrebbero essere rifiutate silenziosamente.
• Alcuni sistemi email aziendali rifiutano le email da mittenti nuovi o con bassa reputazione. Provare a inviare a un indirizzo Gmail o Outlook personale per escludere filtri lato destinatario.

Tasso di bounce elevato

Un tasso di bounce elevato sulle email transazionali di solito significa che si sta inviando a indirizzi inesistenti o non più attivi. Verificare il processo di raccolta degli indirizzi:

• Si sta validando il formato dell'indirizzo email al momento dell'inserimento?
• Si sta inviando un'email di conferma o verifica prima di fidarsi di un nuovo indirizzo?
• Si stanno rimuovendo tempestivamente gli indirizzi con hard bounce dal sistema?

Importante

Continuare a inviare a indirizzi con hard bounce danneggia la reputazione del mittente ad ogni invio. Configurare la gestione dei webhook per gli eventi di bounce e sopprimere immediatamente quegli indirizzi nel sistema.

Errori API e di integrazione

L'API restituisce un errore 422 o 400

Questi errori indicano un problema con la richiesta — un campo obbligatorio mancante, un valore di parametro non valido o un corpo della richiesta malformato. Controllare il messaggio di errore nel corpo della risposta per i dettagli. La documentazione API su email-api.flexmail.eu/documentation elenca tutti i parametri obbligatori e facoltativi per ogni endpoint.

L'API restituisce un errore 429 Too Many Requests

Si è raggiunto un limite di frequenza. La documentazione API specifica i limiti di frequenza per il livello di abbonamento. Aggiungere logica di retry con backoff esponenziale all'integrazione per gestirlo in modo elegante.

Le variabili del template non vengono sostituite

Se il testo segnaposto appare letteralmente nell'email consegnata:

• Verificare di passare correttamente i valori delle variabili nella richiesta API. Si consulti la sezione Template della documentazione API per la struttura esatta dei parametri.
• Verificare che la sintassi del segnaposto nel template corrisponda esattamente a ciò che l'API si aspetta.
• Assicurarsi di fare riferimento all'ID template corretto nella chiamata API.

I webhook non arrivano

Se l'endpoint webhook non riceve eventi:

• Confermare che l'endpoint sia accessibile pubblicamente tramite HTTPS.
• Verificare che l'endpoint restituisca rapidamente una risposta 2xx — un endpoint lento o che non risponde farà considerare la consegna fallita a Flexmail.
• Controllare i log del server per le richieste POST in arrivo per escludere problemi di routing o firewall.
• Verificare che l'URL dell'endpoint webhook sia registrato correttamente nell'API.

Ottenere assistenza

Se si è verificata la situazione descritta sopra e il problema persiste, contattare il team di supporto Flexmail all'indirizzo support@flexmail.eu. Includere nel messaggio le seguenti informazioni per velocizzare la diagnosi:

• L'ID messaggio di un invio fallito (dalla risposta API o dai log).
• L'indirizzo email del destinatario con cui si è testato.
• Il messaggio di errore o il corpo della risposta dell'API, se applicabile.
• Il risultato di uno strumento di verifica dell'autenticazione email come MXToolbox o Mail-Tester.

Passi successivi

• Si consulti "Iniziare con l'API transazionale" per la sequenza di configurazione corretta.
• Si consulti "Capire la reputazione del mittente" per come valutare e proteggere la reputazione di invio.
• Rivedere la documentazione API su email-api.flexmail.eu/documentation per i codici di errore e i dettagli sui limiti di frequenza.