Spring Bootでメール送信｜HTML・添付・Gmail設定

Spring Boot でメールを送るには、spring-boot-starter-mail を入れて spring.mail.host を設定し、自動で作られる JavaMailSender を使います。 文字だけなら SimpleMailMessage、HTML・添付・差出人の日本語名を付けるなら MimeMessageHelper を使います。

# application.yml（Gmail の例。パスワードは環境変数から）
spring:
  mail:
    host: smtp.gmail.com
    port: 587
    username: your-account@gmail.com
    password: ${MAIL_PASSWORD}          # Google のアプリパスワード
    properties:
      "[mail.smtp.auth]": true
      "[mail.smtp.starttls.enable]": true
      "[mail.smtp.starttls.required]": true
      "[mail.smtp.connectiontimeout]": 5000
      "[mail.smtp.timeout]": 3000
      "[mail.smtp.writetimeout]": 5000

@Service
public class NoticeMailService {

    private final JavaMailSender mailSender;

    public NoticeMailService(JavaMailSender mailSender) {
        this.mailSender = mailSender;
    }

    public void sendOrderReceived(String to, String orderNo) {
        SimpleMailMessage m = new SimpleMailMessage();
        m.setFrom("noreply@example.com");
        m.setTo(to);
        m.setSubject("【受付完了】ご注文ありがとうございます");
        m.setText("ご注文を受け付けました。\n注文番号：" + orderNo + "\n");
        mailSender.send(m);
    }
}

確認環境：Spring Boot 4.1.1（Spring Framework 7.0.9、Jakarta Mail 2.1.5、Angus Mail 2.0.5、Jakarta Activation 2.1.4 は Boot の依存管理の版）、OpenJDK 25.0.4.1（Linux）。Jakarta Mail・Angus Mail・Angus Activation と、Spring Framework の JavaMailSenderImpl・MimeMessageHelper を GitHub のタグのソースからビルドし、Python の aiosmtpd 1.4.6 で手元に立てた SMTP サーバーへ実際に送りました。この記事のメールの生データ（ヘッダー・MIME 構造）とエラーの文は、そのときの結果です。spring.mail.* の既定値は Boot v4.1.1 のソース（MailProperties・MailSenderPropertiesConfiguration）で、Gmail の設定は Google のヘルプで確かめました（確認日 2026年10月13日）。

依存と自動設定のしくみ

// build.gradle.kts
dependencies {
    implementation("org.springframework.boot:spring-boot-starter-mail")
}

<!-- pom.xml -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-mail</artifactId>
</dependency>

JavaMailSender の Bean は、spring.mail.host（または spring.mail.jndi-name）を設定したときだけ作られます。 Boot 4.1.1 の MailSenderAutoConfiguration の条件です。設定し忘れると、起動時に次のように出ます（NoSuchMailSenderBeanFailureAnalyzer の文）。

Description:

A MailSender bean could not be found because MailSenderAutoConfiguration did not match. Neither 'spring.mail.host' nor 'spring.mail.jndi-name' is configured.

Action:

Consider configuring 'spring.mail.host' or 'spring.mail.jndi-name' to enable auto-configuration. If you want to use a custom mail sender, define a MailSender bean in your configuration.

Bean が見つからないときの読み方は関連記事「required a bean of typeの直し方｜原因一覧と読み方」で扱っています。

spring.mail.* の設定一覧（Boot 4.1.1）

spring.mail.properties の下のキーには . が入るため、YAML では "[mail.smtp.auth]" のように角括弧で囲みます。 application.properties なら spring.mail.properties.mail.smtp.auth=true と書けます。

タイムアウトは必ず設定する

Spring Boot のリファレンスには「certain default timeout values are infinite」とあり、応答しないメールサーバーでスレッドが止まらないよう、タイムアウトの設定を勧めています。

よく使う Jakarta Mail のキー

