📬
📬
📬
📬
cbMailServices
Search…
Introduction
Intro
Release History
About This Book
Essentials
Installation
Configuration
Sending Mail
Advanced
Async Mail
Building Protocols
Mail Events
Powered By GitBook
Sending Mail
You can initiate a mail payload via the mixin helper (newMail()) or via the injected mail service's newMail() method. The arguments you pass into this method will be used to seed the payload with all the arguments passed to the cfmail tag or the chosen protocol properties. You can also pass an optional mailer argument which will override the default protocol to one of your liking.

Helper

The newMail() helper is useful so you can send mail from your handlers and interceptors.
Please note that the mixin helper can ONLY be used in handlers, interceptors, layouts and views. You will need to use the injection if you want to send mail from your models.
1
// Mixin Helper Approach
2
newMail(
3
to : "[email protected]",
4
from : "[email protected]",
5
subject : "Mail Services Rock",
6
type : "html", // Can be plain, html, or text
7
bodyTokens : {
8
user : "Luis",
9
product : "ColdBox",
10
link : event.buildLink( 'home' )
11
}
12
)
13
.setBody("
14
<p>Dear @[email protected],</p>
15
<p>Thank you for downloading @[email protected], have a great day!</p>
16
<p><a href='@[email protected]'>@[email protected]</a></p>
17
")
18
.send()
19
.onSuccess( function( result, mail ){
20
// Process the success
21
})
22
.onError( function( result, mail ){
23
// Process the error
24
});
Copied!

MailService

Use the WireBox ID of [email protected] to inject the service in any model object to send mail from your models.
1
component{
2
​
3
property name="mailService" inject="[email protected]";
4
​
5
...
6
​
7
function submitOrder( required order ){
8
​
9
...
10
​
11
variables.mailService
12
.newMail(
13
to : "[email protected]",
14
from : "[email protected]",
15
subject : "Mail Services Rock",
16
type : "html",
17
bodyTokens : {
18
user : "Luis",
19
product : "ColdBox",
20
link : event.buildLink( 'home' )
21
}
22
)
23
.setBody("
24
<p>Dear @[email protected],</p>
25
<p>Thank you for downloading @[email protected], have a great day!</p>
26
<p><a href='@[email protected]'>@[email protected]</a></p>
27
")
28
.send()
29
.onSuccess( function( result, mail ){
30
// Process the success
31
})
32
.onError( function( result, mail ){
33
// Process the error
34
});
35
​
36
}
37
​
38
}
Copied!

Mail Payload

The return of the newMail() calls will be a Mail payload object of type cbmailservices.models.Mail. You can find all the full API Docs here:
Mail
cbmailservices.models.Mail
This object will be used to set properties that the mail protocols can use to send mail. We also have several utility methods that can be used to set mail headers, attachments, read receipts, send receipts and so much more. Let's start investigating the Mail Payload Object.

Constructor

The newMail() or configure() method is used to initiate and configure a mail payload. Any argument you pass into these methods will be used to seed the mail config property which is used by all protocols to send email out. Example, the cfmail protocol will read all those properties and pass them as an attribute collection to the cfmail tag.
1
variables.mailService
2
.newMail(
3
to : "[email protected]",
4
from : "[email protected]",
5
subject : "Mail Services Rock",
6
type : "html",
7
bodyTokens : {
8
user : "Luis",
9
product : "ColdBox",
10
link : event.buildLink( 'home' )
11
}
12
)
13
​
14
newMail()
15
.configure(
16
to : "[email protected]",
17
from : "[email protected]",
18
subject : "Mail Services Rock",
19
type : "html",
20
bodyTokens : {
21
user : "Luis",
22
product : "ColdBox",
23
link : event.buildLink( 'home' )
24
}
25
)
Copied!

Send()

You will leverage the send() method to initiate a call to the mail protocols to deliver your mail using your payload. You can then tap into the results of the mailing via the mail callbacks or the mail helper methods. Please also note that the sending operation announces two interceptions points (preMailSend, postMailSend) that you can use to influence the mail payload or listen to mail results.

Callbacks

The mail payload allows you to register two callbacks to determine what happened to the mail payload when sending:
  • onSuccess( callback )
  • onError( callback )
Each callback argument is a function/closure/lambda that receives two arguments:
  • result : The result structure with at least two keys: { error :boolean, messages: array }
  • mail : The mail payload itself.
1
.send()
2
.onSuccess( function( result, mail ){
3
// Process the success
4
})
5
.onError( function( result, mail ){
6
// Process the error
7
});
Copied!

Changing Mailers

You can easily change to use a specific mailer protocol by specifying the mailer argument to the newMail() calls or by calling the setMailer( mailer ) method.
1
newMail( mailer : "files" ),,,
2
​
3
​
4
newMail()
5
.setMailer( "files" )
Copied!

Body Tokens

The mail service allows you to register a structure of tokens that can be replaced by key name on the body content for you. The tokens are demarcated by the tokenMarker setting which defaults to @. Here is the token pattern:
Before sending the mail, the service will replace all the tokens with the specific key names in your content and then send the mail. You can use the bodyTokens argument to the newMail() or configure() methods, or you can use the setBodyTokens() method.
1
// Via constructor
2
newMail(
3
to : "[email protected]",
4
from : "[email protected]",
5
subject : "Mail Services Rock",
6
type : "html",
7
bodyTokens : {
8
user : "Luis",
9
product : "ColdBox",
10
link : event.buildLink( 'home' )
11
}
12
)
13
.setBody("
14
<p>Dear @[email protected],</p>
15
<p>Thank you for downloading @[email protected], have a great day!</p>
16
<p><a href='@[email protected]'>@[email protected]</a></p>
17
")
18
.send()
19
​
20
// Body Tokens Method
21
newMail(
22
to : "[email protected]",
23
subject : "Mail Services Rock",
24
type : "html",
25
)
26
.setBodyTokens( {
27
user : "Luis",
28
product : "ColdBox",
29
link : event.buildLink( 'home' )
30
})
31
.setBody("
32
<p>Dear @[email protected],</p>
33
<p>Thank you for downloading @[email protected], have a great day!</p>
34
<p><a href='@[email protected]'>@[email protected]</a></p>
35
")
36
.send()
Copied!

Rendering Views

You can also set the body of the email to be a view or a layout+view combination using the setView() method. Here is the method signature:
1
/**
2
* Render or a view layout combination as the body for this email. If you use this, the `type`
3
* of the email will be set to `html` as well. You can also bind the view/layout with
4
* the args struct and use them accordingly. You can also use body tokens that the service will
5
* replace for you at runtime.
6
*
7
* @view The view to render as the body
8
* @args The structure of arguments to bind the view/layout with
9
* @module Optional, the module the view is located in
10
* @layout Optional, If passed, we will render the view in this layout
11
* @layoutModule Optional, If passed, the module the layout is in
12
*/
13
Mail function setView(
14
required view,
15
struct args = {},
16
module = "",
17
layout,
18
layoutModule = ""
19
)
Copied!
Please note that you can bind your views and layotus with the args structure as well. You can also use the bodyTokens in your views. Then you can use it in your mail sending goodness:
1
newMail(
2
to : "[email protected]",
3
subject : "Mail Services Rock",
4
type : "html",
5
)
6
.setBodyTokens( {
7
user : "Luis",
8
product : "ColdBox",
9
link : event.buildLink( 'home' )
10
})
11
.setView( view : "emails/newUser" )
12
.send()
13
​
14
newMail(
15
to : "[email protected]",
16
subject : "Mail Services Rock",
17
type : "html",
18
)
19
.setView( view : "emails/newUser", layout : "emails" )
20
.send()
Copied!

Mail Attachments

You can easily add mail attachments using mail params (next section) directly or our fancy helper method called addAttachments().

Signature

Here is our method signature:
1
/**
2
* Add attachment(s) to this payload using a list or array of file locations
3
*
4
* @files A list or array of files to attach to this payload
5
* @remove If true, ColdFusion removes attachment files (if any) after the mail is successfully delivered.
6
*/
7
Mail function addAttachments( required files, boolean remove = false )
Copied!
The files argument can be a list of file locations or an array of file locations to send.

Example

1
newMail(
2
subject = "Hello",
3
from = "[email protected]",
4
to = "[email protected]",
5
body = "Here are your docs"
6
)
7
.addAttachments( "c:\temp\reports\report.pdf", true )
8
.addAttachments( expandpath( "/reports/anotherReport.pdf" ), true )
9
.addAttachments( [
10
expandPath( "/logs/maillog.txt" )
11
expandPath( "/logs/maillog2.txt" )
12
], true )
13
.send();
Copied!

Mail Params

You can easily add mail parameters (cfmailparam) to a payload so you can attach headers or files to the message by using the addMailParam() method. Please see the https://cfdocs.org/cfmailparam cfmail param docs for more information.

Signature

1
/**
2
* Attach a file or adss a header to the email payload
3
*
4
* @contentID The Identifier for the attached file.
5
* @disposition How the attached file is to be handled: attachment, inline
6
* @file Attaches file to a message. Mutually exclusive with name argument.
7
* @type The MIME media type for the attachment.
8
* @name The name of the email header to attach. See https://cfdocs.org/cfmailparam. Mututally exclusive with file
9
* @value The value of the header
10
* @remove Tells ColdFusion to remove any attachments after sucdcesful mail delivery
11
* @content Lets you send the contents of a ColdFusion variable as an attachment
12
*/
13
Mail function addMailParam(
14
contentID,
15
disposition,
16
file,
17
type,
18
name,
19
value,
20
boolean remove,
21
content
22
)
Copied!

Example

1
newMail()
2
.configure(
3
from = "[email protected]",
4
to = "[email protected]",
5
subject = "Mail With Params - Hello Luis"
6
)
7
.setBody( "Hello This is my great unit test" )
8
.addMailParam(
9
name = "Disposition-Notification-To",
10
value = "[email protected]"
11
)
12
.addMailParam( name = "Importance", value = "High" )
13
.send();
Copied!

Mail Parts

You can also add mail parts via the cfmailpart feature of cfmail (https://cfdocs.org/cfmailpart). This allows you to build multi-parted emails.

Signature

1
/**
2
* Add a new mail part to this mail payload
3
*
4
* @charset The charset of the part, defaults to utf-8
5
* @type The valid mime type: text/plain or text/html
6
* @wraptext Specifies the maximum line length, in characters of the mail text.
7
* @type The MIME media type for the attachment.
8
* @body The body of the email according to the type.
9
*/
10
Mail function addMailPart(
11
charset = "utf-8",
12
type,
13
numeric wraptext,
14
body
15
){
Copied!

Example

1
newMail(
2
from = "[email protected]",
3
to = "[email protected]",
4
subject = "Mail MultiPart No Params - Hello Luis"
5
)
6
.addMailPart(
7
type = "text",
8
body = "You are reading this message as plain text, because your mail reader does not handle it."
9
)
10
.addMailPart( type = "html", body = "<h1>This is the body of the message.</h1>" )
11
.send()
Copied!

Mail Helper Methods

We have also registered several methods to help you when sending mail:
  • setReadReceipt( email ) - Set the read receipt email
  • setSendReceipt( email ) - Set the send receipt email
  • setHtml( body ) - Set a multi-part body for html
  • setText( body ) - Set a multi-part body for text
  • addAttachments( files, remove=false) - Easily add attachments
  • getMemento() - Get the entire mail settings for the payload
  • hasErrors():boolean - Verifies if there are any errors in the mailing
  • getResultMessages():array - Get's the array of messages of the sending of the mail
  • getResults():struct - Get the structure of the results of sending the mail

Mail Additional Info

The Mail object has some additional methods to allow you to pass additional information so protocols can leverage them:
1
mail.setAdditionalInfo( struct );
2
mail.getAdditionalInfo();
3
​
4
mail.seavatAdditionalInfoItem( key, value );
5
mail.getAdditionalInfoItem( key );
Copied!
Essentials - Previous
Configuration
Next - Advanced
Async Mail
Last modified 6mo ago
Export as PDF
Copy link
Edit on GitHub
Contents
Helper
MailService
Mail Payload
Constructor
Send()
Callbacks
Changing Mailers
Body Tokens
Rendering Views
Mail Attachments
Signature
Example
Mail Params
Signature
Example
Mail Parts
Signature
Example
Mail Helper Methods
Mail Additional Info