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

SMTPでのメールの送信

このガイドでは、QuarkusアプリケーションがSMTPサーバーを使用して電子メールを送信する方法を説明します。このガイドは入門編です。mailerの詳細やその使用方法については、 Quarkus Mailer リファレンスドキュメントをご確認ください。

前提条件

このガイドを完成させるには、以下が必要です:

  • 約15分

  • IDE

  • JDK 17+がインストールされ、 JAVA_HOME が適切に設定されていること

  • Apache Maven 3.9.6

  • 使用したい場合は、 Quarkus CLI

  • ネイティブ実行可能ファイルをビルドしたい場合、MandrelまたはGraalVM(あるいはネイティブなコンテナビルドを使用する場合はDocker)をインストールし、 適切に設定していること

  • SMTPホスト名、ポート、資格情報、および電子メール アドレス

  • cURL

アーキテクチャ

このガイドでは、次のアプリケーションを作成します:

  1. HTTPエンドポイントを公開している

  2. エンドポイントがHTTPリクエストを受信したときにメールを送信

このアプリケーションでは、 命令型 および リアクティブ型 のmailer APIを使用して電子メールを送信する方法をデモします。

添付ファイル、インライン化された添付ファイル、テンプレート化、テスト、より高度な設定については、 Mailer Referenceドキュメントで説明されています。

ソリューション

次の章で紹介する手順に沿って、ステップを踏んでアプリを作成することをお勧めします。ただし、完成した例にそのまま進んでも構いません。

Gitリポジトリをクローンする: git clone https://github.com/quarkusio/quarkus-quickstarts.git 、または archive をダウンロードする。

ソリューションは mailer-quickstart ディレクトリ にあります。

Mavenプロジェクトの作成

まず、新しいプロジェクトが必要です。以下のコマンドで新規プロジェクトを作成します。

コマンドラインインタフェース
quarkus create app org.acme:mailer-quickstart \
    --extension='rest,mailer,qute' \
    --no-code
cd mailer-quickstart

Gradleプロジェクトを作成するには、 --gradle または --gradle-kotlin-dsl オプションを追加します。

Quarkus CLIのインストールと使用方法の詳細については、 Quarkus CLI ガイドを参照してください。

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

Gradleプロジェクトを作成するには、 -DbuildTool=gradle または -DbuildTool=gradle-kotlin-dsl オプションを追加します。

Windowsユーザーの場合:

  • cmdを使用する場合、(バックスラッシュ \ を使用せず、すべてを同じ行に書かないでください)。

  • Powershellを使用する場合は、 -D パラメータを二重引用符で囲んでください。例: "-DprojectArtifactId=mailer-quickstart"

このコマンドは、以下のエクステンションを含むMaven構造を生成します:

  • RESTエンドポイントの公開に使用されるQuarkus REST(旧RESTEasy Reactive)

  • 電子メールを送信するためのMailer

  • テンプレートエンジン Qute

Quarkusプロジェクトがすでに設定されている場合は、プロジェクトのベースディレクトリで次のコマンドを実行することで、 mailer エクステンションをプロジェクトに追加できます:

コマンドラインインタフェース
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")

生成されたプロジェクトをIDEで開いてください。ターミナルでプロジェクトに移動し、devモードでアプリケーションを起動します:

コマンドラインインタフェース
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

HTTPエンドポイントの実装

まず、以下の内容で 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と 命令型 メーラーを使用しているため、 @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モード で動作しているので、メール送信のシミュレーションを行います。それをログに出力するので、何が送信されようとしているのかを確認することができます。

このセクションでは、 命令型 mailer APIを使用しました。メールが送信されるまで呼び出し元のスレッドをブロックします。

QuarkusのMailpit エクステンションは、メールのテストに非常に便利です。 メール送信のテストやデバッグのための優れたUIである、 Mailpit 用のDev Servicesを提供します。

リアクティブmailerの使用

最後のセクションでは、 命令型の メーラーを使用しています。QuarkusはリアクティブなAPIも提供しています。

Mutiny

リアクティブ MailerはMutiny リアクティブ型 を使用しています。Mutiny - 直感的リアクティブプログラミングライブラリ をチェックしてください。

同じクラスに以下を追加します。

@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 リアクティブmailerをインジェクトします。インポートされるクラスは io.quarkus.mailer.reactive.ReactiveMailer です。
2 /mail/reactive への GET リクエストを処理するためのパスを設定します。なお、ここではリアクティブAPIを使用しているため、 @Blocking は必要ありません。
3 このメソッドは、メールが送信されたときに完了する Uni<Void> を返します。このメソッドは、呼び出し元のスレッドをブロックしません。
4 APIは、 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>

mailerの設定

そろそろメールの送信をシミュレートしないようにmailerを設定しましょう。QuarkusのmailerはSMTPを使用しているので、SMTPサーバーにアクセスできることを確認してください。

Quarkus mailerはSMTPを使用しています。 src/main/resources/application.properties ファイルでは、ホスト、ポート、ユーザー名、パスワードだけでなく、他の設定面も設定する必要があります。パスワードは、システムのプロパティーや環境変数を使って設定することもできるのを覚えておいてください。詳しくは設定リファレンスガイド を参照して下さい。

一般的なメールサービスの設定については、 リファレンスガイド に記載されています。

mailerの設定が完了したら、上記のようにHTTPエンドポイントを呼び出すと、メールが送信されます。

まとめ

このガイドでは、Quarkusアプリケーションからメールを送信する方法を紹介しました。 mailer エクステンションは、JVMとネイティブモードで動作します。

関連コンテンツ

同一エクステンション