Sending emails using SMTP

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

Table of Contents

Prerequisites
Architecture
Solution
Create the Maven Project
- Implement the HTTP endpoint
Using the reactive mailer
Configuring the mailer
Conclusion

Prerequisites

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

Architecture

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

exposing an HTTP endpoint,
当端点收到 HTTP 请求时发送电子邮件。

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

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

Solution

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

克隆 Git 存储库： git clone $${quickstarts-base-url}.git，或下载 $${quickstarts-base-url}/archive/main.zip[存档]。

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

Create the Maven Project

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

CLI

quarkus create app {create-app-group-id}:{create-app-artifact-id} \
    --no-code
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 --gradle 或 --gradle-kotlin-dsl 选项。有关如何安装和使用 Quarkus CLI 的详细信息，请参见 Quarkus CLI 指南。

Maven

mvn {quarkus-platform-groupid}:quarkus-maven-plugin:{quarkus-version}:create \
    -DprojectGroupId={create-app-group-id} \
    -DprojectArtifactId={create-app-artifact-id} \
    -DnoCode
cd {create-app-artifact-id}

要创建一个 Gradle 项目，添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

适用于 Windows 用户：

如果使用 cmd，（不要使用反斜杠 \ ，并将所有内容放在同一行上）
如果使用 Powershell，将 -D 参数用双引号引起来，例如 "-DprojectArtifactId={create-app-artifact-id}"

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

用于公开 REST 端点的 Quarkus REST（以前为 RESTEasy Reactive）
邮件发送器，以便我们发送电子邮件
Qute, our template engine

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

CLI

quarkus extension add {add-extension-extensions}

Maven

./mvnw quarkus:add-extension -Dextensions='{add-extension-extensions}'

Gradle

./gradlew addExtension --extensions='{add-extension-extensions}'

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

pom.xml

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

build.gradle

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

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

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

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 端点的根路径
2	注入由 Quarkus 管理的 `Mailer` 对象
3	在 `/mail` 上处理 HTTP GET 请求，创建一种方法
4	由于我们使用 Quarkus REST 和 imperative 发送器，我们需要添加 `@Blocking` 批注。稍后我们会看到反应变体。
5	通过配置 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`。
2	配置路径以处理 `/mail/reactive` 上的 GET 请求。请注意，由于我们使用的是反应式 API，因此我们不需要 `@Blocking`。
3	该方法返回一个 `Uni<Void>`，当邮件发送时完成。它不阻塞调用线程。
4	API 与 imperative 类似，但 `send` 方法返回一个 `Uni<Void>`。

现在，在您的终端中运行

> 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 提供了有关邮件发送器用法和配置的更多详细信息，例如：