📧邮件发送

wind大约 7 分钟

安装

maven引入

    JDK11以下
  <dependency>
    <groupId>org.dromara.sms4j</groupId>
    <artifactId>sms4j-Email-core</artifactId>
    <version> 最新版本跟随sms4j </version>
  </dependency>
----------------------------------
    JDK11以上
  <dependency>
    <groupId>org.dromara.sms4j</groupId>
    <artifactId>sms4j-email-jakarta-core</artifactId>
    <version> 最新版本跟随sms4j </version>
  </dependency>

配置

Email-plugin不做特殊适配，不严格要求配置形式，不管你是java se还是springboot 还是solon，都可以直接进行使用，兼容JDK17。
在框架的默认中，是维护了一个配置资源池，但是不会关注资源池内的对象是否是一样的，所以你可以用它来实现类似于多租户的功能
框架不会关注你的数据的来源和方式，只会关注最终对象池中的对象。所以，你可以尽情的发挥，从数据库获取，从redis获取，从消息队列获取等等等等……

提示

自3.X版本开始，邮件插件支持失败自动重试功能，默认重试次数1次，可以通过配置进行修改，0则为不重试

配置字段：

      端口号
     String port;
     
     发件人地址
     String fromAddress;
     
     服务器地址
     String smtpServer;
     
     账号
     String username;
     
     密码   注意的是如果你用的是QQ或者网易之类的邮箱需要的不是登录密码，而是授权码
     String password;
     
     是否开启ssl 默认开启 QQ之类的邮箱默认都需要ssl
     String isSSL = "true";
     
     是否开启验证 默认开启
     String isAuth = "true";
     
     重试间隔（单位：秒），默认为5秒
     int retryInterval = 5;

     重试次数，默认为1次
     int maxRetries = 1;

配置对象托管入对象池

//以下仅做演示，实际使用需要填入数据
MailSmtpConfig config = MailSmtpConfig.builder.build;

//这里的key可以是任何可对比类型，用于后续从工厂取出邮件实现类用
MailFactory.put("qq",config)

使用

我们在将配置放入配置池后，可以通过 MailFactory工厂获取到对应配置的邮件客户端实现，例如我们刚刚放置的key为“qq”的配置

MailClient mail = MailFactory.createMailClient("qq");

黑名单过滤

在发送邮件时，我们有时候需要过滤掉某些账号，这时我们可以使用黑名单过滤功能
1.首先我们实现一个位于org.dromara.email.api包的Blacklist接口，并实现getBlacklist方法,在这里，方法的返回值就是需要过滤掉的邮箱地址，至于你过滤数据的来源，框架并不进行关注
示例：

public class BlackListImpl implements BlackList {

    @Override
    public List<String> getBlackList() {
        List<String> blackList = new ArrayList<>();
        blackList.add("111111111@qq.com");
        return blackList;
    }
}

2.在获取邮件客户端实例的时候我们需要将回调的对象传递至工厂
当然，Blacklist也是一个函数式接口，你也可以通过lambda表达式来构建
示例：

MailClient mail = MailFactory.createMailClient("qq",new BlackListImpl);

提示

获取到的带有过滤黑名单过滤功能的客户端与普通的客户端方法完全一致，只是在发送时他会首先将黑名单中的号码进行排除。

方法使用

目前，插件支持

html模板邮件
普通文本邮件
携带附件的文本邮件
携带附件的html模板邮件
同时携带文字正文和html模板和附件的邮件（在多数的邮箱中其实并不支持这种形式，在展示的时候html会把正文覆盖，但是也有少数的邮箱支持这种的渲染）
压缩文件

html模板邮件

html默认会读取 resources/template目录下的文件,也可以使用InputStream流来指定一个位置的文件
html模板邮件是框架内部进行的定义，实际上是将给定的模板进行的转译，你可以创建一个标准的html文件，然后在文件内部需要放置内容的地方用#{变量名}的形式进行替代，
这样在框架拿到html文件后会将内部的变量替换成你给定的值

MailMessage信息解析

