Testare l’invio email in Quarkus senza stress (né spam): benvenuti in Mailpit

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.

Recommended article

Maggio 7, 2025

Evitare la duplicazione del codice sfruttando le high-order function in JavaScript

Fabrizio Tedeschi

Backend

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:

1. inviare un’email tramite l’endpoint della tua app Quarkus
2. 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:

• Mailpit su GitHub
• Documentazione Mailpit
• Quarkus Mailer Extension
• Quarkiverse Mailpit