設定キーの全体は関連記事「Spring Boot application.properties設定一覧」で扱っています。

基本の送信：SimpleMailMessage

冒頭の SimpleMailMessage で送ったメールが、SMTP サーバーにどう届いたかです（手元の SMTP サーバーで受けた生データ）。

Date: Tue, 13 Oct 2026 02:41:37 +0900 (JST)
From: noreply@example.com
To: yamada@example.com
Message-ID: <999661724.0.1791826897494@localhost>
Subject: =?UTF-8?B?44CQ5Y+X5LuY5a6M5LqG44CR44GU5rOo5paH?=
 =?UTF-8?B?44GC44KK44GM44Go44GG44GU44GW44GE44G+44GZ?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: base64

5bGx55SwIOanmAoK44GU5rOo5paH44KS5Y+X44GR5LuY44GR44G+44GX44Gf44CCCuazqOaWh+eV
quWPt++8mkEtMDAwMQo=

SimpleMailMessage の文字コードは、spring.mail.default-encoding（既定 UTF-8）で決まります。 件名・本文が化けるときは、この設定を別の値にしていないかを確かめます。

HTML と添付：MimeMessageHelper

public void sendInvoice(String to, String customerName, Path csv) throws MessagingException, UnsupportedEncodingException {
    MimeMessage msg = mailSender.createMimeMessage();
    MimeMessageHelper h = new MimeMessageHelper(msg, MimeMessageHelper.MULTIPART_MODE_MIXED_RELATED, "UTF-8");

    h.setFrom("noreply@example.com", "株式会社サンプル 通知");   // 差出人の表示名
    h.setTo(to);
    h.setSubject("【請求書】2026年10月分のご案内");
    h.setText(
        customerName + " 様\n2026年10月分の請求書を添付します。",                       // テキスト版
        "<p>" + HtmlUtils.htmlEscape(customerName) + " 様</p>"
            + "<p>2026年10月分の<b>請求書</b>を添付します。</p><img src='cid:logo'>");  // HTML 版
    h.addInline("logo", new ClassPathResource("mail/logo.png"));                    // cid:logo で参照
    h.addAttachment("請求書_2026年10月.csv", new FileSystemResource(csv));
    mailSender.send(msg);
}

setText(テキスト, HTML) の2引数で、HTML を表示できないメールソフト向けのテキスト版も一緒に送れます。 setText(html, true) だけだと HTML 版しか入りません。利用者の入力を HTML に入れるときは HtmlUtils.htmlEscape でエスケープします。

上のコードで送ったメールの生データです（Base64 の本文は省略）。

From: =?UTF-8?B?5qCq5byP5Lya56S+44K144Oz44OX44OrIOmAmuefpQ==?=
 <noreply@example.com>
To: yamada@example.com
Subject: =?UTF-8?B?44CQ6KuL5rGC5pu444CRMjAyNuW5tDEw5pyI5YiG44Gu44GU5qGI5YaF?=
MIME-Version: 1.0
Content-Type: multipart/mixed;
    boundary="----=_Part_0_1342443276.1791826897817"

------=_Part_0_1342443276.1791826897817
Content-Type: multipart/related;
    boundary="----=_Part_1_933699219.1791826897822"

------=_Part_1_933699219.1791826897822
Content-Type: multipart/alternative;
    boundary="----=_Part_2_1296064247.1791826897829"

------=_Part_2_1296064247.1791826897829
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: base64
…
------=_Part_2_1296064247.1791826897829
Content-Type: text/html;charset=UTF-8
Content-Transfer-Encoding: base64
…
------=_Part_1_933699219.1791826897822
Content-Type: image/png; name=inline
Content-Transfer-Encoding: base64
Content-Disposition: inline; filename=inline
Content-ID: <logo>
…
------=_Part_0_1342443276.1791826897817
Content-Type: text/csv; charset=UTF-8;
    name*=UTF-8''%E8%AB%8B%E6%B1%82%E6%9B%B8_2026%E5%B9%B410%E6%9C%88.csv
