Mail Pilot

Mail Pilot sostituisce la funzione mail di default di WordPress con il servizio di email transazionali di Brevo. Indirizza ogni messaggio in uscita attraverso l’API HTTP di Brevo (con fallback automatico su SMTP), registra ogni invio in un log ricercabile e verifica in tempo reale la consegna tramite webhook. Il risultato è email transazionale affidabile e visibilità completa su ciò che il sito spedisce davvero.

Il plugin è pensato per chi gestisce siti e ha bisogno di essere sicuro che reset password, conferme d’ordine, risposte ai contact form, notifiche WooCommerce e le altre mail di sistema arrivino in inbox. Non aggiunge funzioni marketing o di campagna: lavora sul layer transazionale di WordPress.

Punti di forza

• Consegna tramite API Brevo. Tutte le chiamate wp_mail() passano per l’API transazionale di Brevo, che migliora la deliverability rispetto al mail() di PHP.
• Fallback SMTP automatico. Se la chiamata API non va a buon fine (per esempio per un problema di rete temporaneo), il messaggio viene ritentato via SMTP Brevo, così la mail non si perde.
• Log email ricercabile. Ogni messaggio in uscita viene memorizzato con destinatario, oggetto, corpo, header, stato e timestamp. Il log si filtra per stato e si cerca per destinatario o oggetto.
• Tracking di aperture e click. Quando abilitato, Brevo inietta un pixel di tracking e riscrive i link, così il plugin può registrare aperture e click per ciascun messaggio.
• Verifica della consegna via webhook. Brevo rimanda gli eventi delivered, hard bounce, soft bounce, blocked, deferred e spam complaint, che Mail Pilot riflette nell’entry di log.
• Pulizia automatica. Un task cron di WordPress rimuove le righe di log vecchie secondo un periodo di retention configurabile, così il database non cresce a tempo indeterminato.
• Prevenzione conflitti. Mail Pilot rileva altri plugin SMTP (in particolare WP Mail SMTP) e avvisa quando entrambi proverebbero a sovrascrivere wp_mail(), prevenendo mail duplicate o perse.
• Resend e test. Qualsiasi messaggio loggato può essere rispedito dalla pagina admin, e uno strumento di test email integrato verifica la configurazione.

Requisiti

• WordPress 6.0 o superiore.
• PHP 7.4 o superiore (consigliato PHP 8.1+).
• Un account Brevo (il piano free copre i volumi transazionali tipici).
• Un indirizzo email mittente verificato oppure un dominio di invio autenticato in Brevo.
• Accesso HTTPS in uscita dal server WordPress verso api.brevo.com sulla porta 443, più la porta 587 per il fallback SMTP.
• Il cron di WordPress (wp-cron) abilitato, oppure un cron di sistema che colpisca wp-cron.php, per far girare la pulizia su schedule.

Installazione

1. Scarica l’ultimo mail-pilot.zip dal tuo account o dalla pagina di download.
2. Nell’admin WordPress, apri Plugin → Aggiungi nuovo → Carica plugin.
3. Scegli il file ZIP, clicca Installa ora, poi Attiva plugin.
4. Dopo l’attivazione compare una nuova voce sotto Mail Pilot → Impostazioni. Il plugin aggiunge anche un menu top-level Mail Pilot che dà accesso diretto a log e statistiche.

All’attivazione Mail Pilot crea la sua tabella custom ({prefix}_mail_pilot_logs) per memorizzare il log delle mail. Nessuna email viene intercettata finché non salvi l’API key e non abiliti l’integrazione.

Configurazione

La configurazione si divide in tre aree: credenziali Brevo, identità mittente e opzioni operative per logging, tracking e retention. Tutte le impostazioni vivono sotto Mail Pilot → Impostazioni.

1. Crea un account Brevo e una API key

1. Registrati su brevo.com  se non hai ancora un account. Il piano free permette un volume generoso di email transazionali al giorno, sufficiente per la maggior parte dei siti piccoli e medi.
2. Accedi alla dashboard Brevo.
3. Apri il menu utente in alto a destra e scegli SMTP & API.
4. Seleziona la tab API Keys e clicca Generate a new API key.
5. Dai alla chiave un nome riconoscibile (per esempio wordpress-mail-pilot) e copia il valore generato. Brevo mostra il segreto una sola volta; conservalo in un posto sicuro.

2. Verifica un mittente

Brevo rifiuta di inviare messaggi da un mittente non verificato. Prima di salvare la configurazione in WordPress, assicurati che l’indirizzo mittente o l’intero dominio sia verificato in Brevo:

• Per un singolo indirizzo, apri Senders, Domains & Dedicated IPs → Senders in Brevo, aggiungi l’indirizzo e confermalo tramite l’email che Brevo invia.
• Per un dominio, apri Senders, Domains & Dedicated IPs → Domains e segui il wizard che ti chiede di aggiungere i record DNS SPF, DKIM e DMARC. L’autenticazione del dominio dà la migliore deliverability ed è fortemente consigliata sui siti in produzione.

3. Inserisci le credenziali in WordPress

1. Apri Mail Pilot → Impostazioni nell’admin WordPress. La pagina è divisa in tre tab — Generale, Logging e Avanzate — ma credenziali e mailer di test stanno tutti nella tab Generale.
2. (Opzionale) Nella card Licenza in cima, incolla la tua chiave PILOT-XXXX-XXXX-XXXX-XXXX e premi Verifica & Salva per abilitare gli aggiornamenti automatici del plugin dal feed di rilascio GitHub.
3. Nella card Connection, lascia Mail Provider su Brevo (l’unico provider attualmente incluso).
4. Nella card Brevo Settings, incolla l’API key nel campo API Key e premi Test Connection per validare le credenziali contro l’API Brevo.
5. Nella card Sender imposta:
   • From Email sull’indirizzo verificato del passo precedente, e spunta Force From Email per sovrascrivere ogni mittente per-email impostato da altri plugin.
   • From Name sull’etichetta che deve apparire come autore dei messaggi in uscita, e spunta Force From Name per farlo vincere anche sugli override per-email.
6. Clicca Salva impostazioni.

Se vuoi mandare una rapida email di verifica, la card Test Email in fondo alla tab Generale espone un campo Send To e un pulsante Send Test.

4. Invia un’email di test

Sotto la sezione credenziali, il form Send test email ti permette di verificare la configurazione end-to-end:

1. Inserisci l’indirizzo di destinazione (la tua casella è una buona scelta).
2. Clicca Send test email.
3. Il plugin mostra subito un messaggio di successo o errore, e il messaggio appare nel log in pochi secondi.

Se il messaggio di test arriva in inbox, l’integrazione API funziona. Se non arriva in un paio di minuti, apri la entry di log e controlla i dettagli della risposta restituita da Brevo, poi consulta la sezione Troubleshooting più sotto.

5. Configura il webhook di consegna

Gli eventi di apertura, click e consegna sono rispediti a WordPress da Brevo tramite un webhook. Configurarlo è opzionale ma consigliato: senza, il log mostrerà solo che il messaggio è stato accettato da Brevo, non se è stato effettivamente consegnato, bounciato o aperto.

1. In Mail Pilot, copia il Webhook URL mostrato nella pagina impostazioni. Punta all’endpoint REST https://<tuo-sito>/wp-json/mail-pilot/v1/webhook.
2. Nella dashboard Brevo, apri Transactional → Settings → Webhook e clicca Add a new webhook.
3. Incolla l’URL nel campo URL to call.
4. Seleziona gli eventi da riportare. Il set consigliato è:
   • Sent
   • Delivered
   • Hard bounce
   • Soft bounce
   • Blocked
   • Spam (complaint)
   • Opened (solo se il tracking aperture è abilitato)
   • Clicked (solo se il tracking click è abilitato)
5. Salva il webhook.

Brevo inizierà subito a postare aggiornamenti di stato a WordPress. La tabella di log aggiorna la colonna stato man mano che gli eventi arrivano.

6. Tracking, retention e pulizia

Le tab Logging e Avanzate della pagina impostazioni espongono le opzioni operative:

• Enable open tracking. Quando attivo, Brevo inserisce un pixel di tracking 1x1 nel body HTML. Il pixel viene caricato dal mail client del destinatario, e questo conta come apertura.
• Enable click tracking. Quando attivo, i link nelle email HTML vengono riscritti puntando a un redirector Brevo che registra il click e poi inoltra l’utente all’URL originale.
• Log retention (giorni). Numero di giorni dopo i quali la pulizia rimuove le entry del log. Default: 30 giorni. Imposta 0 per tenerle per sempre (sconsigliato su siti molto trafficati).
• Cleanup schedule. Frequenza del cron event di WordPress che pota il log. Default: giornaliera.
• Log message body. Quando off, viene memorizzato solo il metadata (destinatario, oggetto, stato), riducendo lo spazio su DB ed evitando di archiviare il corpo di mail sensibili come i reset password.

Clicca Salva modifiche per applicare.

Utilizzo

Una volta abilitata l’integrazione, Mail Pilot lavora in modo trasparente. Ogni chiamata a wp_mail() fatta dal core WordPress, dai temi o dai plugin viene intercettata e reindirizzata su Brevo. Non serve cambiare codice in WooCommerce, Contact Form 7, WPForms, BuddyPress o qualsiasi altro plugin che usi l’API mail standard di WordPress.

