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-address
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, the 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
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 Email Sending add-on provides the default configuration of the Quartz job that processes the email sending queue. To use it, do the following:
-
Include Quartz add-on in your project as described in the Quartz / Installation section.
-
Change the 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 job configuration, do the following:
-
Include Quartz add-on in your project as described in the Quartz / Installation section.
-
Set the jmix.email.use-default-quartz-configuration application property to false:
jmix.email.use-default-quartz-configuration = false
-
Create a job class:
public class MyCustomEmailSendingJob implements Job { @Autowired private Emailer emailer; @Override public void execute(JobExecutionContext context) throws JobExecutionException { emailer.processQueuedEmails(); } }
-
In the running application, open the Quartz → Quartz jobs view, and configure a job for the
MyCustomEmailSendingJob
class. -
Alternatively, if you want to configure the email sending job at development time, 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 that is switched off by default. You can use it for periodic cleaning of saved emails as described below.
If you need to keep some emails longer, 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
To use the default configuration of the Quartz job for regular cleaning of emails, do the following:
-
Include Quartz add-on in your project as described in the Quartz / Installation section.
-
Set the jmix.email.use-default-email-cleaning-quartz-configuration property to
true
:jmix.email.use-default-email-cleaning-quartz-configuration=true
-
Change the CRON expression if necessary using the jmix.email.email-cleaning-cron property.
jmix.email.email-cleaning-cron=0 0 0 1/2 * ?
-
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
-
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 job configuration, do the following:
-
Include Quartz add-on in your project as described in the Quartz / Installation section.
-
Create a job class:
public class MyCustomEmailCleaningJob implements Job { @Autowired private EmailCleaner emailCleaner; @Override public void execute(JobExecutionContext context) throws JobExecutionException { emailCleaner.deleteOldEmails(); } }
-
In the running application, open the Quartz → Quartz jobs screen, and configure a job for the
MyCustomEmailCleaningJob
class. -
Alternatively, if you want to configure the email cleaning job at development time, 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(); }
-
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
-
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:
-
Add the following line to the
dependencies
section of yourbuild.gradle
file:implementation 'io.jmix.localfs:jmix-localfs-starter'
-
Enable file storage usage. Set in the
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
.