FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

ColdBox Mail Services

v1.6.0+49 Public

Build Status


The ColdBox Mail services module will allow you to send email the OO way in multiple protocols for many environments. The supported protocols are:

  • CFMail - Traditional cfmail sending
  • Null - Ignores emails sent to it.
  • InMemory - Store email mementos in an array. Perfect for testing.
  • Files - Write emails to disk
  • Postmark API - Send via the PostMark Service (

You can easily add your own mail protocols by building upon our standards.


Apache License, Version 2.0.


  • Lucee 5+
  • ColdFusion 2016+


Just drop into your modules folder or use the box-cli to install

box install cbmailservices

The mail services registers all mail components so you can use them in your application.


You will need to update the your ColdBox.cfc with a mailsettings structure with your preferred mail settings and mail protocol to use. All the keys that can go into the mailsettings struct map 1-1 to the cfmail tag except for the tokenMarker and protocol keys. See below for more information on other protocols you can use.

mailsettings = {
    // The default token Marker Symbol
    tokenMarker = "@",
    // protocol
    protocol = {
        class = "cbmailservices.models.protocols.CFMailProtocol",
        properties = {}


This will register a [email protected] in WireBox that you can leverage for usage.

// build one-off mail
var mailService = getInstance( "[email protected]" );
var oMail = mailService.newMail( 
	to="[email protected]",
	from="[email protected]",
	subject="Mail Services Rock",
		link=event.buildLink( 'home' )

// add a Body
    <p>Dear @[email protected],</p>
    <p>Thank you for downloading @[email protected], have a great day!</p>
    <p><a href='@[email protected]'>@[email protected]</a></p> 

// send it
var results = mailService.send( oMail );

You can also inject mailService into your components as you would with other modules to avoid the getInstance() call.

property name="mailService" inject="[email protected]";

Mail Additional Info

The Mail object has some additional methods to allow you to pass additional information so protocols can leverage them:

setAdditionalInfo( struct );

setAdditionalInfoItem( key, value );
getAdditionalInfoItem( key );

Mail Protocols

The mail services can send mail via different protocols. The available protocols are:

  • CFMailProtocol
  • NullProtocol
  • InMemoryProtocol
  • FileProtocol
  • PostmarkProtocol

You register the protocols in the mailsettings via the protocol structure:

// FileProtocol
protocol = {
    class = "cbmailservices.models.protocols.FileProtocol",
    properties = {
        filePath = "logs",
        autoExpand = true

// NullProtocol
protocol = {
    class = "cbmailservices.models.protocols.NullProtocol",
    properties = {}

// InMemoryProtocol
protocol = {
    class = "cbmailservices.models.protocols.InMemoryProtocol",
    properties = {}

// PostMark
protocol = {
    class = "cbmailservices.models.protocols.PostmarkProtocol",
    properties = {
        APIKey = ""

Custom Protocols

In order to create your own custom protocol you will create a CFC that inherits from cbmailservices.models.AbstractProtocol and make sure you implement the init() and send() method.

Interception Points

The module will register two interception points. PreMailSend and PostMailSend. These interception points are useful to alter the mail object before it gets sent out, and/or perform any functions after the mail gets sent out. An example interceptor would be:

component extends="coldbox.system.Interceptor"{
    void function configure(){

    boolean function preMailSend( event, interceptData, buffer, rc, prc ){
        var environment = getSetting('environment');
        var appName = getSetting('appName');
        var mail = interceptData.mail;
        var subject = mail.getSubject()

        if(environment eq 'development'){
            //change recipient if we are on development
            mail.setTo('[email protected]');  
            //prefix the subject if we are on development
            mail.setSubject('<DEV-#appName#> #subject#');

        return false;

    boolean function postMailSend( event, interceptData, buffer, rc, prc ){
        if(interceptData.result.error eq true){
            //log mail failure here...

        return false;


Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp


Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5


"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

Dependencies (0)

Dev Dependencies (0)


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[v1.6.0] => 2021-FEB-22


  • Two new protocols: NullProtocol, InMemoryProtocol
    • The NullProtocol ignores all calls to it.
    • The InMemoryProtocol stores mail mementos in an internal array. This can be useful for testing to check that mail was sent. It also includes a handle hasMessage method which takes a predicate callback and checks it against each sent mail. A reset method is included for use inside tests.
  • New CI updates and code quality systems
  • New updates for ColdBox 6

[v1.5.0] => 2019-NOV-12

New Features

  • Added a fromName to the Mail bean to track names due to some protocols allowing it
  • The module will register two interception points. PreMailSend and PostMailSend


  • New module layout
  • Removed unecessary routing endpoint


  • Var scoping issue


  • Fixes incorrect argument collection nesting on protocol registration


  • Auto create folder paths in FileProtocol if they do not exist


  • Updated to use module templating
  • Proposed additionalInfo data struct for provider specific implementations. Added a couple of helper methods :
  • Updated to leverage WireBox for object creations instead of internal new and createobjects


  • Fix on date formatting on file protocol thanks to @elpete
  • Fix for type inclusion on the file protocol thanks to @elpete


  • Travis integration
  • DocBox updates
  • Build process updates


  • Updated build process
  • Updated readme and instructions


  • Create first module version


$ box install cbmailservices

No collaborators yet.
  • {{ getFullDate("Feb 22 2021 05:02 PM GMT") }}
  • {{ getFullDate("Feb 22 2021 05:02 PM GMT") }}
  • 5,641
  • 4,451
  • 43,425