La dashboard

Il menu top-level Mail Pilot apre una dashboard che riassume l’attività mail nel periodo selezionato. Un range picker in alto alterna tra 7 giorni, 14 giorni e 30 giorni, e sei card KPI in cima alla pagina mostrano Totale inviate, Consegnate (con tasso di consegna %), Fallite (con tasso di fallimento %), Bouncedeggiate, Aperture (con tasso di apertura %) e Click. I numeri si aggiornano man mano che arrivano gli eventi webhook.

Sotto i KPI la dashboard mostra cinque grafici live alimentati dal log del plugin:

• Email Volume — area stacked giornaliera dei messaggi delivered, blocked e bounced.
• Delivery Status — donut con la distribuzione degli stessi tre stati nel periodo selezionato.
• Opens & Clicks — line chart giornaliero di aperture e click unici.
• Top Sources — bar chart orizzontale dei plugin/temi che generano più email, derivato dal call site registrato a ogni invio.
• Sending Hours — istogramma orario di quando le email lasciano il sito vs quando Brevo le dispatcha, utile per individuare cron storm.

In fondo alla pagina, una card Brevo Account mostra lo stato live del tuo account Brevo: l’email connessa, il saldo crediti corrente, e contatori per Requests, Delivered, Opens, Clicks, Hard bounces, Soft bounces, Blocked e Spam reports su tutti i canali di invio (API, SMTP relay e software esterni).

Il log delle email

La schermata Email Log (Mail Pilot → Email Log) elenca ogni messaggio processato dal plugin, dal più recente, con un dropdown di azioni bulk, un filtro di stato, una casella di ricerca testuale e un’azione View per riga. Ogni riga mostra:

• L’indirizzo destinatario (o il primo se ne sono presenti più di uno).
• L’oggetto.
• Lo stato corrente: queued, sent, delivered, opened, clicked, soft-bounce, hard-bounce, blocked, spam o error.
• Il timestamp dell’ultimo cambio di stato.
• Il Brevo message ID (utile per correlare la entry con i log di Brevo).

Usa la casella di ricerca sopra la tabella per filtrare per destinatario o oggetto, o il dropdown di stato per mostrare solo i messaggi in errore. Cliccando una riga si apre la vista di dettaglio, che espone:

• Header completi e corpo del messaggio (se il body logging è attivo).
• Lista dei destinatari (To, Cc, Bcc).
• Ogni evento tracciato con il proprio timestamp.
• La risposta Brevo grezza, utile per richieste di supporto.

Dalla vista di dettaglio puoi cliccare Resend per riprovare il messaggio invariato, o Copy per usarlo come partenza per una nuova mail di test.

Widget nella dashboard di WordPress

Mail Pilot registra un widget sulla Dashboard standard (la pagina che WordPress apre al login). Il widget riproduce in piccolo la dashboard del plugin, così individui anomalie di consegna senza entrare nel menu Mail Pilot.

Il widget espone un range picker Ultimi 7 / 14 / 30 giorni, un line chart Email Volume (Delivered / Failed / Bounced) e un footer Brevo con il saldo crediti corrente e i contatori di Requests, Delivered, Failed, Bounced, Opens e Clicks. Un link View Full Log nell’header apre la pagina Email Log.

Il widget è opt-in: accendilo o spegnilo sotto Mail Pilot → Impostazioni → Avanzate → Dashboard Widget.

Convivenza con altri plugin

Mail Pilot rimpiazza l’implementazione di default di wp_mail() con la propria estensione PHPMailer. Di conseguenza è incompatibile con ogni altro plugin che fa la stessa cosa, inclusi WP Mail SMTP, Easy WP SMTP, Post SMTP, FluentSMTP e simili. Il plugin rileva i più comuni e mostra un admin notice chiedendoti di scegliere un mailer. La strada consigliata è disattivare l’altro plugin SMTP e, se serve, importare le sue credenziali in Mail Pilot.

WooCommerce, BuddyPress, WPForms, Contact Form 7, Easy Digital Downloads e le notifiche core di WordPress continuano a funzionare senza modifiche: passano tutti per wp_mail() e quindi vengono catturati automaticamente da Mail Pilot.

FAQ

Mail Pilot sostituisce solo le email transazionali o anche le campagne marketing? Gestisce solo l’email transazionale, cioè tutto ciò che passa per wp_mail() di WordPress. Le campagne marketing create nella dashboard Brevo sono gestite lì e non sono visibili nel log di Mail Pilot.

