集成 Mailjet

本文档旨在指导开发者如何在 Java 项目中集成 Mailjet 以实现邮件发送功能。内容涵盖了 Maven 依赖配置、应用配置文件设置、工具类封装以及测试方法。此外，还介绍了如何使用封装好的工具类在 Enjoy 框架中发送邀请邮件，并提供了相关的邮件模板和代码示例。

目录

1. Maven 依赖配置
2. 应用配置文件设置
3. MailJet 发送邮件示例
4. 封装工具类
5. 测试工具类
6. 整合 Enjoy 发送邀请邮件
   • 邮件模板
   • EmailService 服务类
   • 工具类扩展
7. 发送后的响应示例

---

Maven 依赖配置

在项目的 pom.xml 文件中添加 Mailjet 客户端依赖。Mailjet 客户端依赖已经自动包含了 org.json 依赖，因此无需单独添加。

<dependencies>
    <!-- Mailjet 客户端依赖 -->
    <dependency>
        <groupId>com.mailjet</groupId>
        <artifactId>mailjet-client</artifactId>
        <version>5.2.5</version>
    </dependency>

    <!-- org.json 依赖（已自动包含，可选） -->
    <dependency>
        <groupId>org.json</groupId>
        <artifactId>json</artifactId>
        <version>20231013</version>
    </dependency>
</dependencies>

应用配置文件设置

在 app.properties 文件中添加 Mailjet 的 API 密钥配置：

MJ_APIKEY_PUBLIC=你的公共 API 密钥
MJ_APIKEY_PRIVATE=你的私有 API 密钥

注意：请确保将 MJ_APIKEY_PUBLIC 和 MJ_APIKEY_PRIVATE 替换为你在 Mailjet 控制台获取的实际 API 密钥。

MailJet 发送邮件示例

以下是一个使用 Mailjet 发送邮件的简单示例代码：

package com.litongjava.open.chat.utils;

import org.json.JSONArray;
import org.json.JSONObject;

import com.litongjava.tio.utils.environment.EnvUtils;
import com.mailjet.client.ClientOptions;
import com.mailjet.client.MailjetClient;
import com.mailjet.client.MailjetRequest;
import com.mailjet.client.MailjetResponse;
import com.mailjet.client.errors.MailjetException;
import com.mailjet.client.resource.Emailv31;

public class MailJetSendEmailExample {

    public static void main(String[] args) {
        // 加载环境变量
        EnvUtils.load();
        String key = EnvUtils.getStr("MJ_APIKEY_PUBLIC");
        String secret = EnvUtils.getStr("MJ_APIKEY_PRIVATE");

        // 配置 Mailjet 客户端
        ClientOptions options = ClientOptions.builder()
                .apiKey(key)
                .apiSecretKey(secret)
                .build();
        MailjetClient client = new MailjetClient(options);

        // 邮件内容
        String subject = "My first Mailjet Email!";
        String text = "Greetings from Mailjet!";
        String html = "<h3>Dear passenger 1, welcome to <a href=\"https://www.mailjet.com/\">Mailjet</a>!</h3>"
                    + "<br />May the delivery force be with you!";

        // 发件人信息
        JSONObject from = new JSONObject()
                .put("Email", "no-reply@message.withkimi.app")
                .put("Name", "KIMI");

        // 收件人信息
        JSONArray to = new JSONArray()
                .put(new JSONObject().put("Email", "litongjava@qq.com").put("Name", "You"));

        // 构建邮件内容 JSON
        JSONObject message = new JSONObject()
                .put(Emailv31.Message.FROM, from)
                .put(Emailv31.Message.TO, to)
                .put(Emailv31.Message.SUBJECT, subject)
                .put(Emailv31.Message.TEXTPART, text)
                .put(Emailv31.Message.HTMLPART, html);

        JSONArray messages = new JSONArray().put(message);

        // 构建请求
        MailjetRequest request = new MailjetRequest(Emailv31.resource)
                .property(Emailv31.MESSAGES, messages);

        // 发送请求并处理响应
        try {
            MailjetResponse response = client.post(request);
            System.out.println(response.getStatus());
            System.out.println(response.getData());
        } catch (MailjetException e) {
            throw new RuntimeException(e);
        }
    }
}

发送成功后的响应示例

发送成功后，Mailjet 返回的 JSON 响应如下：

[
  {
    "Status": "success",
    "Cc": [],
    "Bcc": [],
    "CustomID": "",
    "To": [
      {
        "Email": "litongjava@qq.com",
        "MessageHref": "https://api.mailjet.com/v3/REST/message/576460778884839954",
        "MessageUUID": "594ed5ee-f3b0-4aee-b777-2d82eb34e54a",
        "MessageID": 576460778884839954
      }
    ]
  }
]

封装工具类

为了简化邮件发送操作，可以封装一个工具类 MailJetUtils，提供发送文本邮件和 HTML 邮件的静态方法。

