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.0.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.0.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
    Mailer 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"));
    }
}

Extension Configuration Reference

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

Configuration property

Type

Default

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

The Mailpit container image to use.

Environment variable: QUARKUS_MAILPIT_IMAGE_NAME

string

axllent/mailpit

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

Environment variable: QUARKUS_MAILPIT_VERBOSE

boolean

true