【SpringBoot】「Thymeleaf」を使用してメール送信方法の紹介

メールを送信プログラムを作成する時に、本文の一部を変更したいことはないでしょうか。

このメール本文の一部を変更するために、「Thymeleaf」というテンプレートエンジンの機能を持っているライブラリを使用することで実現することができます。

今回は、「SpringBoot + Thymeleaf」のメールテンプレート機能を使用して、メール送信時に本文の一部を変更する方法の紹介になります。

スポンサーリンク

環境

検証に使用した環境／ライブラリを以下に記載します。

  • Java：11
  • SpringBoot：2.2.6
  • Thymeleaf：3.0.11
  • Gradle：6.1

検証のテストに使用したライブラリを以下に記載します。

  • JUnit：5.5.2
  • GreenMail：1.5.11

メール送信のテストを実施するために「GreenMail」を使用します。テスト方法については、以下の記事も参考になると思います。

【Java】メール送信の単体試験方法の紹介（GreenMail）
メール送信プログラムを作成して試験する時に、単体試験をするための方法に悩んだことはないでしょうか。 単体試験をするためだけに開発環境へメールサーバーを構築するのは手間もかかります。また、他の人がテストするときにも開発環境へメールサーバーを構...
fumidzuki.com
2019年6月23日

Thymeleafについて

「Thymeleaf」は、Javaで動作するテンプレートエンジンです。Webを表示するためのHTMLなどを処理することが多いライブラリですが、プレーンテキストのテンプレートエンジンとして使用することもできます。

このプレーンテキストのテンプレートエンジンの機能を使用してメールテンプレートとして使用する方法の紹介になります。

「Thymeleaf」について詳しく知りたい場合は、以下の日本語リファレンスマニュアルを確認してみてください。

Tutorial: Using Thymeleaf (ja)
www.thymeleaf.org

ビルドスクリプト（gradle）

サンプルプログラムで使用するビルドスクリプト（build.gradle）を以下に記載します。

plugins {
  id 'org.springframework.boot' version '2.2.6.RELEASE'
  id 'io.spring.dependency-management' version '1.0.9.RELEASE'
  id 'java'
}

sourceCompatibility = '11'

repositories {
  mavenCentral()
}

dependencies {
  implementation 'org.springframework.boot:spring-boot-starter-mail'
  implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
  testImplementation('org.springframework.boot:spring-boot-starter-test') {
    exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
  }
  testImplementation 'com.icegreen:greenmail:1.5.11'
}

test {
  useJUnitPlatform()
}

SpringBootの設定ファイル

SpringBootの設定ファイル（application.properties）には、メール送信に関連する設定を追加します。

メール送信に関連する設定は、最低限以下に記載する設定だけでメール送信を実行できます。
記載例は、サンプルプログラムのテストに使用するための設定になります。

spring.mail.host=localhost
spring.mail.port=3025

メールテンプレート

メールテンプレートの作成

サンプルプログラムで使用するメールテンプレートファイルの内容を以下に記載します。

