Configuration

Spring Boot Mail Properties

Use Spring Boot mail properties to define basic email sending parameters, such as protocol, host, port, and others.

For example:

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

Also, you can specify JavaMail properties in the format spring.mail.properties.*. For example, the mail.smtp.auth property can be provided as follows:

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

Jmix Email Properties

Jmix email properties allow you to configure the functionality described in the Email Sending API section.

jmix.email.from-address

Defines the default sender’s address. It is used if the EmailInfo.from attribute is not specified.

Default value: DoNotReply@localhost

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

Property is used in asynchronous sending of emails to skip the first few calls of Emailer.processQueuedEmails() after server startup to reduce the load during application initialization. Email sending will start with the next call.

Default value: 2

jmix.email.message-queue-capacity

Property is used for asynchronous sending, the maximum number of messages read from the queue and sent in one call of Emailer.processQueuedEmails().

Default value: 100

jmix.email.default-sending-attempts-limit

Property is used for asynchronous sending, the default number of attempts to send an email. It is used if the attemptsCount parameter is not specified when calling Emailer.sendEmailAsync().

Default value: 10

jmix.email.sending-timeout-sec

Defines the maximum expected time in seconds, which is required to send an email to the SMTP server. It is used for asynchronous sending to optimize the selection of SendingMessage objects from the DB queue.

Default value: 240

jmix.email.admin-addresss

Defines the address, to which all messages are sent if the jmix.email.send-all-to-admin property is switched on.

Default value: admin@localhost

jmix.email.send-all-to-admin

Indicates that all messages should be sent to the jmix.email.admin-address address, regardless of the specified recipient’s address. It is recommended to use this parameter during system development and debugging.

Default value: false

jmix.email.use-file-storage

When turned on, email body text and attachments will be stored in file storage instead of BLOB columns in the database. Should be used if the application stores lots of emails and/or email attachments.

Default value: false

jmix.email.async-sending-username

Defines the login of the system user, used by asynchronous email sending code to be able to persist the information to the database. It is recommended to create a separate user (for example, emailer) without a password so that it will be impossible to log in under their name via user interface. This is also convenient to search for messages related to email sending in the server log.

Default value: admin

jmix.email.use-default-quartz-configuration

Defines whether the Default Quartz Configuration of the Email Sending is used.

Default value: true

jmix.email.email-sending-cron

Defines the CRON expression that is used by default in quartz scheduling configuration of the Email Sending .

Default value: 0 * * * * ? (every minute).

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

Defines whether the Default Quartz Configuration of the Email Cleaning is used.

Default value: false

jmix.email.email-cleaning-cron

Defines the CRON expression that is used by default in quartz scheduling configuration of the Email Cleaning .

Default value: 0 0 0 * * ? (in the begining of every day)

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

Defines the maximum age (in days) of important messages after which they must be deleted. Zero value (0) means that messages won’t be removed.

Default value: 0

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

Defines the maximum age (in days) of messages after which they must be deleted. Zero value (0) means that messages won’t be removed.

Default value: 0

jmix.email.clean-file-storage

Defines whether the file storage cleaning should be performed while the cleaning scheduler is working.

Default value: false

Email Sending Scheduler

When you call the Emailer.sendEmailAsync() method, an email is not sent but queued in the database. To send queued emails, you need to invoke the Emailer.processQueuedEmails() method.

You can use Quartz Job Scheduler for periodic processing of the email queue as described below.

Default Quartz Configuration

The add-on provides the default configuration of Quartz Job Scheduler. To process the email queue regularly, do the following:

  1. Include Quartz in your project as described in the Quartz Job Scheduler Setup section.

  2. Change scheduling as CRON expression if necessary using the jmix.email.email-sending-cron property.

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

Custom Quartz Configuration

If you want to use a custom Quartz configuration, do the following:

  1. Include Quartz in your project as described in the Quartz Job Scheduler Setup section.

  2. Create a job class:

    public class MyCustomEmailSendingJob implements Job {

    @Autowired
    private Emailer emailer;

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

  3. Add the following beans to the main application class:

    @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();
}

Email Cleaning Scheduler

The add-on has a built-in cleaning Quartz Job Scheduler that is switched off by default. You can use it for periodic cleaning emails as described below.

If you need to keep some emails, use the "important" flag and set the maximum age for important and non important emails. You can set this flag using the setImportant() method of the EmailInfoBuilder.

Default Quartz Configuration

The add-on provides the default configuration of Quartz Job Scheduler. To clean emails regularly, do the following:

  1. Include Quartz in your project as described in the Quartz Job Scheduler Setup section.

  2. Set the jmix.email.use-default-email-cleaning-quartz-configuration property to true.

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

  3. Change scheduling as CRON expression if necessary using the jmix.email.email-cleaning-cron property.

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

  4. Set the age for important and non important emails using the jmix.email.max-age-of-important-messages and jmix.email.max-age-of-non-important-messages properties, for example:

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

  5. Set the jmix.email.clean-file-storage property to true in case you want to delete attachments.

Custom Quartz Configuration

If you want to use a custom Quartz configuration, do the following:

  1. Include Quartz in your project as described in the Quartz Job Scheduler Setup section.

  2. Create a job class:

    public class MyCustomEmailCleaningJob implements Job {

    @Autowired
    private EmailCleaner emailCleaner;

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

  3. Add the following beans to the main application class:

    @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();
}

  4. Set the age for important and non important emails using the jmix.email.max-age-of-important-messages and jmix.email.max-age-of-non-important-messages properties, for example:

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

  5. Set the jmix.email.clean-file-storage property to true in case you want to delete attachments.

File Storage Usage

You can store email body text and attachments in file storage instead of BLOB columns in the database.

To use file storage:

  1. Add the following line to the dependencies section of your build.gradle file:

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

  2. Enable file storage usage. Set in application.properties file:

    jmix.email.use-file-storage=true

By default, the local file storage is located in the application work directory at ${user.dir}/.jmix/work/filestorage.