Quarkus - Sending emails

This guide demonstrates how your Quarkus application can send emails using an SMTP server.

Prerequisites

To complete this guide, you need:

  • less than 15 minutes

  • The SMTP hostname, port and credentials, and an email address

  • an IDE

  • JDK 1.8+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.5.3+

  • GraalVM installed if you want to run in native mode.

Architecture

In this guide, we are going to see how you can send emails from a Quarkus application. It covers simple emails, attachments, inlined attachments, the reactive and imperative APIs…​

Creating the Maven Project

Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:0.24.0:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=sending-email-quickstart \
    -Dextensions="mailer"

If you already have an existing project, add the mailer extension:

./mvnw quarkus:add-extensions -Dextensions="mailer"

Configuring the mailer

The Quarkus mailer is using SMTP. In the src/main/resources/application.properties file, you need to configure the host, port, username, password as well as the other configuration aspect. Note that the password can also be configured using system properties and environment variables.

Here is an example using sendgrid:

quarkus.mailer.from=test@quarkus.io
quarkus.mailer.host=smtp.sendgrid.net
quarkus.mailer.port=465
quarkus.mailer.ssl=true
quarkus.mailer.username=....
quarkus.mailer.password=....
For more information about the Mailer extension configuration please refer to the Configuration Reference.

Sending simple emails

In a JAX-RS resource, or in a bean, you can inject the mailer as follows:

@Inject
Mailer mailer;

@Inject
ReactiveMailer reactiveMailer;

There are 2 APIs:

  • io.quarkus.mailer.Mailer provides the imperative (blocking and synchronous) API;

  • io.quarkus.mailer.ReactiveMailer provides the reactive (non-blocking and asynchronous) API

The two APIs are equivalent feature-wise. Actually the Mailer implementation is built on top of the ReactiveMailer implementation.

To send a simple email, proceed as follows:

// Imperative API:
mailer.send(Mail.withText("to@acme.org", "A simple email from quarkus", "This is my body."));
// Reactive API:
CompletionStage<Void> stage = reactiveMailer.send(Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body."));

For example, you can use the Mailer in a JAX-RS endpoint as follows:

@GET
@Path("/simple")
public Response sendASimpleEmail() {
    mailer.send(Mail.withText("to@acme.org", "A simple email from quarkus", "This is my body"));
    return Response.accepted().build();
}

@GET
@Path("/async")
public CompletionStage<Response> sendASimpleEmailAsync() {
    return reactiveMailer.send(
            Mail.withText("to@acme.org", "A reactive email from quarkus", "This is my body"))
            .thenApply(x -> Response.accepted().build());
}

With such a JAX-RS resource, you can check that everything is working with:

curl http://localhost:8080/simple
curl http://localhost:8080/async

You can create new io.quarkus.mailer.Mail instances from the constructor or from the Mail.withText and Mail.withHtml helper methods. The Mail instance lets you add recipients (to, cc, or bcc), set the subject, headers, sender (from) address…​

You can also send several Mail objects in one call:

mailer.send(mail1, mail2, mail3);

Sending attachments

To send attachment, just use the addAttachment methods on the io.quarkus.mailer.Mail instance:

@GET
@Path("/attachment")
public Response sendEmailWithAttachment() {
    mailer.send(Mail.withText("to@acme.org", "An email from quarkus with attachment",
            "This is my body")
            .addAttachment("my-file.txt",
                "content of my file".getBytes(), "text/plain"));
    return Response.accepted().build();
}

Attachments can be created from raw bytes (as shown in the snippet) or files.

Sending HTML emails with inlined attachments

When sending HTML email, you can add inlined attachments. For example, you can send an image with your email, and this image will be displayed in the mail content. If you put the image file into resources folder, you should specify the full path to the file. "e.g." "META-INF/resources/quarkus-logo.png" otherwise quarkus will lookup in the root folder of the project

@GET
@Path("/html")
public Response sendingHTML() {
    String body = "<strong>Hello!</strong>" + "\n" +
        "<p>Here is an image for you: <img src=\"cid:my-image@quarkus.io\"/></p>" +
        "<p>Regards</p>";
    mailer.send(Mail.withHtml("to@acme.org", "An email in HTML", body)
        .addInlineAttachment("quarkus-logo.png",
            new File("quarkus-logo.png"),
            "image/png", "<my-image@quarkus.io>"));
    return Response.accepted().build();
}

Note the content-id format and reference. By spec, when you create the inline attachment, the content-id must be structured as follows: <id@domain>. If you don’t wrap your content-id between <>, it is automatically wrapped for you. When you want to reference your attachment, for instance in the src attribute, use cid:id@domain (without the < and >).

Testing email sending

Because it is very inconvenient to send emails during development and testing, you can set the quarkus.mailer.mock boolean configuration to true to not actually send emails but print them on stdout and collect them in a MockMailbox bean instead. This is the default if you are running Quarkus in DEV or TEST mode.

You can then write tests to verify that your emails were sent, for example, by a REST endpoint:

@QuarkusTest
class MailTest {

    private static final String TO = "foo@quarkus.io";

    @Inject
    MockMailbox mailbox;

    @BeforeEach
    void init() {
        mailbox.clear();
    }

    @Test
    void testTextMail() throws MessagingException, IOException {
        // call a REST endpoint that sends email
        given()
        .when()
        .get("/send-email")
        .then()
           .statusCode(202)
           .body(is("OK"));

        // verify that it was sent
        List<Mail> sent = mailbox.getMessagesSentTo(TO);
        assertThat(sent).hasSize(1);
        Mail actual = sent.get(0);
        assertThat(actual.getText()).contains("Wake up!");
        assertThat(actual.getSubject()).isEqualTo("Alarm!");

        assertThat(mailbox.getTotalMessagesSent()).isEqualTo(6);
    }
}

Gmail specific configuration

If you want to use the Gmail SMTP server, first create a dedicated password in Google Account > Security > App passwords or go to https://myaccount.google.com/apppasswords.

When done, you can configure your Quarkus application by adding the following properties to your application.properties:

With TLS:

quarkus.mailer.from=YOUREMAIL@gmail.com
quarkus.mailer.host=smtp.gmail.com
quarkus.mailer.port=587
quarkus.mailer.start-tls=REQUIRED
quarkus.mailer.username=YOUREMAIL@gmail.com
quarkus.mailer.password=YOURGENERATEDAPPLICATIONPASSWORD

Or with SSL:

quarkus.mailer.from=YOUREMAIL@gmail.com
quarkus.mailer.host=smtp.gmail.com
quarkus.mailer.port=465
quarkus.mailer.ssl=true
quarkus.mailer.username=YOUREMAIL@gmail.com
quarkus.mailer.password=YOURGENERATEDAPPLICATIONPASSWORD

Using SSL with native executables

Note that if you enable SSL for the mailer and you want to build a native executable, you will need to enable the SSL support. Please refer to the native-and-ssl-guide.html[Using SSL With Native Executables] guide for more information.

Using the underlying Vert.x Mail Client

The Quarkus Mailer is implemented on top of the Vert.x Mail Client, providing an asynchronous and non-blocking way to send emails. If you need fine control on how the mail is sent, for instance if you need to retrieve the message ids, you can inject the underlying client, and use it directly:

@Inject MailClient client;

Three API flavors are exposed:

  • the Axle client (io.vertx.axle.ext.mail.MailClient), using CompletionStage and Reactive Streams Publisher

  • the RX Java 2 client (io.vertx.reactivex.ext.mail.MailClient)

  • the bare client (io.vertx.ext.mail.MailClient)

Check the Using Vert.x guide for further details about these different APIs and how to select the most suitable for you.

The retrieved MailClient is configured using the configuration key presented above. You can also create your own instance, and pass your own configuration.

Conclusion

This guide has shown how you can send emails from a Quarkus application. The mailer extension works in JVM and native mode.

Mailer Configuration Reference

Configuration property fixed at build time - ️ Configuration property overridable at runtime

Configuration property Type Default

quarkus.mailer.from

Configure the default from attribute. It’s the sender email address.

string

quarkus.mailer.mock

Enables the mock mode, not sending emails. The content of the emails is printed on the console. Disabled by default on PROD, enabled by default on DEV and TEST modes.

boolean

quarkus.mailer.bounce-address

Configures the default bounce email address.

string

quarkus.mailer.host

The SMTP host name.

string

localhost

quarkus.mailer.port

The SMTP port.

int

quarkus.mailer.username

The username.

string

quarkus.mailer.password

The password.

string

quarkus.mailer.ssl

Enables or disables the SSL on connect. false by default.

boolean

false

quarkus.mailer.trust-all

Set whether to trust all certificates on ssl connect the option is also applied to STARTTLS operation. false by default.

boolean

false

quarkus.mailer.max-pool-size

Configures the maximum allowed number of open connections to the mail server If not set the default is 10.

int

quarkus.mailer.own-host-name

The hostname to be used for HELO/EHLO and the Message-ID

string

quarkus.mailer.keep-alive

Set if connection pool is enabled, true by default. If the connection pooling is disabled, the max number of sockets is enforced nevertheless.

boolean

true

quarkus.mailer.disable-esmtp

Disable ESMTP. false by default. The RFC-1869 states that clients should always attempt EHLO as first command to determine if ESMTP is supported, if this returns an error code, HELO is tried to use the regular SMTP command.

boolean

false

quarkus.mailer.start-tls

Set the TLS security mode for the connection. Either DISABLED, OPTIONAL or REQUIRED.

string

quarkus.mailer.login

Set the login mode for the connection. Either DISABLED, OPTIONAL or REQUIRED

string

quarkus.mailer.auth-methods

Set the allowed auth methods. If defined, only these methods will be used, if the server supports them.

string

quarkus.mailer.key-store

Set the key store.

string

quarkus.mailer.key-store-password

Set the key store password.

string