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.fromAddress

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

Default value: DoNotReply@localhost

jmix.email.scheduledSendingDelayCallCount

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.messageQueueCapacity

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.defaultSendingAttemptsCount

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.sendingTimeoutSec

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.adminAddress

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

Default value: admin@localhost

jmix.email.sendAllToAdmin

Indicates that all messages should be sent to the jmix.email.adminAddress 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.useFileStorage

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.emailerUserLogin

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

Configuring Quartz 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.

Follow the steps below to use Quartz Job Scheduler for periodic processing of the email queue.

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

    implementation 'org.springframework.boot:spring-boot-starter-quartz'
  2. Add the following properties to the application.properties file:

    spring.quartz.job-store-type=jdbc
    spring.quartz.jdbc.initialize-schema=always

    If you use PostgreSQL and get the exception "org.quartz.JobPersistenceException: Couldn’t retrieve job: Bad value for type long" on application start, set the following property:

    spring.quartz.properties.org.quartz.jobStore.driverDelegateClass=org.quartz.impl.jdbcjobstore.PostgreSQLDelegate
  3. Create a job class:

    public class EmailSendingJob implements Job {
    
        @Autowired
        private Emailer emailer;
    
        @Override
        public void execute(JobExecutionContext context) throws JobExecutionException {
            emailer.processQueuedEmails();
        }
    }
  4. Add the following beans to the main application class:

    @Bean
    JobDetail emailSendingJob() {
        return JobBuilder.newJob()
                .ofType(EmailSendingJob.class)
                .storeDurably()
                .withIdentity("emailSending")
                .build();
    }
    
    @Bean
    Trigger emailSendingTrigger() {
        return TriggerBuilder.newTrigger()
                .forJob(emailSendingJob())
                .startNow()
                .withSchedule(CronScheduleBuilder.cronSchedule("0 * * * * ?")) (1)
                .build();
    }
    1 This Cron expression means "every minute".

As a result, all queued emails will be sent once a minute.

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.useFileStorage=true

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