MailMessage是一个精心设计的建造者模式的类，他里面囊括了所有邮件类型所需的参数信息，可以非常方便的构建一个单发或者群发邮件

        MailMessage message = MailMessage.Builder()
                //收件人地址，此处可以为字符串的单个地址也可以为一个List<String>的群发地址
                //例如  .mailAddress (new ArrayList<String>().add("XXXXXXXXX@qq.com"))
                .mailAddress ("XXXXXXXXX@qq.com")
                // 邮件的标题
                .title("测试标题")
                // 邮件的文字正文，但是如果发送html邮件时候，大多数的邮件服务商会隐藏掉body的信息
                .body("测试邮件发送")
                //html模板来源，此处与mailAddress相似可以为一个字符串形式的html文件名，此时默认读取resources/template目录下的文件
                //也可以为一个 InputStream 输入流
                //例如 .html(Files.newInputStream(new File("D:\\index.html").toPath()))
                .html("index.html")
                /* html模板变量，如果你的html不需要变量，则可以为空，这里有多种的用法
                Map map的key为变量名称，map的value为变量的值  
                例如 Map<String,String> map = new HashMap<String,String>().put("变量名称","变量值");    .htmlValues(map)
                还可以直接写入变量名称和变量值 如.htmlValues("变量名称",“变量值”)
                此处也可以使用接口进行，接口形式在下方详细介绍
                */
                .htmlValues(map)
                //抄送人，可以添加一个或多个，使用方式与.mailAddress一致
                .cc("xxxxxx@qq.com")
                // 密送人，可以添加一个或多个，使用方式与.mailAddress一致
                .bcc("xxxxxx@qq.com")
                // 附件，此处与.htmlValues使用方法相似，如果你只有一个附件，可以直接填写key value 如果你有多个附件，这里可以接受一个map
                .files(“文件名”,"文件路径")
                //3.0版本支持发送文件自动压缩，你可以选择指定这里的压缩文件名称，框架将会自动将 .files中的所有文件打为一个压缩包并发送
                .zipName("压缩文件名称")
                .build();

邮件发送

邮件发送只需要一个方法,方法接收 MailMessage 作为参数

MailClient mail = MailFactory.createMailClient("qq");
mail.send(message);

Parameter接口

这个接口是一个空接口，主要的作用是为了标定实体类类型，一旦某实体类实现了这个接口，则实体可以直接作为MailMessage中的htmlValues参数，对象字段名称将作为模板
变量名称，字段值将作为模板变量值
示例：

@Data
public class EntityText implements Parameter{
    private String name;
    private String size;
}

EntityText entity = new EntityText();
entity.setName("这是变量name的值");
entity.setSize("这是变量size的值");

MailMessage message = MailMessage.Builder()
.mailAddress ("XXXXXXXXX@qq.com")
 .title("测试标题")
 .html("index.html")
 .htmlValues(entity)
 .build();
 
MailClient mail = MailFactory.createMailClient("qq");
mail.send(message);

小技巧

在使用中，如果我们不经常更改配置信息，并且配置信息很少的情况下，我们可以将工厂构建出来的 MailClient 对象交给容器托管（例如spring或者solon）
spring示例：

@Configuration
public class MailConfig{
    @Bean("qqMailClient")
    public MailClient qqMailClient(){
        //以下仅做演示，实际使用需要填入数据
        MailSmtpConfig config = MailSmtpConfig.builder.build;
        //这里的key可以是任何可对比类型，用于后续从工厂取出邮件实现类用
        MailFactory.put("qq",config);
        return  MailFactory.createMailClient("qq");
    }
}

solon示例：

@Configuration
public class MailConfig{
    @Bean
    public MailClient qqMailClient(){
        //以下仅做演示，实际使用需要填入数据
        MailSmtpConfig config = MailSmtpConfig.builder.build;
        //这里的key可以是任何可对比类型，用于后续从工厂取出邮件实现类用
        MailFactory.put("qq",config);
        return  MailFactory.createMailClient("qq");
    }
}

📧邮件发送

# 安装

# 配置

# 配置对象托管入对象池

# 使用

# 黑名单过滤

# 方法使用

# html模板邮件

# MailMessage信息解析

# 邮件发送

# Parameter接口

# 小技巧

安装

配置