Quarkus Mailpit

A Quarkus extension that lets you utilize Mailpit as a Dev Service for the Quarkus Mailer enabling zero-config SMTP for testing or running in dev mode. Mailpit acts as an SMTP server, provides a modern web interface to view & test captured emails, and contains an API for automated integration testing.

Using this service has some obvious advantages when running in dev mode including but not limited to:

  • Verify e-mail and their content without a real mail server

  • Prevent accidentally sending a customer an email while developing

  • Use the REST API to verify contents of real send emails and not mocked mail

  • 12 Factor App: Backing services Treat backing services as attached resources

  • 12 Factor App: Dev/Prod Parity Keep development, staging, and production as similar as possible

Installation

If you want to use this extension, you need to add the io.quarkiverse.mailpit:quarkus-mailpit extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>io.quarkiverse.mailpit</groupId>
    <artifactId>quarkus-mailpit</artifactId>
    <version>1.6.1</version>
</dependency>

<!-- If you want to use test framework to verify emails also -->
<dependency>
   <groupId>io.quarkiverse.mailpit</groupId>
   <artifactId>quarkus-mailpit-testing</artifactId>
   <version>1.6.1</version>
   <scope>test</scope>
</dependency>

Usage

Now that you configured your POM to use the service in quarkus:dev mode it will automatically wire up the mail server to send all emails to Mailpit. This will enable the Mailer to send real e-mails that will be intercepted by Mailpit.

Next, add some code that sends an e-mail…​

@Path("/superheroes")
@ApplicationScoped
public class SuperheroResource {
    @Inject
    Mailer mailer;

    @GET
    public String villainAlert() {
        Mail m = new Mail();
        m.setFrom("admin@hallofjustice.net");
        m.setTo(List.of("superheroes@quarkus.io"));
        m.setText("Lex Luthor has been seen in Gotham City!");
        m.setSubject("WARNING: Super Villain Alert");
        mailer.send(m);

        return "Superheroes alerted!";
    }
}

Simply run your application with mvn quarkus:dev and execute your code. Browse to the Dev UI to see this Mailpit card under Extensions:

Mailpit DevUI Card

You can also inspect the container image that was started under Dev Services:

Mailpit Dev Service

Click on the "Mailpit UI" link to then see the UI with all your captured e-mails.

Mailpit User Interface

Logging

You can view all of Mailpit’s container logs right in the DevUI log area to debug all messages and errors from Mailpit.

Mailpit Logs

Testing

Mailpit ships with REST APIs that allow you to query, inspect, mark read, or delete e-mails from the running instance. This extension has wrapped up the API nicely and allows you to query Mailpit to check the emails were sent.

@QuarkusTest
@WithMailbox
public class MailpitResourceTest {

    @InjectMailbox
    Mailbox mailbox;

    @AfterEach
    public void afterEach() throws ApiException {
        // clear the mailbox after each test run if you prefer
        mailbox.clear();
    }

    @Test
    public void testAlert() throws ApiException {
        given()
                .when().get("/mailpit/alert")
                .then()
                .statusCode(200)
                .body(is("Superheroes alerted!!"));

        // look up the mail and assert it
        Message message = mailbox.findFirst("admin@hallofjustice.net");
        assertThat(message, notNullValue());
        assertThat(message.getTo().get(0).getAddress(), is("superheroes@quarkus.io"));
        assertThat(message.getSubject(), is("WARNING: Super Villain Alert"));
        assertThat(message.getText(), is("Lex Luthor has been seen in Gotham City!\r\n"));
    }
}

Chaos Testing

Mailpit provides chaos testing capabilities that allow you to simulate various email delivery scenarios. This is particularly useful for testing how your application handles email delivery failures.

You can configure chaos testing through the Mailpit UI and API. The extension provides a convenient way to set up chaos testing in your tests:

quarkus.mailpit.enable-chaos=true
@QuarkusTest
@WithMailbox
public class MailpitChaosTest {
    @InjectMailbox
    Mailbox mailbox;
    @Test
    public void testChaos() throws ApiException {
        // Arrange - Configure chaos testing - set errorCode and probability for authentication, sender and recipient error triggers
        mailbox.setChaos(
                ChaosConfig.builder()
                        .authentication(451, 0)
                        .sender(451, 0)
                        .recipient(550, 100)
                        .build()
        );

        // Act - Your code that sends email goes here...

        // Assert - Make assertions on errors

        // Stack traces may contain strings like the following
        // "recipient address not accepted"
        // "550 Chaos recipient error"
    }
    @AfterEach
    public void cleanup() throws ApiException {
        // Don't forget to disable chaos testing after the test
        mailbox.disableChaos();
    }
}

The chaos configuration supports the following options:

Mailpit has three types of triggers in which chaos can be introduced:

  • Checking the sender is valid.

  • Checking the recipient is valid.

  • Checking the authentication is valid.

Authentication chaos testing requires that authentication is set up in MailPit and is currently not configurable by quarkus-mailpit.

Each trigger requires the following parameters are filled:

  • errorCode - is an integer from 400 to 599 - the returned SMTP error code when an error triggers

  • probability - is an an integer from 0 to 100 - how likely this error will trigger

This feature is particularly useful for:

  • Testing error handling in your email sending code

  • Simulating SMTP server failures

  • Ensuring your application gracefully handles email delivery issues

  • Testing retry mechanisms in your email infrastructure

Extension Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.mailpit.enabled

If Dev Services for Mailpit has been explicitly enabled or disabled. Dev Services are generally enabled by default, unless there is an existing configuration present.

Environment variable: QUARKUS_MAILPIT_ENABLED

boolean

true

quarkus.mailpit.image-name

The Mailpit container image to use.

Environment variable: QUARKUS_MAILPIT_IMAGE_NAME

string

axllent/mailpit

quarkus.mailpit.verbose

Flag to control if verbose logging of Mailpit container is requested.

Environment variable: QUARKUS_MAILPIT_VERBOSE

boolean

true

quarkus.mailpit.enable-chaos

Flag to control if chaos testing is requested.

Environment variable: QUARKUS_MAILPIT_ENABLE_CHAOS

boolean

false

quarkus.mailpit.max-messages

Although mailpit can easily handling tens of thousands of emails, it will automatically prune old messages by default keeping the most recent 500 emails. Default is 500, or set to 0 to disable entirely.

Environment variable: QUARKUS_MAILPIT_MAX_MESSAGES

int

500

quarkus.mailpit.mapped-http-port

Statically define the mapped HTTP port that the container user interface exposes

Environment variable: QUARKUS_MAILPIT_MAPPED_HTTP_PORT

int