Sending emails using SMTP

本指南演示了您的 Quarkus 应用程序如何使用 SMTP 服务器发送电子邮件。这是快速入门指南。查看 Quarkus Mailer Reference documentation 以获得有关邮件发送器及其用法更完整的说明。

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.

Prerequisites

include::{includes}/prerequisites.adoc[] * SMTP 主机名、端口和凭据以及电子邮件地址 * cURL

Unresolved directive in mailer.adoc - include::{includes}/prerequisites.adoc[] * The SMTP hostname, port and credentials, and an email address * cURL

Architecture

在本指南中，我们将构建一个应用程序：

In this guide, we will build an application:

exposing an HTTP endpoint,
sending email when the endpoint receives an HTTP request.

应用程序将演示如何使用 imperative 和 reactive 邮件发送器 API 发送电子邮件。

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

Mailer Reference documentation 中涵盖了附件、内联附件、模板、测试和更多高级配置。

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

Solution

我们建议您遵循接下来的部分中的说明，按部就班地创建应用程序。然而，您可以直接跳到完成的示例。

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

克隆 Git 存储库： git clone {quickstarts-clone-url}，或下载 {quickstarts-archive-url}[存档]。

Clone the Git repository: git clone {quickstarts-clone-url}, or download an {quickstarts-archive-url}[archive].

解决方案位于 mailer-quickstart directory 中。

The solution is located in the mailer-quickstart directory.

Create the Maven Project

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

First, we need a new project. Create a new project with the following command:

Unresolved directive in mailer.adoc - include::{includes}/devtools/create-app.adoc[]

此命令生成一个包含以下扩展的 Maven 结构：

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

如果您已经配置了 Quarkus 项目，可以通过在项目基本目录中运行以下命令将 mailer 扩展添加到您的项目中：

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:

Unresolved directive in mailer.adoc - include::{includes}/devtools/extension-add.adoc[]

这会将以下内容添加到您的 pom.xml：

This will add the following to your pom.xml:

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-mailer</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-mailer")

在您的 IDE 中打开生成的项目。在终端中，导航到项目并在开发模式下启动您的应用程序：

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

Unresolved directive in mailer.adoc - include::{includes}/devtools/dev.adoc[]

Implement the HTTP endpoint

首先，创建 src/main/java/org/acme/MailResource.java 文件，内容如下：

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

MailResource 类实现应用程序公开的 HTTP API。它在 http://localhost:8080/mail 上处理 GET 请求。

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>

由于应用程序在 dev mode 中运行，它模拟发送电子邮件。它在日志中打印它，以便您可以检查即将发送的内容。

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.

本部分使用了 imperative 发送器 API。它阻塞调用线程，直到邮件发送。

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

Quarkus Mailpit 扩展对于测试电子邮件非常方便。它为 Mailpit 提供开发服务，这是一个用于测试和调试电子邮件发送的漂亮 UI。

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

最后一部分使用 imperative 发送器。Quarkus 还提供了一个反应式 API。

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

Mutiny

反应式发送器使用 Mutiny 反应式类型。如果您不熟悉 Mutiny，请查阅 Mutiny - an intuitive reactive programming library。

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

现在是时候配置收件器，使其不模拟发送电子邮件了。Quarkus 收件器使用 SMTP，因此请确保您有权访问 SMTP 服务器。

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.

在 src/main/resources/application.properties 文件中，您需要配置主机、端口、用户名、密码以及其他配置方面。请注意，密码还可以使用系统属性和环境变量进行配置。有关详细信息，请参阅 configuration reference guide。

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.

受欢迎邮件服务的配置涵盖在 the reference guide 中。

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

配置邮件发送器后，如果您按上面所示调用 HTTP 端点，您将发送电子邮件。

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

Conclusion

本指南展示了如何从您的 Quarkus 应用程序发送电子邮件。mailer reference guide 提供了有关邮件发送器用法和配置的更多详细信息，例如：

This guide has shown how to send emails from your Quarkus application. The mailer reference guide provides more details about the mailer usage and configuration such as: