Quando sviluppiamo applicazioni che inviano email, uno dei problemi più comuni è: come testare tutto senza inviare messaggi reali ai nostri utenti (o peggio, al nostro capo)?
In questo articolo ti presento Mailpit, uno strumento moderno, open source e facilissimo da usare per testare l’invio email in ambienti di sviluppo. Lo combineremo con Quarkus, il framework Java pensato per il cloud, per vedere quanto può essere semplice simulare un server SMTP e validare le nostre logiche di email.
Cos’è Mailpit
Mailpit è un server SMTP (Simple Mail Transfer Protocol), progettato per intercettare le email inviate dalle applicazioni e mostrarle in una comoda interfaccia web. Le email non vengono recapitate realmente, ma archiviate in una casella di posta virtuale visibile su browser.
È ideale per testare:
- contenuto HTML
- allegati
- encoding
- email in diverse lingue
- template dinamici
Sostituisce strumenti come MailHog, con una UI più moderna e feature avanzate, tra cui una REST API utile per automazione e test end-to-end.
Perché usarlo con Quarkus?
Quarkus offre l’estensione ufficiale quarkus-mailer per inviare email ma durante lo sviluppo, non vogliamo rischiare di inviare email reali.
Ecco dove entra in gioco Mailpit: configurando Quarkus per inviare email verso Mailpit, possiamo sviluppare in piena sicurezza, visualizzando le email inviate in tempo reale.
Come integrare Mailpit con Quarkus
Il primo passo prevede l’avvio del servizio Mailpit. Esistono modalità diverse di start ma in questo caso useremo la via tramite container usando il comando a seguire.
# Usando il comando docker
docker run --rm -p 1025:1025 -p 8025:8025 axllent/mailpit
# Usando il comando podman
podman run --rm -p 1025:1025 -p 8025:8025 axllent/mailpitCode language: Bash (bash)Avviando il container di Mailpit, avremo in listen il servizio SMTP sulla porta 1025 e la WebUI sulla porta 8025.
Il secondo passo prevede la configurazione di Quarkus che consiste nell’aggiungere l’estensione quarkus-mailer e la configurazione del servizio SMTP attraverso il file application.properties.
# Aggiunta dell'estensione Quarkus Mailer al progetto
./mvnw quarkus:add-extension -Dextensions="mailer"Code language: PHP (php)A seguire la configurazione di Quarkus Mailer.
quarkus.mailer.from=no-reply@example.com
quarkus.mailer.host=localhost
quarkus.mailer.port=1025
quarkus.mailer.mock=false
quarkus.mailer.start-tls=disabledCode language: Properties (properties)Il terzo step prevede l’invio email. A seguire un esempio minimale d’invio email tramite un semplice servizio JAX-RS.
@Path("/send")
public class MailResource {
@Inject
Mailer mailer;
@GET
public String sendEmail() {
mailer.send(
Mail.withText("test@example.com", "Ciao da Quarkus!",
"Questa è una email di test.")
);
return "Email inviata!";
}
}Code language: CSS (css)Una volta avviata l’applicazione Quarkus (in modalità dev) con il comando ./mvnw quarkus:dev, sarà possibile eseguire un test d’invio email usando il comando a seguire.
# Invio email di prova chiamando la risorsa JAX-RS mappata su /send
curl http://localhost:8080/send
# La risposta attesa deve essere Email inviata!Code language: PHP (php)Accedendo alla WebUI di Mailpit, dovreste vedere l’email appena inviata, così come mostrato dalla figura a seguire.
Test automatizzati con Mailpit
Uno dei punti di forza di Mailpit è la REST API che consente di interrogare le email ricevute. Questo lo rende perfetto per test end-to-end o integrazioni automatizzate.
Potremmo per esempio scrivere un test d’integrazione che usi Rest Assured per:
- inviare un’email tramite l’endpoint della tua app Quarkus
- interrogare l’API di Mailpit per verificarne il contenuto
A seguire il codice del test d’integrazione implementato tramite la classe EmailIntegrationTest.
@QuarkusTest
class EmailIntegrationTest {
@Test
void shouldSendEmailAndVerifyInMailpit() throws InterruptedException {
// Step 1: Chiamata all'endpoint che invia l'email
RestAssured.get("/send").then().statusCode(200);
// Attendi che Mailpit riceva l'email
Thread.sleep(1000);
// Step 2: Recupera l'ultima email da Mailpit
var response = RestAssured
.get("http://localhost:8025/api/v1/messages")
.then()
.statusCode(200)
.extract()
.jsonPath();
var subject = response.getString("messages[0].Subject");
var body = response.getString("messages[0].Snippet");
assertThat(subject, containsString("Ciao da Quarkus"));
assertThat(body, containsString("email di test"));
}
}Code language: Java (java)Suggerimento: puoi anche pulire la casella prima di ogni test chiamando DELETE /api/v1/messages.
Con Quarkus, possiamo fare di più?
Certamente! Grazie all’estensione quarkus-mailpit, puoi integrare Mailpit nel tuo ambiente di sviluppo e test senza configurare nulla manualmente.
In breve, l’estensione:
- Avvia Mailpit in automatico durante i test
- Espone la Web UI su una porta casuale o configurabile
- Fornisce un’integrazione fluida per l’invio e l’ispezione delle email
Aggiungiamo l’estensione Mailpit
Al progetto occorre aggiungere l’estensione quarkus-mailpit e quarkus-mailpit-testing utilizzando sempre il comando maven così come mostrato a seguire.
# Aggiungi l'estensione quarkus-mailpit
./mvnw quarkus:add-extension -Dextensions="quarkus-mailpit"Code language: PHP (php)Aggiungiamo al progetto anche la dipendenza quarkus-mailpit-testing sul pom.xml che ci consentirà di eseguire i test d’integrazione sulle email.
<dependency>
<groupId>io.quarkiverse.mailpit</groupId>
<artifactId>quarkus-mailpit-testing</artifactId>
<version>1.6.2</version>
<scope>test</scope>
</dependency>Code language: HTML, XML (xml)
Dev Services: Mailpit pronto all’uso
L’estensione quarkus-mailpit supporta i Dev Services di Quarkus, consentendo l’avvio automatico di un’istanza di Mailpit durante lo sviluppo e i test, senza necessità di configurazioni manuali.
Quali sono i vantaggi principali?
- Nessuna configurazione manuale: Mailpit viene avviato automaticamente se non è già configurato un server SMTP.
- Interfaccia web accessibile: puoi visualizzare le email inviate tramite l’interfaccia web di Mailpit all’indirizzo
http://localhost:<dynamic-port>. - Sicurezza in fase di sviluppo: evita l’invio accidentale di email reali durante lo sviluppo.
- API REST per i test: accesso alle email inviate tramite API REST per facilitare i test automatizzati.
Come funziona?
Quando avvii l’applicazione in modalità di sviluppo (quarkus dev) o durante l’esecuzione dei test, Quarkus rileva automaticamente l’estensione quarkus-mailpit e avvia (per impostazione predefinita) un’istanza di Mailpit utilizzando Testcontainers . L’applicazione viene configurata per utilizzare questa istanza come server SMTP.
I test automatizzati
Il vero super potere dell’estensione quarkus-mailpit è che ti permette di verificare nei test automatizzati le email ricevute via API, senza dover lanciare nulla manualmente. A seguire un esempio di test end-to-end.
@QuarkusTest
@WithMailbox
class EmailIntegrationTest {
@InjectMailbox
Mailbox mailbox;
@AfterEach
public void afterEach() throws ApiException {
// svuota la casella di posta dopo ogni esecuzione di prova
mailbox.clear();
}
@Test
void shouldSendEmailAndVerifyInMailpit() throws InterruptedException {
// Step 1: Chiamata all'endpoint che invia l'email
RestAssured.get("/send").then().statusCode(200);
// Step 2: Look up email in Mailpit ed esecuzione delle asserzioni
Message message = mailbox.findFirst("no-reply@example.com");
assertThat(message, notNullValue());
assertThat(message.getTo().get(0).getAddress(), is("test@example.com"));
assertThat(message.getSubject(), is("Ciao da Quarkus!"));
assertThat(message.getText(), containsString("email di test"));
}
}Code language: JavaScript (javascript)Le API Mailbox sono fornite direttamente da quarkus-mailpit-testing e queste incapsulano tutte le chiamate REST a Mailpit.
Conclusioni
Testare le email non è mai stato così facile. Con Mailpit puoi concentrarti sulla logica della tua applicazione senza preoccuparti di configurare server SMTP esterni o di inviare accidentalmente email a utenti reali.
Mailpit è lo strumento perfetto per chi sviluppa email in ambienti dev e test. Con Quarkus, grazie all’estensione quarkus-mailpit, possiamo integrare il tutto in modo elegante, evitando configurazioni manuali e test fragili.
Che tu stia sviluppando un’applicazione, un microservizio o un backend per un sistema notifiche, ora puoi testare tutto senza rischi, senza invii reali e con massima automazione.
Tutto quanto descritto in questo articolo è disponibile nel repository GitHub:
👉 https://github.com/amusarra/quarkus-poc-mailpit
Il progetto è stato organizzato utilizzando tag Git step-n, ognuno dei quali rappresenta uno specifico passo dell’articolo. Questo ti permette di esplorare, testare e approfondire ogni fase in modo graduale e guidato, rendendo più semplice la comprensione e la riproduzione della soluzione.
Il progetto di esempio è stato realizzato con Quarkus 3.21.3 e Java 23, per sfruttare tutte le funzionalità moderne offerte dal framework.
Link utili:
