跳到主要内容

Micronaut Email

与交易电子邮件提供者集成。

1. 简介​

Micronaut 电子邮件模块可与亚马逊简单电子邮件服务、Postmark、Mailjet 或 SendGrid 等事务电子邮件提供者集成。

2. 重大变更​

Micronaut Email 2

Micronaut Email 2 迁移到 Jakarta 邮件包命名空间，从 javax.mail 到 jakarta.mail。此外，它使用传递依赖 jakarta.mail:jakarta.mail-api 代替 com.sun.mail:javax.mail。Jakarta Mail 还分离了 API 和实现。以前的实现源现在是 Eclipse Angus 项目的一部分，是 JavaMail/JakartaMail 的直接继承者。除了 jakarta-mail-api 之外，还需要额外依赖 org.eclipse.angus:angus-mail。请注意，对于 Eclipse Angus，模式和软件包前缀已从 com.sun.mail 改为 org.eclipse.angus.mail。

此版本还将 ActiveCampaign Postmark 库从 1.8.x 升级到 1.9.0。尽管这只是一个小的修订，但它重构了软件包名称，并将依赖关系 groupId 从 com.wildbit.java 改为 com.postmarkapp。

3. 发布历史​

关于此项目，你可以在此处找到发布版本列表（含发布说明）：

https://github.com/micronaut-projects/micronaut-email/releases

4. 快速入门​

首先，你需要安装依赖项并为你的事务电子邮件提供者添加配置。

然后，你就可以通过注入一个 EmailSender 类型的 Bean 来发送电子邮件了。

package io.micronaut.email.docs;

import io.micronaut.email.BodyType;
import io.micronaut.email.EmailSender;
import io.micronaut.email.Email;
import io.micronaut.email.MultipartBody;
import jakarta.inject.Singleton;

@Singleton
public class WelcomeService {
    private final EmailSender<?, ?> emailSender;

    public WelcomeService(EmailSender<?, ?> emailSender) {
        this.emailSender = emailSender;
    }

    public void sendWelcomeEmail() {
        emailSender.send(Email.builder()
                .from("sender@example.com")
                .to("john@example.com")
                .subject("Micronaut test")
                .body(new MultipartBody("<html><body><strong>Hello</strong> dear Micronaut user.</body></html>", "Hello dear Micronaut user")));
    }
}

5. 附件​

要发送附件，请使用Attachment生成器。

package io.micronaut.email.docs;

import io.micronaut.email.Attachment;
import io.micronaut.email.BodyType;
import io.micronaut.email.Email;
import io.micronaut.email.EmailSender;
import io.micronaut.email.MultipartBody;
import io.micronaut.email.test.SpreadsheetUtils;
import io.micronaut.http.MediaType;
import jakarta.inject.Singleton;
import org.apache.poi.xssf.usermodel.XSSFWorkbook;

import java.io.ByteArrayOutputStream;
import java.io.IOException;

@Singleton
public class SendAttachmentService {
    private final EmailSender<?, ?> emailSender;

    public SendAttachmentService(EmailSender<?, ?> emailSender) {
        this.emailSender = emailSender;
    }

    public void sendReport() throws IOException {
        emailSender.send(Email.builder()
                .from("sender@example.com")
                .to("john@example.com")
                .subject("Monthly reports")
                .body(new MultipartBody("<html><body><strong>Attached Monthly reports</strong>.</body></html>", "Attached Monthly reports"))
                .attachment(Attachment.builder()
                        .filename("reports.xlsx")
                        .contentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")
                        .content(excel())
                        .build()));
    }

    private static byte[] excel() throws IOException {
        XSSFWorkbook wb = new XSSFWorkbook();
        wb.createSheet("Reports");
        ByteArrayOutputStream bos = new ByteArrayOutputStream();
        try {
            wb.write(bos);
        } finally {
            bos.close();
        }
        return bos.toByteArray();
    }
}

6. 装饰器​

如果你总是从同一个电子邮件地址发送电子邮件，你可以通过配置指定它，并在创建电子邮件时跳过填充发件人字段。

表 1. FromConfigurationProperties 的配置属性

属性类型描述
micronaut.email.from.emailjava.lang.String
micronaut.email.from.namejava.lang.String发送电子邮件的联系人姓名

通过设置 micronaut.email.from.email，Micronaut Email 注册了一个 FromDecorator 类型的 Bean，如果在构建电子邮件时未指定 from 字段，该 Bean 将填充该字段。

此外，如果你有自定义需求（例如，总是密送电子邮件地址，在特定环境中为电子邮件主题添加前缀），你可以注册一个 EmailDecorator 类型的 Bean。

7. 自定义电子邮件​

如果你需要自定义发送的电子邮件，例如在电子邮件中添加标题，那么你可以使用 EmailSender 的 Consumer 变体。

这里我们展示了一个使用 jakarta.mail.Message 类的 JavaMail 示例，但也可根据你使用的邮件平台请求类进行修改。

package io.micronaut.email.docs;

import io.micronaut.email.Email;
import io.micronaut.email.EmailSender;
import io.micronaut.email.MultipartBody;
import jakarta.inject.Singleton;
import jakarta.mail.Message;
import jakarta.mail.MessagingException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

/**
 * An example of customization for JavaMail messages
 */
@Singleton
public class CustomizedJavaMailService {

    private static final Logger LOG = LoggerFactory.getLogger(CustomizedJavaMailService.class);

    private final EmailSender<Message, ?> emailSender;

    public CustomizedJavaMailService(EmailSender<Message, ?> emailSender) {
        this.emailSender = emailSender;
    }

    public void sendCustomizedEmail() {
        Email.Builder email = Email.builder()
                .from("sender@example.com")
                .to("john@example.com")
                .subject("Micronaut test")
                .body(
                        new MultipartBody(
                                "<html><body><strong>Hello</strong> dear Micronaut user.</body></html>",
                                "Hello dear Micronaut user"
                        )
                );

        // Customize the message with a header prior to sending
        emailSender.send(email, message -> {
            try {
                message.addHeader("List-Unsubscribe", "<mailto:list@host.com?subject=unsubscribe>");
            } catch (MessagingException e) {
                LOG.error("Failed to add header", e);
            }
        });
    }
}

8. 模板​

如果要使用模板发送电子邮件，请在应用程序中添加以下依赖。

implementation("io.micronaut.email:micronaut-email-template")

你可以使用 Micronaut Views 支持的任何模板引擎。

例如，如果包含以下依赖，你就可以使用 velocity 模板来发送电子邮件：

implementation("io.micronaut.views:micronaut-views-velocity")

指定电子邮件文本或 HTML 作为 TemplateBody 发送模板。

TemplateBodyDecorator 类型的 Bean 会渲染这些模板。

package io.micronaut.email.docs;

import io.micronaut.core.util.CollectionUtils;
import io.micronaut.email.BodyType;
import io.micronaut.email.Email;
import io.micronaut.email.EmailSender;
import io.micronaut.email.MultipartBody;
import io.micronaut.email.template.TemplateBody;
import io.micronaut.views.ModelAndView;
import jakarta.inject.Singleton;

import java.util.Map;

@Singleton
public class WelcomeWithTemplateService {
    private final EmailSender<?, ?> emailSender;

    public WelcomeWithTemplateService(EmailSender<?, ?> emailSender) {
        this.emailSender = emailSender;
    }

    public void sendWelcomeEmail() {
        Map<String, String> model = CollectionUtils.mapOf("message", "Hello dear Micronaut user",
                "copyright", "© 2021 MICRONAUT FOUNDATION. ALL RIGHTS RESERVED",
                "address", "12140 Woodcrest Executive Dr., Ste 300 St. Louis, MO 63141");
        emailSender.send(Email.builder()
                        .from("sender@example.com")
                        .to("john@example.com")
                        .subject("Micronaut test")
                        .body(new MultipartBody(
                                new TemplateBody<>(BodyType.HTML, new ModelAndView<>("htmltemplate", model)),
                                new TemplateBody<>(BodyType.TEXT, new ModelAndView<>("texttemplate", model)))));
    }

}

在前面的例子中，你可以使用一个 Velocity 模板，例如：

src/main/resources/views/texttemplate.vm

Hello

$message

thanks,
Micronaut Framework

$address

$copyright

9. 集成​

9.1 SES​

要与亚马逊简单电子邮件服务集成，请在应用程序中添加以下依赖 。

implementation("io.micronaut.email:micronaut-email-amazon-ses")

此集成使用 Micronaut AWS SDK v2 集成。

了解更多：

9.2 Postmark​

要与 Postmark 集成，请在应用程序中添加以下依赖：

implementation("io.micronaut.email:micronaut-email-postmark")

你需要通过配置提供 Postmark 的 API 令牌：

表 1. PostmarkConfigurationProperties 的配置属性

属性类型描述
postmark.enabledboolean如果启用了 Postmark 集成。默认值：true
postmark.api-tokenjava.lang.String
postmark.track-opensboolean是否跟踪电子邮件是否被打开。默认值：true
postmark.track-linksTrackLinks是否跟踪电子邮件的链接。默认值 DO_NOT_TRACK。

9.3 SendGrid​

要与 SendGrid 集成，请在应用程序中添加以下依赖。

implementation("io.micronaut.email:micronaut-email-sendgrid")

你需要通过配置提供 SendGrid 的 API 密钥和秘密：

表 1. SendGridConfigurationProperties 的配置属性

属性类型描述
sendgrid.enabledboolean如果启用 SendGrid 集成。默认值 true
sendgrid.api-keyjava.lang.String

9.4 Mailjet​

要与 Mailjet 集成，请在你的应用程序中添加以下依赖。

implementation("io.micronaut.email:micronaut-email-mailjet")

你需要通过配置提供 Mailjet 的 API 密钥和秘密：

表 1. MailjetConfigurationProperties 的配置属性

属性类型描述
mailjet.enabledboolean如果启用 Mailjet 集成。默认值：true
mailjet.versionjava.lang.StringMailjet API 版本。默认值："v3.1"
mailjet.api-keyjava.lang.StringMailjet API key。
mailjet.api-secretjava.lang.StringMailjet API secret。

9.5 Jakarta Mail​

要使用 Jakarta Mail，请在应用程序中添加以下依赖。

implementation("io.micronaut.email:micronaut-email-javamail")

此外，你还需要为 Jakarta Mail api 的实现提供运行时依赖关系。Eclipse Angus 是 JavaMail/JakartaMail 先前版本的直接继承者。

runtimeOnly("org.eclipse.angus:angus-mail")

你需要提供 MailPropertiesProvider 和 SessionProvider 类型的 bean 以匹配你的配置。

通过配置进行验证

除了提供自己的 SessionProvider 用于认证外，你还可以通过配置来配置基于密码的认证：

javamail:
  authentication:
    username: 'my.username'
    password: 'my.password'

10. 仓库​

你可以在此资源库中找到此项目的源代码：

https://github.com/micronaut-projects/micronaut-email

英文链接