Свойства Email

Свойства Spring Boot Mail

Используйте свойства Spring Boot для почты, чтобы определить основные параметры отправки писем, такие как протокол, хост, порт и другие.

Например:

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

Также вы можете указать свойства JavaMail в формате spring.mail.properties.*. Например, свойство mail.smtp.auth можно задать следующим образом:

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

Свойства Jmix Email

Свойства Jmix email позволяют настроить функциональность, описанную в разделе Email Sending 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

Свойство используется для асинхронной отправки, количество попыток отправить письмо по умолчанию. Используется, если параметр attemptsCount не указан при вызове Emailer.sendEmailAsync().

Значение по умолчанию: 10

jmix.email.sending-timeout-sec

Определяет максимально ожидаемое время в секундах, необходимое для отправки письма на SMTP-сервер. Используется для асинхронной отправки для оптимизации выборки объектов 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

Определяет CRON-выражение, которое используется по умолчанию в конфигурации планирования Quartz для отправки писем.

Значение по умолчанию: 0 * * * * ? (каждую минуту).

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

Определяет, используется ли конфигурация Quartz по умолчанию для очистки писем.

Значение по умолчанию: false

jmix.email.email-cleaning-cron

Определяет CRON-выражение, которое используется по умолчанию в конфигурации планирования Quartz для очистки писем.

Значение по умолчанию: 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

jmix.email.oauth2.enabled

Если true, включает использование авторизации на основе токена OAuth 2.0 для подключения к почтовому серверу.

jmix.email.oauth2.provider

Определяет провайдера OAuth для почты.

jmix.email.oauth2.client-id

Определяет идентификатор клиента OAuth (client id).

jmix.email.oauth2.secret

Определяет секрет клиента OAuth (client secret).

jmix.email.oauth2.tenant-id

Определяет идентификатор тенанта OAuth (tenant id).

jmix.email.oauth2.refresh-token

Определяет токен обновления OAuth (refresh token).

Планировщик отправки писем

При вызове метода Emailer.sendEmailAsync() письмо не отправляется, а ставится в очередь в базе данных. Для отправки писем из очереди необходимо вызвать метод Emailer.processQueuedEmails().

Вы можете использовать планировщик заданий Quartz для периодической обработки очереди писем, как описано ниже.

Конфигурация Quartz по умолчанию

Дополнение Email Sending предоставляет конфигурацию задачи Quartz по умолчанию для обработки очереди отправки писем. Чтобы использовать ее, выполните следующие действия:

  1. Включите дополнение Quartz в свой проект, как описано в разделе Quartz / Установка.

  2. При необходимости измените CRON-выражение, используя свойство jmix.email.email-sending-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. Создайте класс задачи:

    import io.jmix.email.Emailer;
import org.quartz.Job;
import org.quartz.JobExecutionContext;
import org.quartz.JobExecutionException;
import org.springframework.beans.factory.annotation.Autowired;

public class MyCustomEmailSendingJob implements Job {

    @Autowired
    private Emailer emailer;

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

  4. В работающем приложении откройте экран Quartz → Quartz jobs и настройте задачу для класса MyCustomEmailSendingJob.

  5. Альтернативно, если вы хотите настроить задачу отправки писем на этапе разработки, добавьте следующие бины в основной класс приложения:

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

@Bean
Trigger myCustomEmailSendingTrigger() {
    return TriggerBuilder.newTrigger() (3)
            .forJob(myCustomEmailSendingJob()) (4)
            .startNow()
            .withSchedule(CronScheduleBuilder.cronSchedule("* 0/2 * * * ?"))
            .build(); (5)
}
    1 Начните построение определения задачи с помощью класса org.quartz.JobBuilder.
    2 Создайте экземпляр org.quartz.JobDetail.
    3 Начните построение определения триггера с помощью класса org.quartz.TriggerBuilder.
    4 Свяжите этот триггер с ранее определенной задачей.
    5 Создайте экземпляр org.quartz.Trigger.

Планировщик очистки писем

Дополнение имеет встроенную задачу Quartz для очистки, которая по умолчанию выключена. Вы можете использовать ее для периодической очистки сохраненных писем, как описано ниже.

Если вам нужно хранить некоторые письма дольше, используйте флаг important и установите максимальный возраст для важных и неважных писем. Вы можете установить этот флаг с помощью метода setImportant() у EmailInfoBuilder.

Конфигурация Quartz по умолчанию

Чтобы использовать конфигурацию задачи Quartz по умолчанию для регулярной очистки писем, выполните следующие действия:

  1. Включите дополнение Quartz в свой проект, как описано в разделе Quartz / Установка.

  2. Установите значение свойства jmix.email.use-default-email-cleaning-quartz-configuration в true:

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

  3. При необходимости измените CRON-выражение, используя свойство jmix.email.email-cleaning-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. Создайте класс задачи:

    import io.jmix.email.EmailCleaner;
import org.quartz.Job;
import org.quartz.JobExecutionContext;
import org.quartz.JobExecutionException;
import org.springframework.beans.factory.annotation.Autowired;

public class MyCustomEmailCleaningJob implements Job {

    @Autowired
    private EmailCleaner emailCleaner;

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

  3. В работающем приложении откройте экран Quartz → Quartz jobs и настройте задачу для класса MyCustomEmailCleaningJob.

  4. Альтернативно, если вы хотите настроить задачу очистки писем на этапе разработки, добавьте следующие бины в основной класс приложения:

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

@Bean
Trigger MyCustomEmailCleaningTrigger() {
    return TriggerBuilder.newTrigger() (3)
            .forJob(myCustomEmailCleaningJob()) (4)
            .startNow()
            .withSchedule(CronScheduleBuilder.cronSchedule("0 0 0 1/2 * ? "))
            .build(); (5)
}
    1 Начните построение определения задачи с помощью класса org.quartz.JobBuilder.
    2 Создайте экземпляр org.quartz.JobDetail.
    3 Начните построение определения триггера с помощью класса org.quartz.TriggerBuilder.
    4 Свяжите этот триггер с ранее определенной задачей.
    5 Создайте экземпляр org.quartz.Trigger.

  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. Убедитесь, что следующая строка присутствует в разделе dependencies вашего файла build.gradle:

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

  2. Включите использование файлового хранилища. Установите в файле application.properties:

    jmix.email.use-file-storage=true

По умолчанию локальное файловое хранилище находится в рабочем каталоге приложения по пути ${user.dir}/.jmix/work/filestorage.