package com.litongjava.max.blog.utils;

import org.json.JSONArray;
import org.json.JSONObject;

import com.litongjava.tio.utils.environment.EnvUtils;
import com.mailjet.client.ClientOptions;
import com.mailjet.client.MailjetClient;
import com.mailjet.client.MailjetRequest;
import com.mailjet.client.MailjetResponse;
import com.mailjet.client.errors.MailjetException;
import com.mailjet.client.resource.Emailv31;

public class MailJetUtils {

  /**
   * 发送纯文本邮件
   *
   * @param toName  收件人姓名
   * @param toEmail 收件人邮箱
   * @param subject 邮件主题
   * @param text    邮件内容（纯文本）
   * @return MailjetResponse 响应对象
   */
  public static MailjetResponse sendText(String toName, String toEmail, String subject, String text) {
    JSONObject from = new JSONObject().put("Email", " ").put("Name", "KIMI");

    JSONArray to = new JSONArray().put(new JSONObject().put("Email", toEmail).put("Name", toName));

    JSONObject message = new JSONObject()
        //
        .put(Emailv31.Message.FROM, from)
        //
        .put(Emailv31.Message.TO, to)
        //
        .put(Emailv31.Message.SUBJECT, subject)
        //
        .put(Emailv31.Message.TEXTPART, text);

    JSONArray messages = new JSONArray().put(message);
    return send(messages);
  }

  /**
   * 发送 HTML 格式邮件
   *
   * @param toName  收件人姓名
   * @param toEmail 收件人邮箱
   * @param subject 邮件主题
   * @param html    邮件内容（HTML 格式）
   * @return MailjetResponse 响应对象
   */
  public static MailjetResponse sendHtml(String toName, String toEmail, String subject, String html) {
    JSONObject from = new JSONObject().put("Email", "no-reply@message.withkimi.app").put("Name", "KIMI");

    JSONArray to = new JSONArray().put(new JSONObject().put("Email", toEmail).put("Name", toName));

    JSONObject message = new JSONObject()
        //
        .put(Emailv31.Message.FROM, from)
        //
        .put(Emailv31.Message.TO, to)
        //
        .put(Emailv31.Message.SUBJECT, subject)
        //
        .put(Emailv31.Message.HTMLPART, html);

    JSONArray messages = new JSONArray().put(message);
    return send(messages);
  }

  /**
   * 发送邮件请求
   *
   * @param messages 邮件消息数组
   * @return MailjetResponse 响应对象
   */
  private static MailjetResponse send(JSONArray messages) {
    MailjetRequest request = new MailjetRequest(Emailv31.resource).property(Emailv31.MESSAGES, messages);

    String key = EnvUtils.getStr("MJ_APIKEY_PUBLIC");
    String secret = EnvUtils.getStr("MJ_APIKEY_PRIVATE");

    ClientOptions options = ClientOptions.builder().apiKey(key).apiSecretKey(secret).build();
    MailjetClient client = new MailjetClient(options);

    try {
      return client.post(request);
    } catch (MailjetException e) {
      throw new RuntimeException("邮件发送失败", e);
    }
  }
}

工具类说明

• sendText：发送纯文本格式的邮件。
• sendHtml：发送 HTML 格式的邮件。
• send：内部方法，负责构建并发送邮件请求。

测试工具类

使用 JUnit 测试工具类 MailJetUtils 的发送功能，确保集成正确。

package com.litongjava.open.chat.utils;

import org.junit.Test;

import com.litongjava.tio.utils.environment.EnvUtils;
import com.mailjet.client.MailjetResponse;

public class MailJetUtilsTest {

    @Test
    public void testSendHtmlEmail() {
        // 加载环境变量
        EnvUtils.load();

        // 邮件内容
        String subject = "My first Mailjet Email!";
        String html = "<h3>Dear passenger 1, welcome to <a href=\"https://www.mailjet.com/\">Mailjet</a>!</h3>"
                    + "<br />May the delivery force be with you!";
        String toEmail = "litongjava@qq.com";
        String toName = "You";

        // 发送邮件
        MailjetResponse response = MailJetUtils.sendHtml(toName, toEmail, subject, html);

        // 输出响应状态和数据
        System.out.println("响应状态: " + response.getStatus());
        System.out.println("响应数据: " + response.getData());
    }
}

测试步骤：

1. 确保 app.properties 文件中的 API 密钥配置正确。
2. 运行 MailJetUtilsTest 测试方法。
3. 检查控制台输出，确认邮件发送状态和响应数据。

整合 Enjoy 发送邀请邮件

在 Enjoy 框架中集成 Mailjet 发送邀请邮件，以下是具体步骤。

邮件模板

