Usage

Models

The module will register a mailService@cbmailservices in WireBox that you can leverage for usage. The main functions of usage are newMail() to retrieve a new mail payload object and send() to send the payload out.

Simple Example

// build mail and send
var oMail = getInstance( "mailService@cbmailservices" )
    .newMail( to="email@email.com",
              subject="Mail Services Rock",
              bodyTokens={ user="Luis", product="ColdBox", link=event.buildLink( 'home' )} );

// Set a Body
oMail.setBody("
    <p>Dear @user@,</p>
    <p>Thank you for downloading @product@, have a great day!</p>
    <p><a href='@link@'>@link@</a></p> 
");

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

newMail()

You can pass any argument to the newMail() method and it will be treated as a property of the Mail payload object (cbmailservices.models.Mail).

send( required mail )

The send() method will require a mail payload object and return a struct of information to you. This struct will contains the following keys:

{
	error : boolean, // if the mail was sent or not
	errorArray :  array // An array of messages with diagnostic information
}

Body Tokens

The mail services allows you to set replacement markers in the body of your mail payload by using the default @token@ syntax. You can change the token marker in your settings if you like. This will allow you to do dynamic body replacements by just passing a bodyTokens structure to your mail payload object:

// setup a new payload with body tokens
var oMail = getInstance( "mailService@cbmailservices" )
    .newMail( 
    	to 			= "email@email.com",
    	subject 	= "Mail Services Rock",
    	bodyTokens 	= { user="Luis", product="ColdBox", link=event.buildLink( 'home' )} 
    );

// Set a Body with token markers
oMail.setBody("
    <p>Dear @user@,</p>
    <p>Thank you for downloading @product@, have a great day!</p>
    <p><a href='@link@'>@link@</a></p> 
");

More Examples

// Used by the email layout to render this e-mail's view
rc.emailView = 'Reports/email/scheduledReport';

// Create a new mail object
local.Email = mailService.newMail(
     from       = getSetting('sendEmailFrom')
    ,to     = arrayToList(local.emailTo)
    ,subject    = 'Scheduled Report: ' & scheduledReport);

// Set tokens within the mail object. THe tokens will be evaluated
// by the ColdBox Mail Service. Any matching @key@ within the view
// will be replaced with the token's value
local.Email.setBodyTokens({
     timezone   = "#local.timeZoneOfServer.getDisplayName()# (#local.timeZoneOfServer.getID()#)"
    ,reportName     = rc.reportTitle
    ,dateCreated    = now()
    ,reportStatus   = (local.reportEmpty) ? 'Nothing to report.' : 'Report Attached'
    ,username   = rc.schedule_users
    ,frequency  = rc.schedule_frequency
});

// Add plain text email
local.Email.addMailPart(charset='utf-8',type='text/plain',body=local.Renderer.renderLayout("layout.email.plain"));

// Add HTML email
local.Email.addMailPart(charset='utf-8',type='text/html',body=local.Renderer.renderLayout("layout.email.html"));

// Attach a file if a report exists
if (!local.reportEmpty) {
    local.Email.addMailParam(disposition='attachment'
                ,file=getTempDirectory() & rc.generateResult.filepath
                ,type='application/vnd.ms-excel');
}

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