Using the ColdBox MailService Plugin

Need to send out emails in your ColdBox application? Then the ColdBox MailService plugin is your friend. Here are the steps:

  1. Inject the mail service
  2. Create the email method
  3. Create the html email view
  4. Using the email method

Inject the Mail Service

Before you can use the mail service, we need to inject it into the handler component where we will define the mail method like so:

component accessors="true" {
  property name="mailService" inject="coldbox:plugin:MailService";
  property name="renderer" inject="coldbox:plugin:Renderer";
  property name="configBean" inject="coldbox:configBean";
  property name="userService"  inject="model:userService@solitary";
} //component


  • We first inject the MailService plugin
  • Then the Renderer plugin so we can render the email message
  • Finally we inject the configBean to bring in any configurations from the ConfigurationCFC (coldbox.cfc)

Create the email method

In the same handler component, create an email method, e.g. notifyUser. Here’s an example to illustrate:

private void function notifyUser(required user) {
  var baseURL = len(configBean.getKey('sesBaseURL')) ? configBean.getKey('sesBaseURL') : configBean.getKey('htmlBaseURL');
  var emailTitle = "New Records Available";
  rc.emailView = 'notifications/newEntry';

  // Create a new mail object = MailService.newMail().config(
    subject= emailTitle

  /* define the token for use in the email view. 
     this is the dynamic content for the html email body */{
    title = emailTitle,
    firstName = arguments.user.getFirstName(),
    url = baseURL & "/reports/list"

  // Add HTML email'utf-8',type='text/html',body=renderer.renderView(view=rc.emailView));

  // Send the email. MailResult is a boolean.
  local.mailResult = mailService.send(local.Email);
} //notifyUser


  • We use the injected configBean to retrieve settings from the ConfigurationCFC (coldbox.cfc) and set the base URL
  • Then we create a new mail message using MailService’s newMail method
  • Then we define the token for the body and add the html email. The content of the html email is defined in the views folder. In the above example, a view template called newEntry.cfm should be created and saved under the views/notifications sub-folder
  • Finally we send it using the MailService plugin’s send method.

Create the email view

Under the views folder, create a subfolder called notifications. Then in this new subfolder create a new file called newEntry.cfm and add the following code snippet:

  <p>Dear @FIRSTNAME@,</p>
  <p>New records are now available. Please <a href="@URL@">logon</a> to action them.</p>
  <p>System Admin</p>


  • Any @key@ will be replace by the values defined in the MailService’s new email setBodyTokens method in the notifyUser method.
  • So in this instance @TITLE@ will be replaced with the value: New Records Available

Using the email method

Here’s the scenario. In your application you have a method which uploads a file and emailing all application users to notify them of new records. Here the notifyUser method is called and used.

And an example code snippet to illustrate.

public void function upload(event){
  uploadResult = getPlugin("FileUtils").uploadFile(fileField="csvFile",destination=expandPath('files'),nameConflict="Overwrite");
  if (!StructIsEmpty(uploadResult) ){
    users = userService.findAllWhere(criteria={isActive=true});
    if (!ArrayIsEmpty(users)){
      for (var i=1; i<=ArrayLen(users); i++){
    } //if !ArrayIsEmpty()
} //upload


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s