What's New With 2.0.0

📬
cbMailServices
Search…
Introduction
Intro
Release History
What's New With 2.0.0
Essentials
Advanced
What's New With 2.0.0
November 2021
cbMailServices has been rewritten from the ground up for the 2.x release. It was about time to add some 💕 and modernize it. Please note that this is a major upgrade and it WILL require some changes on your configuration and usage. We have documented all the changes for you to provide for a smooth transition.
Compatibility Changes
The following are the changes you will need to do to upgrade to version 2.x.
Adobe 2016 Support Dropped
It’s too old and too cumbersome to support now. So upgrade to a supported engine.
MailSettingsBean Dropped
This CFC was unnecessary and dropped in favor of encapsulation in the MailService
Configuration Changes
You will have to place the configuration in the standard ColdBox approach now of moduleSettings.cbmailservices in the config/coldbox.cfc configuration file instead of the top level mailServices struct.
1
moduleSettings = {
2
	cbMailservices : {
3
​
4
	}
5
};
Copied!
No More Top Level Mail Settings
In the previous version you would put any payload mail default settings as a top-level key under the mailServices struct. Now you will use the defaults struct instead.
1
cbmailservices : { 
2
  tokenMarker : "@",
3
  defaults : {
4
    from : "[email protected]",
5
    cc : "[email protected]",
6
    server : "myserver"
7
  }
8
}
Copied!
Default Protocol
In 2.x you can define multiple mailers in an application. So the previous protocol struct is now removed. You will have to register the protocol by name in the mailers struct and add a defaultProtocol key which points to the one you define in the mailers.
1
cbmailservices : {
2
  defaultProtocol : "cfmail",
3
  mailers : {
4
    "files" : { class : "File" },
5
    "cfmail" : { class : "CFMail" }
6
  }
7
}
Copied!
If no defaultProtocol is added and no mailers then the mail services module will register a cfmail protocol for you as the default mailer.
Mail bean returned from send() method
Previous a struct containing error and errorArray would be returned from the send() method.  Now, the Mail bean is returned (whether using mail.send() or mailService.send( mail )). The previously available struct can be accessed using mail.getResults(). (Be sure to see the changes to the errorArray name below.)
No More errorArray
The return struct from the mail services has been modified. The errorArray has been renamed to messages. Which is still an array but can be used by any protocol to register an array of messages about the mailing for any status.
Mail config() renamed to configure()
The mail payload config() method was renamed to configure()
1
mailService
2
	.newMail()
3
	.configure(
4
		from    = "[email protected]",
5
		to      = "[email protected]",
6
		subject = "Mail With Params - Hello Luis"
7
	)
Copied!
Postmark message_id renamed to messageId
The return message identifier from postmark has been renamed from message_id to messageID to be consistent with the postmark API results.
​
New Features and Improvements
Let’s investigate now the new features and improvements.
newMail() Helper
The module now registers several new mixin helpers. You can now use newMail() in any handler, and interceptor to start a fluent mailing.
1
function save( event, rc, prc ){
2
	...
3
​
4
	newMail( to: "[email protected]", subject : "Hello" )
5
		.setBody( "hello body" )
6
		.send();
7
}
Copied!
Mailer Aliases
You can now register your mailer protocols by using their alias instead of the full CFC path:
CFMail
File
InMemory
Null
Postmark
1
moduleSettings = {
2
	cbMailservices : {
3
		defaultProtocol : "default",
4
		mailers : {
5
			"default" : { class : "CFmail" },
6
			"memory" : { class : "InMemory" }
7
		}
8
	}
9
}
Copied!
Mailer WireBox ID
You can now also register ANY WireBox ID or class path as the mailer as well. This will allow you to register mailers that come from your application or any other module.
1
moduleSettings = {
2
	cbMailservices : {
3
		defaultProtocol : "default",
4
		mailers : {
5
			"default" : { class : "CFmail" },
6
			"amazon" : { class : "[email protected]" }
7
		}
8
	}
9
}
Copied!
Protocol Names
All protocols now have a name property that can be used to give a human readable name for all protocols.
1
/**
2
 * Initialize the InMemory protocol
3
 *
4
 * @properties A map of configuration properties for the protocol
5
 */