创建一个 HTML 邮件模板 student_register_mail.html，用于发送邀请邮件。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <title>Sign Up</title>
  </head>
  <body>
    <h3>Dear Student,</h3>
    <p>We are excited to invite you to register.</p>
    <p>
      This is a fantastic opportunity to enhance your skills, connect with peers, and take advantage of the resources we
      offer to support your academic and personal growth.
    </p>

    <p>To secure your spot, please complete your registration by clicking the link below:</p>

    <a href="#(link)">Here</a>

    <p>
      Do not miss out on this chance to be part of a vibrant and supportive community. If you have any questions or need
      assistance with the registration process, feel free to reach out to us at
      <a href="https://collegebot.ai/">CollegeBot AI</a>.
    </p>

    <p>We look forward to welcoming you!</p>

    <p>Best regards,</p>

    <p>The College Bot AI Team</p>
  </body>
</html>

模板说明：

• #(link) 是占位符，发送邮件时会被实际的注册链接替换。
• 使用简单的 HTML 结构，确保邮件在各种邮件客户端中都能良好显示。

EmailService 服务类

创建 EmailService 类，负责处理邀请邮件的发送逻辑。

package com.litongjava.max.blog.service;

import com.jfinal.kit.Kv;
import com.jfinal.template.Engine;
import com.jfinal.template.Template;
import com.litongjava.db.activerecord.Db;
import com.litongjava.max.blog.consts.TableNames;
import com.litongjava.max.blog.utils.MailJetUtils;
import com.litongjava.model.body.RespBodyVo;

public class EmailService {

  /**
   * 发送邀请邮件给指定的学生
   *
   * @param origin     请求的原始地址，用于生成注册链接
   * @param studentIds 学生的 ID 数组
   * @return RespBodyVo 响应体对象
   */
  public RespBodyVo sendInviteEmail(String origin, long[] studentIds) {
    // 加载邮件模板
    Template template = Engine.use().getTemplate("student_register_mail.html");

    for (long id : studentIds) {
      // 生成注册链接
      String link = origin + "/auth/register?role=student&id=" + id;
      // 渲染模板，替换链接占位符
      String content = template.renderToString(Kv.by("link", link));
      String subject = "Join Our Community! Register Today";

      // 查询学生邮箱
      String sql = String.format("SELECT email FROM %s WHERE id=?", TableNames.max_blog_users);
      String email = Db.queryStr(sql, id);
      // 从邮箱地址中提取用户名作为收件人姓名
      String name = email.split("@")[0];

      // 发送 HTML 格式的邀请邮件
      MailJetUtils.sendHtml(name, email, subject, content);
    }
    return RespBodyVo.ok();
  }
}

服务类说明：

• sendInviteEmail 方法接收原始请求地址和学生 ID 数组，逐个生成注册链接并发送邀请邮件。
• 使用 JFinal 的模板引擎渲染邮件内容，将 link 占位符替换为实际的注册链接。
• 从数据库中查询学生的邮箱地址，并提取用户名作为收件人姓名。
• 使用 MailJetUtils.sendHtml 方法发送 HTML 格式的邀请邮件。

工具类扩展

在 MailJetUtils 工具类中添加 sendHtml 方法，用于发送 HTML 格式的邮件（已在前文封装工具类部分提供）。

public static MailjetResponse sendHtml(String toName, String toEmail, String subject, String html) {
    // 实现详见封装工具类部分
}

发送后的响应示例

成功发送邮件后，Mailjet 返回的响应 JSON 示例：

[
  {
    "Status": "success",
    "Cc": [],
    "Bcc": [],
    "CustomID": "",
    "To": [
      {
        "Email": "litongjava@qq.com",
        "MessageHref": "https://api.mailjet.com/v3/REST/message/576460778884839954",
        "MessageUUID": "594ed5ee-f3b0-4aee-b777-2d82eb34e54a",
        "MessageID": 576460778884839954
      }
    ]
  }
]

响应字段说明：

• Status：邮件发送状态，success 表示成功。
• To：包含收件人的详细信息，如邮箱地址、消息链接、UUID 和消息 ID。
• MessageHref：指向该邮件消息的 Mailjet API 链接，可用于后续查询或跟踪。
• MessageUUID 和 MessageID：唯一标识符，可用于日志记录和问题排查。

---

总结

通过本文档，开发者可以快速在 Java 项目中集成 Mailjet，实现邮件发送功能。文档详细介绍了 Maven 依赖配置、应用配置文件设置、工具类封装、测试方法以及在 Enjoy 框架中的实际应用示例。通过封装好的工具类，开发者可以方便地发送纯文本或 HTML 格式的邮件，满足不同场景的需求。

建议：

• 确保 Mailjet API 密钥的安全，避免在版本控制系统中泄露。
• 使用模板引擎（如 JFinal）管理邮件模板，方便维护和更新。
• 在生产环境中，结合异常处理和日志记录，提升邮件发送的可靠性和可维护性。