Sending emails using SMTP

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

Prerequisites

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

Architecture

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

  1. exposing an HTTP endpoint,

  2. 当端点收到 HTTP 请求时发送电子邮件。

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

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

Solution

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

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

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

Create the Maven Project

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

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

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

  • 用于公开 REST 端点的 Quarkus REST（以前为 RESTEasy Reactive）

  • 邮件发送器，以便我们发送电子邮件

  • Qute, our template engine

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

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

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

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

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

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

Implement the HTTP endpoint

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

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>  配置我们的 HTTP 端点的根路径
<1>  注入由 Quarkus 管理的 `Mailer` 对象
<1>  在 `/mail` 上处理 HTTP GET 请求，创建一种方法
<1>  由于我们使用 Quarkus REST 和 _imperative_ 发送器，我们需要添加 `@Blocking` 批注。稍后我们会看到反应变体。
<1>  通过配置 _to_ 收件人、主题和正文来创建一个 `Mail` 对象

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

因此，如果您在另一个终端中运行：

> curl http://localhost:8080/mail

您应该在应用程序日志中看到类似以下内容：

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 中运行，它模拟发送电子邮件。它在日志中打印它，以便您可以检查即将发送的内容。

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

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

Using the reactive mailer

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

Mutiny

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

在同一类中，添加：

@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>  注入反应式发送器。要导入的类是 `io.quarkus.mailer.reactive.ReactiveMailer`。
<1>  配置路径以处理 `/mail/reactive` 上的 GET 请求。请注意，由于我们使用的是反应式 API，因此我们不需要 `@Blocking`。
<1>  该方法返回一个 `Uni&amp;lt;Void&amp;gt;`，当邮件发送时完成。它不阻塞调用线程。
<1>  API 与 _imperative_ 类似，但 `send` 方法返回一个 `Uni&amp;lt;Void&amp;gt;`。

现在，在您的终端中运行

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

您应该在应用程序日志中看到类似以下内容：

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 服务器。

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

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

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

Conclusion

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