Content-Transfer-Encoding: base64
Content-Disposition: attachment;
    filename*=UTF-8''%E8%AB%8B%E6%B1%82%E6%9B%B8_2026%E5%B9%B410%E6%9C%88.csv

Python の email で読み直すと、件名は 【請求書】2026年10月分のご案内、差出人は 株式会社サンプル 通知<noreply@example.com>、添付の名前は 請求書_2026年10月.csv に戻りました。

MIME の入れ子の形

multipart/mixed            ← 本文と添付を並べる
├─ multipart/related       ← HTML と、HTML から参照する画像をまとめる
│   ├─ multipart/alternative  ← 同じ内容のテキスト版と HTML 版（どちらか一方が表示される）
│   │   ├─ text/plain
│   │   └─ text/html
│   └─ image/png (Content-ID: <logo>)  ← インライン画像
└─ text/csv (attachment)   ← 添付ファイル

addInline は setText の後に呼びます。 Spring Framework 7.0.9 の MimeMessageHelper の Javadoc に「Invoke addInline after setText」とあり、逆の順番ではメールソフトが画像の参照を解決できないことがある、と説明されています。

添付ファイル名の形（RFC 2231 と RFC 2047）

上の生データのとおり、Angus Mail 2.0.5 は日本語の添付ファイル名を filename*=UTF-8''…（RFC 2231 の形） で送りました。一部のメールソフトはこの形を読めず、添付の名前が化けることがあります。

JVM のシステムプロパティで、filename="=?UTF-8?Q?…?="（RFC 2047 の形）に変えられます。 実際に -Dmail.mime.encodeparameters=false -Dmail.mime.encodefilename=true を付けて送った結果です。

Content-Type: text/csv; charset=UTF-8;
    name="=?UTF-8?Q?=E8=AB=8B=E6=B1=82=E6=9B=B8=5F10=E6=9C=88.csv?="
Content-Disposition: attachment;
    filename="=?UTF-8?Q?=E8=AB=8B=E6=B1=82=E6=9B=B8=5F10=E6=9C=88.csv?="

送る相手のメールソフトで添付の名前が化けると分かったときに、RFC 2047 の形を試します。システムプロパティなので、main の最初で System.setProperty するか、起動オプションで渡します。

ISO-2022-JP で送るとき

既存のシステムに合わせて ISO-2022-JP で送るときは、MimeMessageHelper の第3引数に "ISO-2022-JP" を渡します。実際に送ると、件名・差出人・本文が ISO-2022-JP になりました。

From:
    =?ISO-2022-JP?B?GyRCM3Q8MDJxPFIlNSVzJVclaxsoQg==?= <noreply@example.com>
Subject: =?ISO-2022-JP?Q?=1B$B!Z@A5a=3Dq![=1B(B10=1B$B7nJ,!J=1B(BI?=
 =?ISO-2022-JP?Q?SO-2022-JP=1B$B!K=1B(B?=
Content-Type: text/plain; charset=ISO-2022-JP
Content-Transfer-Encoding: quoted-printable

添付ファイル名は ISO-2022-JP にならず、UTF-8 の filename* のままでした。 ISO-2022-JP は ①・髙 などの機種依存文字を表せないため、新しく作るなら UTF-8 が扱いやすい選択です。

HTML を Thymeleaf で作る

Context ctx = new Context(Locale.JAPAN);
ctx.setVariable("name", customerName);
String html = templateEngine.process("mail/invoice", ctx);   // templates/mail/invoice.html
h.setText(plainText, html);

Thymeleaf は値を自動でエスケープするため、HTML に利用者の入力を入れるときに扱いやすくなります。

Gmail の設定

Gmail は、通常のパスワードではなく「アプリパスワード」で認証します。 Google アカウント ヘルプによると、アプリパスワードは2段階認証プロセスを有効にしたアカウントでだけ使え、Google アカウントのパスワードを変えると取り消されます。組織のアカウントなどでは作れない場合があります。

# 465 番を使う場合
spring:
  mail:
    host: smtp.gmail.com
    port: 465
    username: your-account@gmail.com
    password: ${MAIL_PASSWORD}
    ssl:
      enabled: true
    properties:
      "[mail.smtp.auth]": true

アプリパスワードは application.yml に書かず、環境変数などで渡します。 設定ファイルをリポジトリに入れると、パスワードも一緒に残るためです。業務で大量に送るなら、Amazon SES などの送信サービスを使う形もあります（関連記事「Amazon SESメール送信｜AWS CLIとboto3の手順・エラー対処」）。

よくあるエラー（手元の SMTP サーバーで再現）

535・530 のような3桁の数字は SMTP サーバーの応答コードです。 文の後半（Authentication credentials invalid など）はサーバーごとに違います。上の表はローカルの aiosmtpd の文で、Gmail では別の文になります。

MailSendException は getFailedMessages() で、どのメッセージがなぜ失敗したかを持っています。 一斉送信で一部だけ失敗したときに使います。

try {
    mailSender.send(messages);
}
catch (MailSendException ex) {
    ex.getFailedMessages().forEach((msg, cause) -> log.warn("送信失敗: {}", cause.getMessage()));
}

起動時に接続を確かめたいときは spring.mail.test-connection=true にします。 Boot 4.1.1 のソースでは、接続できないと IllegalStateException: Mail server is not available で起動が止まり、原因に Jakarta Mail の例外が入ります。パスワードが違うときの原因は AuthenticationFailedException: 535 5.7.8 Authentication credentials invalid でした（JavaMailSenderImpl.testConnection() を直接呼んで確かめました）。調べるときは "[mail.debug]": true で SMTP のやり取りを全部表示できます。

送信を本処理から切り離す

メールの送信は外部のサーバーとの通信で、数秒かかったり失敗したりします。注文の登録などの処理と同じトランザクションで待たないようにします。

@Component
public class OrderMailListener {

    private final NoticeMailService mail;

    public OrderMailListener(NoticeMailService mail) {
        this.mail = mail;
    }

    @Async
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void onOrderPlaced(OrderPlacedEvent e) {
        mail.sendOrderReceived(e.email(), e.orderNo());   // DB の確定後に、別スレッドで送る
    }
}

非同期処理の設定は関連記事「Spring Boot @Async｜非同期の使い方と設定一覧・効かない原因表」で扱っています。

テスト：GreenMail で受信内容を確かめる

GreenMail は、テストの中で SMTP サーバーを立てるライブラリです。GreenMail のサイトによると、2.1 系が Jakarta Mail 2.1 に対応し、JUnit 5 用の greenmail-junit5 があります（Boot の依存管理には入っていないため版を書きます）。

testImplementation("com.icegreen:greenmail-junit5:2.1.14")

@SpringBootTest(properties = {
        "spring.mail.host=127.0.0.1",
        "spring.mail.port=3025"           // ServerSetupTest.SMTP のポート
})
class NoticeMailServiceTest {

    @RegisterExtension
    static GreenMailExtension greenMail = new GreenMailExtension(ServerSetupTest.SMTP);

    @Autowired NoticeMailService service;

    @Test
    void 受付メールが日本語の件名で届く() throws Exception {
        service.sendOrderReceived("yamada@example.com", "A-0001");

        MimeMessage[] received = greenMail.getReceivedMessages();
        assertThat(received).hasSize(1);
        assertThat(received[0].getSubject()).isEqualTo("【受付完了】ご注文ありがとうございます");
        assertThat(GreenMailUtil.getBody(received[0])).isNotBlank();
    }
}

getSubject() は RFC 2047 の形をデコードした文字列を返すため、日本語のまま比べられます。 本文は Base64 のまま返ることがあるため、内容を比べるなら received[0].getContent() を使います。単体テストだけなら JavaMailSender を Mockito で置き換え、send に渡された SimpleMailMessage を確かめる形でも書けます。テストの書き方は関連記事「Spring Bootテスト入門｜@WebMvcTestとMockMvcの使い分け」で扱っています。

よくある質問

Q. 件名が化けます。 A. spring.mail.default-encoding を UTF-8 以外にしていないか、MimeMessageHelper の第3引数に文字コードを渡しているかを確かめます。MimeMessage を自分で作る場合は msg.setSubject(件名, "UTF-8") と文字コードを渡します。

Q. 添付ファイルの名前が ATT00001 のようになります。 A. 受け取ったメールソフトが RFC 2231 の filename* を読めていない可能性があります。上の「添付ファイル名の形」の RFC 2047 の設定を試します。

Q. 送信が遅く、画面の応答が止まります。 A. メールサーバーの応答待ちです。タイムアウトを設定し、@Async と @TransactionalEventListener で切り離します。

Q. 送るたびに接続しています。まとめて送れますか。 A. mailSender.send(MimeMessage...) に配列で渡すと、1回の接続で順に送ります（JavaMailSenderImpl の動き）。大量に送るなら、送信サービスの上限と配信の状況を確かめられる仕組みを使います。

まとめ

• spring-boot-starter-mail と spring.mail.host で JavaMailSender が作られる
• 既定の文字コードは UTF-8。件名は =?UTF-8?B?…?= で送られる
• HTML・添付・日本語の差出人名は MimeMessageHelper。setText(テキスト, HTML) で両方入れる
• 日本語の添付名は既定で filename*=UTF-8''…。化けるなら mail.mime.encodeparameters=false
• Gmail は 587 + STARTTLS + アプリパスワード。パスワードは環境変数で
• タイムアウトを設定し、送信は @Async と AFTER_COMMIT で本処理から切り離す
• エラーは3桁の応答コード（535・530 など）を見る

参考・出典

確認日はいずれも 2026年10月13日です。

• Spring Boot リファレンス「Sending Email」：https://docs.spring.io/spring-boot/reference/io/email.html
• Spring Framework リファレンス「Email」：https://docs.spring.io/spring-framework/reference/integration/email.html
• Spring Boot ソースコード（v4.1.1）MailProperties：https://github.com/spring-projects/spring-boot/blob/v4.1.1/module/spring-boot-mail/src/main/java/org/springframework/boot/mail/autoconfigure/MailProperties.java
• Spring Boot ソースコード（v4.1.1）MailSenderPropertiesConfiguration：https://github.com/spring-projects/spring-boot/blob/v4.1.1/module/spring-boot-mail/src/main/java/org/springframework/boot/mail/autoconfigure/MailSenderPropertiesConfiguration.java
• Spring Framework ソースコード（v7.0.9）MimeMessageHelper：https://github.com/spring-projects/spring-framework/blob/v7.0.9/spring-context-support/src/main/java/org/springframework/mail/javamail/MimeMessageHelper.java
• Angus Mail（2.0.5）：https://github.com/eclipse-ee4j/angus-mail/tree/2.0.5
• Google アカウント ヘルプ「Sign in with app passwords」：https://support.google.com/mail/answer/185833
• Google Workspace 管理者ヘルプ「Send email from a printer, scanner, or app」：https://knowledge.workspace.google.com/admin/gmail/send-email-from-a-printer-scanner-or-app
• GreenMail：https://greenmail-mail-test.github.io/greenmail/
• RFC 2047 MIME Part Three: Message Header Extensions for Non-ASCII Text：https://www.rfc-editor.org/rfc/rfc2047
• RFC 2231 MIME Parameter Value and Encoded Word Extensions：https://www.rfc-editor.org/rfc/rfc2231

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。