6
InMemoryProtocol function init( struct properties = {} ){
7
​
8
	variables.name = "InMemory";
9
​
10
	super.init( argumentCollection = arguments );
11
	variables.mail = [];
12
	return this;
13
}
Copied!
Fluent Mail
The mail payload object has been completely rewritten to allow you to use it to not only construct a mail payload, but to do it in a fluent and more approachable manner. It also allows you to send the payload itself without using the mail service. It also sports a dynamic getter/setter approach for any property stored in the internal config structure. This structure is used to model all the mail settings and properties that will be used to send mail through any protocol.
1
mailService
2
	.newMail()
3
	.configure(
4
		from    = "[email protected]",
5
		to      = "[email protected]",
6
		subject = "Mail With Params - Hello Luis"
7
	)
8
	.setBody( "Hello This is my great unit test" )
9
	.addMailParam(
10
		name  = "Disposition-Notification-To",
11
		value = "[email protected]"
12
	)
13
	.addMailParam( name = "Importance", value = "High" )
14
	.send()
15
  .onSuccess ( () => {
16
​
17
  } )
18
  .onError( () = > {
19
  } );
Copied!
Success - Errors Callback
The send() method will return itself so you can interact with the payload for either success or failures. You will do so using the following methods:
OnError( callback )
OnSuccess ( callback )
1
newMail( to: "[email protected]" )
2
.setSubject( "This is my email confirmation" )
3
.setBody( "You got in buddy!" )
4
.send()
5
  .onSuccess ( () => {
6
​
7
  } )
8
  .onError( () = > {
9
  } );
Copied!
Utility Methods
The following utility methods can be used for inspecting results and errors.
getResults() : struct. Empty if no results
hasErrors() : boolean. False if no results
getResultMessages() : array. Empty if no results
Multiple Transmission Mailer Protocols
The configuration allows for a mailers structure where you can register extra named mailer protocols. You can then use them by name in your mail payloads and set the defaultProtocol as well by it's name.
1
cbMailservices : {
2
	// Default Token marker
3
	tokenMarker : "@",
4
​
5
	// Default protocol
6
	defaultProtocol : "file",
7
​
8
	// Mailers
9
	mailers : {
10
		file : { class: "", properties : {} },
11
		postmark : { class: "", properties : {} },
12
		amazon : { class: "", properties : {} }
13
	},
14
​
15
  ...
16
​
17
}
Copied!
You can also seed the mailer name in the payload using the setMailer() method to register the name of the mailer to use for the payload or use the mailer configuration key.
1
// Using constructor
2
newMail( mailer : "amazon" )
3
​
4
// Using setter
5
newMail()
6
	.setMailer( "amazon" )
Copied!
View Rendering
Allow for the payload to render a view as the body for you instead of doing this manually using the setView() method.
1
newMail()
2
.setView(
3
	view   : "View",
4
	module : "view module",
5
	layout : "layout",
6
	layoutModule : "layout module",
7
	args   : {}
8
)
Copied!
This will tell the mail payload to render the view with or without the layout, pass in the args into the view and layout as the body of the mailing. If you don't pass a layout by convention we will just render the view in isolation.
Async Sending
Thanks to ColdBox futures you can now send the mailing asynchronously via the sendAsync() method. The return is a ColdBox Future object.
1
future = newMail()
2
 .setView( "report" )
3
 .sendAsync()
Copied!
In Memory Mail Queue
The mail services module will also register a mail scheduler that will iterate and send mail payload asynchronously. The scheduler runs every minute and iterates and sends all mail in the queue. This allows for your application to not wait and block until mail is sent.
All you need to do is use the queue() method. That’s it. The mail services schedule will deliver the mail payload to the right mailer asynchronously and at least every minute schedule.
1
var taskId = newMail()
2
 ...
3
 .queue();
Copied!
Please note that we are in async land, so you won’t be able to process successes or failures. The scheduler will log all activity to the applications logging facilities for either a success or failed mailing. The return of the queue() method is a task ID guid which you can use to track in log statements.
Last modified 12d ago
Compatibility Changes

Adobe 2016 Support Dropped

MailSettingsBean Dropped

Configuration Changes

No More Top Level Mail Settings

Default Protocol

Mail bean returned from send() method

No More `errorArray`

Mail config() renamed to configure()

Postmark `message_id` renamed to `messageId`

New Features and Improvements

newMail() Helper

Mailer Aliases

Mailer WireBox ID

Protocol Names

Fluent Mail

Success - Errors Callback

Utility Methods

Multiple Transmission Mailer Protocols

View Rendering

Async Sending

In Memory Mail Queue
