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.3.0</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.3.0</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:
You can also inspect the container image that was started under Dev Services:
Click on the "Mailpit UI" link to then see the UI with all your captured e-mails.
Logging
You can view all of Mailpit’s container logs right in the DevUI log area to debug all messages and errors from Mailpit.
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"));
}
}Extension Configuration Reference
Configuration property fixed at build time - All other configuration properties are overridable at runtime
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: |
boolean |
|
The Mailpit container image to use. Environment variable: |
string |
|
Flag to control if verbose logging of Mailpit container is requested. Environment variable: |
boolean |
|
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: |
int |
|
Statically define the mapped HTTP port that the container user interface exposes Environment variable: |
int |