Eric Peterson

December 14, 2017

Spread the word

Share your thoughts

ForgeBox is your first stop for when you need some new functionality for your application, be that a utility library, an SDK, a framework, or something else. Today we'll take a look at one of the tools for helping manage sending emails — [cbmailservices](


cbmailservices provides a protocol-based service to send emails as well as mail merge functionality to easily customize emails.

But what about good 'ole cfmail? Well, you can still use it! cbmailservices ships with a CFMailProtocol which will delegate back to cfmail for sending your emails.

You might wonder why you would even use this module? Let me give you two reasons:

Mail Merge

Mail merging lets you specify an email template with tokens that can be replaced per email. This lets you tailor your emails to each user, company, or use case you find.

Here's an example of the mail merging capabilitys of cbmailservices:

var mailService = getInstance( "mailService@cbmailservices" );
var mail = mailService.newMail(
    to = "",
    subject = "Mail Services Rock",
    bodyTokens = {
        user = "John",
        product = "cbmailservices",
        link = event.buildLink( "view.cbmailservices" )
    body = "

Dear @user@,

Thank you for downloading @product@. Have a great day!


" ); mailService.send( mail );

This will send the following email:

<p>Dear John,</p>
<p>Thank you for downloading cbmailservices.  Have a great day!</p>
<p><a href=""></a></p>


A cbmailservices protocol defines how to send an email. This can be through good 'ole cfmail, third party mail services like Postmark and SendGrid, or even just locally to your file system or the console output.

Even better, with ColdBox's environment detection, you can set different protocols for each environment. Here's what a sample config/ColdBox.cfc file might look like:

function configure() {
    mailsettings = {
        tokenMarker = "@",
        protocol = {
            class = "cbmailservices.models.protocols.PostmarkProtocol",
            properties = {
                APIKey = getSystemSetting( "POSTMARK_API_KEY" )

function development() {
    mailsettings.protocol = {
        class = "cbmailservices.models.protocols.FileProtocol",
        properties = {
            filePath = "logs",
            autoExpand = true

This configuration will log emails locally to the file system in development and use Postmark to send emails for real in production. Nice!

You can write your own protocols as well and even publish them on ForgeBox like the SendGrid protocol for your favorite email service.

Wrap Up

So head on over to your local CommandBox terminal and give cbmailservices a go!

Add Your Comment

Recent Entries

CBWIRE 2.2 Released

CBWIRE 2.2 Released

We're excited to announce the release of CBWIRE 2.2. This release includes several added enhancements, such as new lifecycle hooks and simplified Turbo Drive integration. We changed the previous lifecycle hook of mount() to onMount() to be consistent, and several bugs were squashed.

Maria Jose Herrera
Maria Jose Herrera
January 09, 2023
FORGEBOX v7.1.0 Released

FORGEBOX v7.1.0 Released

We are so happy to announce a minor release for our package management system. In this release, we take care of some bug fixes reported and a lot of work for our elastic search engine. Now better search results with an improved response time. We have updated our core modules to the latest versions for better security and performance.

Javier Quintero
Javier Quintero
December 30, 2022
Favorite 2022 Ortus Content

Favorite 2022 Ortus Content

2022 was quite the year. For us, it was all about delivering exceptional content and service to our amazing community of developers. That's why we updated our tools, released new products, and announce upcoming projects and initiatives we are working on for 2023.

We know 2023 will be awesome but 2022 was amazing too. Read on and don't miss anything, review the top content we released in 2022 and improve your projects in 2023. Happy New Year!

Maria Jose Herrera
Maria Jose Herrera
December 29, 2022