[(${name})] へ
メール本文です。
[#th:block th:if="${display}"]
ここは表示されます。
[/th:block]
[#th:block th:if="${!display}"]
ここは表示されません。
[/th:block]
[#th:block th:each="item : ${items}"]
[#th:block th:utext="${item}" /]
[/th:block]
メール末尾です。

作成したメールテンプレートファイルを保存します。以下に記載するフォルダ構成の「mail」フォルダに、ファイル名を「sample.txt」として保存してください。

src
└main
  ├java
  └resources
    └mail
      └sample.txt

【注意】
ファイルを保存するとき文字コードは、必ず「UTF-8」を指定してください。正しい文字コードを指定しないと文字化けの原因となります。

メールテンプレートのテキスト構文

メールテンプレート内に記載しているテキスト構文についての記載方法を紹介します。

単純な情報の表示方法

単純な情報を設定したい場合は、以下のように記載する必要があります。

[(${xxxx})]

繰り返す情報の表示方法

繰り返す情報を設定したい場合は、以下ように記載する必要があります。

[#th:block th:each="item : ${items}"]
  [#th:block th:utext="${item}" /]
[/th:block]

条件による情報の表示方法

条件による情報の表示を設定したい場合は、以下のように記載する必要があります。

[#th:block th:if="${display}"]
  条件が正しい場合に表示されます。
[/th:block]

省略して記載する方法

「#th:block」は、以下のように省略して記載することもできます。

[# th:each="item : ${items}"]

[/]

テキストテンプレートのテキスト構文についての詳細は、こちらも参考にしてみてください。

サンプルプログラム

サンプルプログラムでは、メールテンプレートに関連する説明だけを記載しています。それ以外については割愛しているため、メール送信などに関連する内容は、以下の記事も参考にしてください。

【SpringBoot】メール送信方法の紹介
SpringBootを使用してメール送信方法として、以下に記載する２つを紹介していきます。 直接インスタンスを作成する方法。DI（Dependency Injection）を使用する方法。 基本的には、DIを使用する方法で問題ないと思います...
fumidzuki.com
2020年4月12日

サンプルプログラムの全体を以下に記載します。

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.mail.MailSender;
import org.springframework.mail.SimpleMailMessage;
import org.springframework.stereotype.Service;
import org.thymeleaf.context.Context;
import org.thymeleaf.spring5.SpringTemplateEngine;
import org.thymeleaf.templatemode.TemplateMode;
import org.thymeleaf.templateresolver.ClassLoaderTemplateResolver;

/**
 * 「メール送信」のクラスのサンプルクラス。
 */
@Service
public class MailSenderService {

  /**
   * 「メール送信」のクラスをDIする。
   */
  @Autowired
  MailSender mailSender;

  public void send() {

    // メール送信内容作成して設定する。
    SimpleMailMessage message = new SimpleMailMessage();
    message.setTo("to@example.com");
    message.setFrom("from@example.com");
    message.setSubject("てすと件名");

    // テンプレートエンジンを使用するための設定インスタンスを生成します。
    ClassLoaderTemplateResolver templateResolver = new ClassLoaderTemplateResolver();
    /*
     * テンプレートエンジンの種類を指定します。
     * メールテンプレートとして使用するため、テキストを指定しています。
     */
    templateResolver.setTemplateMode(TemplateMode.TEXT);
    /*
     * テンプレートファイルとして読み込む文字エンコードを指定します。
     * 以下のように指定すると「UTF-8」の文字エンコードなります。
     */
    templateResolver.setCharacterEncoding("UTF-8");

    // テンプレートエンジンを使用するためのインスタンスを生成します。
    SpringTemplateEngine engine = new SpringTemplateEngine();
    engine.setTemplateResolver(templateResolver);

    // メールテンプレートに設定するパラメータを設定します。
    Map<String, Object> variables = new HashMap<>();
    variables.put("name", "てすと氏名");
    variables.put("items", Arrays.asList("りんご", "みかん"));
    variables.put("display", true);

    // テンプレートエンジンを実行してテキストを取得します。
    Context context = new Context();
    context.setVariables(variables);
    // 使用するテンプレートのファイル名とパラメータ情報を設定します。
    String text = engine.process("/mail/sample.txt", context);
    message.setText(text);

    // メール送信を実施する。
    // メール送信の設定は、設定ファイルから取得する。
    this.mailSender.send(message);

  }

}

メールテンプレート設定方法

メールテンプレートを使用するための設定オブジェクトの作成と使用方法の紹介です。

サンプルでは、「ClassLoaderTemplateResolver」を使用していますが、直接ファイルから取得するための「FileTemplateResolver」などもあります。

// テンプレートエンジンを使用するための設定インスタンスを生成します。
ClassLoaderTemplateResolver templateResolver = new ClassLoaderTemplateResolver();
/*
 * テンプレートエンジンの種類を指定します。
 * メールテンプレートとして使用するため、テキストを指定しています。
 */
templateResolver.setTemplateMode(TemplateMode.TEXT);
/*
 * テンプレートファイルとして読み込む文字エンコードを指定します。
 * 以下のように指定すると「UTF-8」の文字エンコードなります。
 */
templateResolver.setCharacterEncoding("UTF-8");

メールテンプレート取得方法

メールテンプレートから情報を取得するオブジェクトの作成と使用方法を紹介します。

メールテンプレートエンジンのインスタンス作成

メールテンプレートエンジンのインスタンスを作成して、作成済みのメールテンプレート設定オブジェクトを設定します。

// テンプレートエンジンを使用するためのインスタンスを生成します。
SpringTemplateEngine engine = new SpringTemplateEngine();
engine.setTemplateResolver(templateResolver);

メールテンプレートに設定するパラメータ作成

メールテンプレートに設定するパラメータを作成します。パラメータを作成するためには、「java.util.Map」を使用します。

値の設定方法は、「Key」にメールテンプレートに記載している名前を指定します。「Value」に表示する情報を指定します。

// メールテンプレートに設定するパラメータを設定します。
Map<String, Object> variables = new HashMap<>();
variables.put("name", "てすと氏名");
variables.put("items", Arrays.asList("りんご", "みかん"));
variables.put("display", true);

メールテンプレートの本文取得

メール本文に設定するための情報を取得します。

「Context」のインスタンスを生成して、作成済みのパラメータ情報を設定します。

// テンプレートエンジンを実行してテキストを取得します。
Context context = new Context();
context.setVariables(variables);

「SpringTemplateEngine.engine」の「process」を実行することで、メールテンプレートの本文を取得することができます。

一番目の引数にメールテンプレートのファイル名を指定してください。
二番目の引数に作成済みの「Context」を指定してください。

作成済みのメール送信オブジェクトに取得したメールテンプレートの情報を設定します。

// 使用するテンプレートのファイル名とパラメータ情報を設定します。
String text = engine.process("sample.txt", context);
message.setText(text);

【注意】
指定したメールテンプレートが取得できない場合は、以下に記載する例外が発生します。
例外が発生した場合は、フォルダ名、ファイル名などが正しいかを確認してください。

org.thymeleaf.exceptions.TemplateInputException: An error happened during template parsing (template: "xxxx")

例外の詳細情報に指定したパスが表示されます。例では、「xxxx」と記載している箇所に表示されます。

メール送信時の本文

サンプルプログラムで作成したメールテンプレートを使用してメール送信できるメール本文を以下に記載します。

てすと氏名 へ

メール本文です。

  ここは表示されます。



 - りんご
 - みかん

メール末尾です。

まとめ

「SpringBoot + Thymeleaf」のメールテンプレート機能を使用した、サンプルプログラムで使用方法を紹介しました。