配置

Spring Boot 邮件属性

使用 Spring Boot 邮件属性 设置基本的电子邮件发送参数，例如，协议、主机、端口等。

示例：

spring.mail.host=smtp.company.com
spring.mail.port=587
spring.mail.protocol=smtp
spring.mail.username=username
spring.mail.password=password

另外，可以用 spring.mail.properties.* 格式指定 JavaMail 属性。例如，mail.smtp.auth 属性可以这样设置：

spring.mail.properties.mail.smtp.auth=true

Jmix 邮件属性

Jmix 邮件属性支持对 电子邮件 API 部分的功能进行配置。

jmix.email.from-address

设置默认的发件人地址。如果 EmailInfo.from 未定义，则使用该值。

默认值：DoNotReply@localhost

jmix.email.scheduled-sending-delay-call-count

属性用于异步发送电子邮件，在服务器启动后跳过前几次调用 Emailer.processQueuedEmails()，以减少应用程序初始化期间的负载。邮件发送将从下一个调用开始。

默认值：2

jmix.email.message-queue-capacity

属性用于异步发送，设置一次调用 Emailer.processQueuedEmails() 时，从队列中读取并发送的最大邮件数量。

默认值：100

jmix.email.default-sending-attempts-limit

属性用于异步发送，设置默认尝试发送邮件的次数。如果调用 Emailer.sendEmailAsync() 时未指定 attemptsCount 参数，则使用该参数。

默认值：10

jmix.email.sending-timeout-sec

设置将电子邮件发送到 SMTP 服务器所需的最大期望时间（以秒为单位）。用于异步发送，用于优化从 DB 队列中选择 SendingMessage 对象的速度。

默认值：240

jmix.email.admin-address

设置一个收件人地址，如果启用 jmix.email.send-all-to-admin 属性，所有邮件都将发送到该地址。

默认值：admin@localhost

jmix.email.send-all-to-admin

设置将所有邮件都发送到 jmix.email.admin-address 地址，无论收件人地址是什么。建议在系统开发和调试时使用该参数。

默认值：false

jmix.email.use-file-storage

启用后，电子邮件正文和附件将保存在文件存储中，而不是数据库的 BLOB 列中。如果应用程序需要存储大量邮件或邮件附件，则应该使用文件存储。

默认值：false

jmix.email.async-sending-username

设置系统用户的登录名，异步邮件发送的代码使用该用户名将信息持久化保存到数据库中。建议创建一个没有密码的单独用户（例如，emailer），无法通过用户界面使用此用户名登录。另外，也方便在服务器日志中搜索与邮件发送相关的消息。

默认值：admin

jmix.email.use-default-quartz-configuration

设置是否使用 默认 Quartz 配置 发送邮件。

默认值：true

jmix.email.email-sending-cron

设置发送邮件 Quartz 调度使用的默认 cron 表达式。

默认值：0 * * * * ?（每分钟）

jmix.email.use-default-email-cleaning-quartz-configuration

设置是否使用 默认 Quartz 配置 清理邮件。

默认值：false

jmix.email.email-cleaning-cron

设置清理邮件 Quartz 调度使用的默认 cron 表达式。

默认值：0 0 0 * * ?（每天 0 点）

jmix.email.max-age-of-important-messages

设置重要邮件保留的最长时间（以天为单位），超时后，邮件将被删除。零值（0）表示不删除。

默认值：0

jmix.email.max-age-of-non-important-messages

设置普通邮件保留的最长时间（以天为单位），超时后，邮件将被删除。零值（0）表示不删除。

默认值：0

jmix.email.clean-file-storage

设置是否在清理邮件调度器工作时也同时清理文件存储。

默认值：false

邮件发送调度器

当调用 Emailer.sendEmailAsync() 方法时，邮件并未发送，而是进入数据库排队。如需发送队列中的邮件，需要调用 Emailer.processQueuedEmails() 方法。

你可以使用 Quartz Job Scheduler 周期性地处理邮件队列。

默认 Quartz 配置

电子邮件扩展组件提供 Quartz 任务的默认配置，用于处理邮件发送队列。按照下列步骤使用：

  1. 为项目添加 Quartz 扩展组件，按照 Quartz 安装 章节的说明进行添加。

  2. 如果需要的话，用 jmix.email.email-sending-cron 应用程序属性修改 cron 表达式：

    jmix.email.email-sending-cron=* 0/2 * * * ?

自定义 Quartz 配置

如需使用自定义的 Quartz 任务配置，按照下列步骤：

  1. 为项目添加 Quartz 扩展组件，按照 Quartz 安装 章节的说明进行添加。

  2. 设置 jmix.email.use-default-quartz-configuration 应用程序属性为 false：

    jmix.email.use-default-quartz-configuration = false

  3. 创建一个任务类：

    public class MyCustomEmailSendingJob implements Job {

    @Autowired
    private Emailer emailer;

    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        emailer.processQueuedEmails();
    }
}

  4. 在运行的应用程序中，打开 Quartz → Quartz jobs（Quartz 任务） 视图，并为 MyCustomEmailSendingJob 类配置一个任务。

  5. 或者，如果需要在开发阶段配置邮件发送的任务，将下面的 bean 添加至主应用程序类：

    @Bean
JobDetail myCustomEmailSendingJob() {
    return JobBuilder.newJob()
            .ofType(MyCustomEmailSendingJob.class)
            .storeDurably()
            .withIdentity("emailSending")
            .build();
}

@Bean
Trigger myCustomEmailSendingTrigger() {
    return TriggerBuilder.newTrigger()
            .forJob(myCustomEmailSendingJob())
            .startNow()
            .withSchedule(CronScheduleBuilder.cronSchedule("* 0/2 * * * ?"))
            .build();
}

邮件清理调度器

该扩展组件带有一个内置的邮件清理 Quartz 任务，默认是关闭的。可以按照下列步骤使用这个任务周期性地清理邮件。

如需将某些邮件保存长一些，可以使用 important（重要） 标签进行标记，并设置重要和普通邮件的最长保存时间。可以通过 EmailInfoBuilder 的 setImportant() 方法设置该标记。

默认 Quartz 配置

如需使用清理邮件的默认 Quartz job 配置，按照下列步骤：

  1. 为项目添加 Quartz 扩展组件，按照 Quartz 安装 章节的说明进行添加。

  2. 设置 jmix.email.use-default-email-cleaning-quartz-configuration 属性为 true：

    jmix.email.use-default-email-cleaning-quartz-configuration=true

  3. 如果需要的话，用 jmix.email.email-cleaning-cron 应用程序属性修改 cron 表达式：

    jmix.email.email-cleaning-cron=0 0 0 1/2 * ?

  4. 设置重要和普通邮件的保存时长，使用 jmix.email.max-age-of-important-messages 和 jmix.email.max-age-of-non-important-messages 属性，示例：

    jmix.email.max-age-of-non-important-messages=5
jmix.email.max-age-of-important-messages=30

  5. 如需删除附件，设置 jmix.email.clean-file-storage 属性为 true。

自定义 Quartz 配置

如需使用自定义的 Quartz 任务配置，按照下列步骤：

  1. 为项目添加 Quartz 扩展组件，按照 Quartz 安装 章节的说明进行添加。

  2. 创建一个任务类：

    public class MyCustomEmailCleaningJob implements Job {

    @Autowired
    private EmailCleaner emailCleaner;

    @Override
    public void execute(JobExecutionContext context) throws JobExecutionException {
        emailCleaner.deleteOldEmails();
    }
}

  3. 在运行的应用程序中，打开 Quartz → Quartz jobs（Quartz 任务） 视图，然后为 MyCustomEmailCleaningJob 类配置一个任务。

  4. 或者，如果需要在开发阶段配置邮件清理的任务，将下面的 bean 添加至主应用程序类：

    @Bean
JobDetail myCustomEmailCleaningJob() {
    return JobBuilder.newJob()
            .ofType(MyCustomEmailCleaningJob.class)
            .storeDurably()
            .withIdentity("emailCleaning")
            .build();
}

@Bean
Trigger MyCustomEmailCleaningTrigger() {
    return TriggerBuilder.newTrigger()
            .forJob(myCustomEmailCleaningJob())
            .startNow()
            .withSchedule(CronScheduleBuilder.cronSchedule("0 0 0 1/2 * ? "))
            .build();
}

  5. 设置重要和普通邮件的保存时长，使用 jmix.email.max-age-of-important-messages 和 jmix.email.max-age-of-non-important-messages 属性，示例：

    jmix.email.max-age-of-non-important-messages=5
jmix.email.max-age-of-important-messages=30

  6. 如需删除附件，设置 jmix.email.clean-file-storage 属性为 true。

使用文件存储

电子邮件正文和附件可以保存在文件存储中，而不是数据库的 BLOB 列中。

使用文件存储：

  1. 在 build.gradle 文件的 dependencies 部分添加如下内容：

    implementation 'io.jmix.localfs:jmix-localfs-starter'

  2. 在 application.properties 文件中设置启用文件存储：

    jmix.email.use-file-storage=true

默认情况下，本地文件存储位于应用程序的工作目录：${user.dir}/.jmix/work/filestorage。