Email Module

Description

The Email module allows possibility to send e-mails. Messages are sent via org.springframework.mail.javamail.JavaMailSender. There are three ways to send email:

  • Using OSGI Service
  • Sending via GUI
  • By publishing an event(the event is exposed as an action in tasks)

Configuration

Property Display name Description Value
mail.host Host SMTP server URL(for example smtp.domain.com) valid url
mail.port Port SMTP server Port port value
mail.log.address Log User Email Address If true then logs will be saved with the address of the recipient and the sender true, false
mail.log.subject Log Message Subjects If true then logs will be saved with the message subject true, false
mail.log.body Log Message Body If true then logs will be saved with the message body true, false
mail.log.purgeenable Purge any record older than If true then mails logs older than value specified by the mail.log.purgetime and mail.log.purgetimemultiplier params, will be removed. This option works only when the Scheduler module is installed and running true, false
mail.log.purgetime - Number of time units used by mail.log.purgeenable param purgetime value
mail.log.purgetimemultiplier - Unit of time used by mail.log.purgeenable param Hours, Days, Weeks, Months, Years

Default Email module configuration:

mail.host=localhost
mail.port=8099
mail.log.address=true
mail.log.subject=true
mail.log.body=true
mail.log.purgeenable=false
mail.log.purgetime=0
mail.log.purgetimemultiplier=days

Attention

Using the module requires a configured and working mail server, for example Postfix.

OSGI Service API

The Email module exposes two OSGi services. First service provides possibility to send mail using the following API:

public interface EmailSenderService {

    /**
     * Attempts to send the supplied email message. Adds an {@link org.motechproject.email.domain.EmailRecord}
     * entry to the log with the details of the activity.
     *
     * @param message  the message to send
     */
    void send(Mail message);
}

Email message is represented by an object of org.motechproject.email.domain.Mail class which contains following fields:

  • String fromAddress - sender address.
  • String toAddress - recipient address.
  • String subject - mail subject.
  • String message - messages which is treated as html.

Second service provides API for browsing logged email activity and deleting unwanted logs.

public interface EmailAuditService {

    // finds an email in the log by ID
    EmailRecord findById(long id);

    // finds all emails available in the log
    List<EmailRecord> findAllEmailRecords();

    // finds emails matching the specified search criteria
    List<EmailRecord> findEmailRecords(EmailRecordSearchCriteria criteria);

    // returns the count of emails matching the specified search criteria
    long countEmailRecords(EmailRecordSearchCriteria criteria);

    // deletes the specified email from the log
    void delete(EmailRecord emailRecord);
}

Email module UI

Email module user interface delivers three tabs:

  • Send Email - gives you the ability to send e-mail messages.

  • Email Logs - allows you to view and filter email logs, you can also export them to a csv file.

  • Settings - allows you to change the current configuration of the module.

    Send email screen

User roles

Access to the module via GUI is granted to users with one of the following roles:

  • Email Junior Admin - user can send mails, change module settings and view basic email logs(user can only see message status and delivery time).
  • Email Admin - user can send mails, change module settings and view detailed email logs.

Consumed Event

To send e-mail from other module there is no need to have dependency on the Email module, because it handle events(org.motechproject.event.MotechEvent). Messages are created on the basis of handles events. Valid event must have subject SendEMail (constant SEND_EMAIL_SUBJECT) and following parameters(The constants are in class org.motechproject.email.constants.SendEmailConstants):

Parameter Description Value Constant names
fromAddress Sender address valid email address FROM_ADDRESS
toAddress Recipient address valid email address TO_ADDRESS
subject Mail subject any SUBJECT
message Messages any MESSAGE

The Email module registers an event handler to allow other modules to request sending emails. This event is exposed to the Task module as a task action, so you can send mails using the Task module.