Asynchronous Mail Plugin

  • Tags: asynchronous, mail
  • Latest: 1.1
  • Last Updated: 10 September 2014
  • Grails version: 2.3.1 > *
11 votes

3% of Grails users

Dependency:
compile ":asynchronous-mail:1.1"

 Documentation  Source  Issues

Summary

The plugin realises asynchronous mail sending. It stores messages in the DB and sends them asynchronously by the quartz job.

Description

Attention! The plugin was migrated to the quartz plugin. If you need the quartz2 plugin please use version 0.9.

The Grails Asynchronous Mail is a plugin for asynchronous sending email messages. It stores email messages in the DB using Grails domain classes and sends them by scheduled job. It allows to react to user's actions faster. If the SMTP server isn't available in time then the plugin can sends message after, when the server will be available.

The plugin depends on quartz and mail plugins. You also need a persistence provider plugin. hibernate, hibernate4 and mongodb are supported. MongoDB is supported since the version 1.1-RC.

Configuration

Create AsynchronousMailConfig.groovy in grails-app/config directory. There is a script which creates your configuration file based on the default configuration.
grails install-asynchronous-mail-config
Or you can use the default configuration. It disposes in plugin-dir/grails-app/conf/DefaultAsynchronousMailConfig.groovy .
asynchronous.mail.default.attempt.interval=300000l       // Five minutes
asynchronous.mail.default.max.attempts.count=1
asynchronous.mail.send.repeat.interval=60000l           // One minute
asynchronous.mail.expired.collector.repeat.interval=607000l
asynchronous.mail.messages.at.once=100
asynchronous.mail.send.immediately=true  // since 0.1.2
asynchronous.mail.override=false    // since 0.2.0
asynchronous.mail.clear.after.sent=false    // since 0.2.0
asynchronous.mail.disable=fasle    // since 0.7
asynchronous.mail.useFlushOnSave=true
asynchronous.mail.persistence.provider='hibernate' // Possible values are 'hibernate', 'hibernate4', 'mongodb'
asynchronous.mail.gparsPoolSize=1
asynchronous.mail.newSessionOnImmediateSend=false

Configuration options

OptionDescription
asynchronous.mail.default.attempt.intervalThe default repeat interval in milliseconds between attempts to send an email.
asynchronous.mail.default.max.attempts.countThe default max attempts count per message.
asynchronous.mail.send.repeat.intervalThe repeat interval in milliseconds between starts of the SendJob which sends email messages.
asynchronous.mail.expired.collector.repeat.intervalThe repeat interval in milliseconds between starts of the ExpiredCollectorJob which marks messages as EXPIRED if time for sent is expired.
asynchronous.mail.messages.at.onceThe max count of messages which can be sent per time.
asynchronous.mail.send.immediatelyIf true (default) then the SendJob is started immediately after a message was created. Since version 0.1.2.
asynchronous.mail.overrideIf true then overrides method sendMail of MailService in Grails mail plugin. Default is false. Since version 0.2.0
asynchronous.mail.clear.after.sentIf true then all messages will be deleted after sent. Default is false. Since version 0.2.0
asynchronous.mail.disableIf true then jobs don't start.
asynchronous.mail.useFlushOnSaveBy default the plugin flushes all changes to DB on every step of the sending process for prevent resending but it makes overhead. So you can set this property to false and will have better performance but will not have guarantee prevention of resending.
asynchronous.mail.persistence.providerThe persistence provider. Possible values are hibernate , hibernate4 , mongodb .
asynchronous.mail.gparsPoolSizeThe size of the thread pool for sending messages.
asynchronous.mail.newSessionOnImmediateSendIt's difficult.

Configure the mail plugin. The Asynchronous Mail plugin uses the mail plugin for sending messages to the SMTP server.

Usage

If you usen the mail plugin already, you must import and inject asynchronousMailService or his alias asyncMailService into your class:
import grails.plugin.asyncmail.AsynchronousMailService

AsynchronousMailService asynchronousMailService
or
AsynchronousMailService asyncMailService

The AsynchronousMailService is a Grails service.

And change your sendMail call to

asyncMailService.sendMail {
    // Mail parameters
    to 'john.smith@example.com'
    subject 'Test';
    html '<body><u>Test</u></body>';
    attachBytes 'test.txt', 'text/plain', byteBuffer;
    // Additional asynchronous parameters (optional)
    beginDate new Date(System.currentTimeMillis()+60000)    // Starts after one minute, default current date
    endDate new Date(System.currentTimeMillis()+3600000)   // Must be sent in one hour, default infinity
    maxAttemptsCount 3;   // Max 3 attempts to send, default 1
    attemptInterval 300000;    // Minimum five minutes between attempts, default 300000 ms
    delete true;    // Marks the message for deleting after sent
    immediate true;    // Run the send job after the message was created
    priority 10;   // If priority is greater then message will be sent faster
}
See the sample application.

Override the Mail plugin

You can override the MailService and the sendMail dynamic method for use the Grails Asynchronous Mail plugin with others plugins for example. Just add to the configuration file:
asynchronous.mail.override=true
The Grails Asynchronous Mail plugin supports all features of the Grails Mail plugin.

The AsynchronousMailController and views

You can create the controller and views for view and edit email messages in the DB.
create-asynchronous-mail-controller --package=com.example

Logging

You can want to enable logging for the plugin. It's easy.
log4j = {
    …
    // Enable the Asynchronous Mail plugin logging
    trace 'grails.app.jobs.grails.plugin.asyncmail', 
          'grails.app.services.grails.plugin.asyncmail',
          'grails.plugin.asyncmail'
    // Enable the Quartz plugin logging
    debug 'grails.plugins.quartz'
    …
}

Indexes

I recommend to create an index on async_mail_mess.status column. It's result of my heuristic observations. Only DBA must create indexes anyway.

Support

You can report about bugs on the JIRA or GitHub. You also can ask me by email kefirfromperm@gmail.com. Before you send a bugreport please enable logs and attach it to your issue.

Please, review this project on Ohloh.