The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Sending emails using SMTP

This guide demonstrates how your Quarkus application can send emails using an SMTP server. This is a getting started guide. Check the Quarkus Mailer Reference documentation for more complete explanation about the mailer and its usage.

先决条件

完成这个指南,你需要:

  • 大概15分钟

  • 编辑器

  • JDK 17+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.9.9

  • 如果你愿意的话,还可以选择使用Quarkus CLI

  • 如果你想构建原生可执行程序,可以选择安装Mandrel或者GraalVM,并正确配置(或者使用Docker在容器中进行构建)

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

  • cURL

应用结构

In this guide, we will build an application:

  1. exposing an HTTP endpoint,

  2. sending email when the endpoint receives an HTTP request.

The application will demonstrate how to send emails using the imperative and reactive mailer APIs.

Attachments, inlined attachments, templating, testing and more advanced configuration are covered in the Mailer Reference documentation.

解决方案

我们建议您按照下一节的说明逐步创建应用程序。然而,您可以直接转到已完成的示例。

克隆 Git 仓库: git clone https://github.com/quarkusio/quarkus-quickstarts.git ,或下载一个 存档

The solution is located in the mailer-quickstart directory.

Create the Maven Project

首先,我们需要一个新的项目。使用以下命令创建一个新的项目:

CLI
quarkus create app org.acme:mailer-quickstart \
    --extension='rest,mailer,qute' \
    --no-code
cd mailer-quickstart

创建Grade项目,请添加 --gradle 或者 --gradle-kotlin-dsl 参数。

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:3.17.4:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=mailer-quickstart \
    -Dextensions='rest,mailer,qute' \
    -DnoCode
cd mailer-quickstart

创建Grade项目,请添加 -DbuildTool=gradle 或者 -DbuildTool=gradle-kotlin-dsl 参数。

For Windows users:

  • If using cmd, (don’t use backward slash \ and put everything on the same line)

  • If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=mailer-quickstart"

This command generates a Maven structure including the following extensions:

  • Quarkus REST (formerly RESTEasy Reactive) used to expose REST endpoints

  • Mailer so that we can send emails

  • Qute, our template engine

If you already have your Quarkus project configured, you can add the mailer extension to your project by running the following command in your project base directory:

CLI
quarkus extension add mailer
Maven
./mvnw quarkus:add-extension -Dextensions='mailer'
Gradle
./gradlew addExtension --extensions='mailer'

这将在你的 pom.xml 中添加以下内容:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-mailer</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-mailer")

Open the generated project in your IDE. In a terminal, navigate to the project and start your application in dev mode:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

Implement the HTTP endpoint

First, create the src/main/java/org/acme/MailResource.java file, with the following content:

package org.acme;

import io.quarkus.mailer.Mail;
import io.quarkus.mailer.Mailer;
import io.smallrye.common.annotation.Blocking;

import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

@Path("/mail")                                                          (1)
public class MailResource {

    @Inject Mailer mailer;                                              (2)

    @GET                                                                (3)
    @Blocking                                                           (4)
    public void sendEmail() {
        mailer.send(
                Mail.withText("quarkus@quarkus.io",                     (5)
                    "Ahoy from Quarkus",
                    "A simple email sent from a Quarkus application."
                )
        );
    }

}
1 Configure the root path of our HTTP endpoint
2 Inject the Mailer object managed by Quarkus
3 Create a method that will handle the HTTP GET request on /mail
4 Because we are using Quarkus REST and the imperative mailer, we need to add the @Blocking annotation. We will see later the reactive variant.
5 Create a Mail object by configuring the to recipient, the subject and body

The MailResource class implements the HTTP API exposed by our application. It handles GET request on `http://localhost:8080/mail.

So, if in another terminal, you run:

> curl http://localhost:8080/mail

You should see in the application log something like:

INFO  [quarkus-mailer] (executor-thread-0) Sending email Ahoy from Quarkus from null to [quarkus@quarkus.io], text body:
A simple email sent from a Quarkus application.
html body:
<empty>

As the application runs in dev mode, it simulates the sending of the emails. It prints it in the log, so you can check that what was about to be sent.

This section used the imperative mailer API. It blocks the caller thread until the mail is sent.

The Quarkus Mailpit extension is very handy for testing emails. It provides Dev Services for Mailpit, a nice UI for testing and debugging email sending.

Using the reactive mailer

The last section use the imperative mailer. Quarkus also offers a reactive API.

Mutiny

The reactive mailer uses Mutiny reactive types. If you are not familiar with Mutiny, check Mutiny - an intuitive reactive programming library.

In the same class, add:

@Inject
ReactiveMailer reactiveMailer;                          (1)

@GET
@Path("/reactive")                                      (2)
public Uni<Void> sendEmailUsingReactiveMailer() {       (3)
    return reactiveMailer.send(                         (4)
                Mail.withText("quarkus@quarkus.io",
                    "Ahoy from Quarkus",
                    "A simple email sent from a Quarkus application using the reactive API."
                )
        );
}
1 Inject the reactive mailer. The class to import is io.quarkus.mailer.reactive.ReactiveMailer.
2 Configure the path to handle GET request on /mail/reactive. Note that because we are using the reactive API, we don’t need @Blocking
3 The method returns a Uni<Void> which completes when the mail is sent. It does not block the caller thread.
4 The API is similar to the imperative one except that the send method returns a Uni<Void>.

Now, in your terminal, run

> curl http://localhost:8080/mail/reactive

You should see in the application log something like:

INFO  [quarkus-mailer] (vert.x-eventloop-thread-11) Sending email Ahoy from Quarkus from null to [quarkus@quarkus.io], text body:
A simple email sent from a Quarkus application using the reactive API.
html body:
<empty>

Configuring the mailer

It’s time to configure the mailer to not simulate the sending of the emails. The Quarkus mailer is using SMTP, so make sure you have access to an SMTP server.

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. See the configuration reference guide for details.

Configuration of popular mail services is covered in the reference guide.

Once you have configured the mailer, if you call the HTTP endpoint as shown above, you will send emails.

解决方案

Related content

On the same extensions

On the same topics