Devo pagare Brevo? No. Il piano free di Brevo include attualmente una quota giornaliera di email transazionali che copre la maggior parte dei siti piccoli e medi. Se il volume cresce, puoi passare a un piano a pagamento dalla dashboard Brevo senza reinstallare il plugin.

Posso usare contemporaneamente WP Mail SMTP e Mail Pilot? No. Solo un plugin per volta può fare override di wp_mail(); farne girare due in parallelo porta a invii duplicati, messaggi persi o errori PHP. Disattiva l’altro plugin SMTP prima di abilitare Mail Pilot.

I corpi dei messaggi vengono memorizzati nel database? Solo se Log message body è abilitato nelle impostazioni. Con l’opzione disattivata, il log tiene destinatario, oggetto, header e stato ma non il corpo, ed è la scelta preferibile sui siti che inviano reset password o altri contenuti sensibili.

Il tracking aperture funziona con tutti i mail client? Il tracking aperture dipende dal fatto che il destinatario carichi le immagini remote nel mail client. Molti client aziendali e Apple Mail Privacy Protection bloccano o pre-fetchano il pixel, quindi i tassi di apertura sono da leggere come una soglia inferiore (o superiore), non come dato esatto.

Il plugin supporta più indirizzi mittente? Il mittente di default è configurato globalmente. Plugin o codice che passano un header From: esplicito a wp_mail() useranno quell’indirizzo, purché sia verificato in Brevo. Gli indirizzi non verificati sono rifiutati dall’API.

Posso esportare il log? Sì. La schermata del log ha un pulsante Export CSV che esporta la vista filtrata corrente. L’export contiene destinatario, oggetto, stato, timestamp e Brevo message ID.

Dove sono memorizzati i dati? I log sono memorizzati in una tabella custom chiamata {prefix}_mail_pilot_logs nel database WordPress. Le impostazioni stanno nella tabella options standard. Nulla viene mandato a terze parti oltre a Brevo stesso.

Mail Pilot è compatibile con multisite? Sì. Ogni sito di un network multisite ha le proprie impostazioni, la propria tabella di log e la propria API key Brevo. Il plugin può anche essere attivato a livello network.

Troubleshooting

La pagina impostazioni mostra “API key rejected”. Ricopia la chiave da Brevo, attento a non includere spazi all’inizio o alla fine. Verifica che la chiave non sia stata revocata o ridotta di scope nella dashboard Brevo. Le chiavi create per l’API v2 potrebbero non funzionare; genera una chiave v3 dalla tab API Keys.

Le email di test risultano inviate ma non arrivano mai. Apri la entry di log per il messaggio di test e controlla le sezioni Status e Brevo response. I casi più comuni sono:

• Il destinatario è nella suppression list di Brevo (bounce o disiscrizione precedente). Rimuovi l’indirizzo da Contacts → Suppressed contacts in Brevo.
• Il mittente o il dominio di invio non è verificato, quindi Brevo accetta la richiesta ma blocca il messaggio.
• Il provider del destinatario ha segnato il messaggio come spam. Controlla la cartella spam e rivedi SPF, DKIM e DMARC del dominio di invio.

Gli eventi webhook non arrivano mai al log. Verifica che l’URL webhook salvato in Brevo coincida con quello mostrato nella pagina impostazioni di Mail Pilot, protocollo (https) e sottodirectory inclusi. WordPress deve essere raggiungibile dalla rete pubblica; i webhook non possono essere consegnati a un sito dietro VPN o a localhost. Se usi un security plugin o un WAF, assicurati che le richieste a /wp-json/mail-pilot/v1/webhook non vengano bloccate.

Le entry di log vecchie non vengono cancellate. La pulizia è triggerata dal cron di WordPress. Se il sito ha pochissimo traffico, il cron potrebbe non scattare abbastanza spesso; configura un cron di sistema che chiami wp-cron.php ogni ora. Puoi anche triggerare una pulizia manuale con il pulsante Run cleanup now in fondo alla pagina impostazioni.

Le email di un plugin specifico non vengono indirizzate a Brevo. Controlla se quel plugin invia mail tramite una propria implementazione SMTP invece di wp_mail(). I plugin che bypassano wp_mail() non possono essere intercettati; consulta la loro documentazione per puntarli alle stesse credenziali Brevo, o disabilita il loro mailer custom.

Passare a Mail Pilot ha cambiato l’indirizzo mittente. Il mittente configurato in Mail Pilot sovrascrive quello che WordPress userebbe altrimenti. Per mantenere un “From” per-plugin, assicurati che quel plugin imposti l’header From: esplicitamente quando chiama wp_mail(); altrimenti aggiorna il mittente globale in Mail Pilot → Impostazioni sul valore desiderato.