📧Sending Mail
Up up and away!
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 that will override the default
protocol to one of your likings.
Helper
The newMail()
helper is useful so you can send mail from your handlers and interceptors.
// Mixin Helper Approach
newMail(
to : "[email protected]",
from : "[email protected]",
subject : "Mail Services Rock",
type : "html", // Can be plain, html, or text
bodyTokens : {
user : "Luis",
product : "ColdBox",
link : event.buildLink( 'home' )
}
)
.setBody("
<p>Dear @user@,</p>
<p>Thank you for downloading @product@, have a great day!</p>
<p><a href='@link@'>@link@</a></p>
")
.send()
.onSuccess( function( result, mail ){
// Process the success
})
.onError( function( result, mail ){
// Process the error
});
Delegate
If you are using ColdBox 7 you can use the Mailable@cbMailservices
delegate to add mailing capabilities to ANY model managed by WireBox. It will add the newMail()
method to your objects:
component name="UserService" delegates="Mailable@cbMailservices"{
...
newMail()
.send();
}
MailService
Use the WireBox ID of MailService@cbmailservices
to inject the service in any model object to send mail from your models.
component{
property name="mailService" inject="MailService@cbmailservices";
...
function submitOrder( required order ){
...
variables.mailService
.newMail(
to : "[email protected]",
from : "[email protected]",
subject : "Mail Services Rock",
type : "html",
bodyTokens : {
user : "Luis",
product : "ColdBox",
link : event.buildLink( 'home' )
}
)
.setBody("
<p>Dear @user@,</p>
<p>Thank you for downloading @product@, have a great day!</p>
<p><a href='@link@'>@link@</a></p>
")
.send()
.onSuccess( function( result, mail ){
// Process the success
})
.onError( function( result, mail ){
// Process the error
});
}
}
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:
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.
variables.mailService
.newMail(
to : "[email protected]",
from : "[email protected]",
subject : "Mail Services Rock",
type : "html",
bodyTokens : {
user : "Luis",
product : "ColdBox",
link : event.buildLink( 'home' )
}
)
newMail()
.configure(
to : "[email protected]",
from : "[email protected]",
subject : "Mail Services Rock",
type : "html",
bodyTokens : {
user : "Luis",
product : "ColdBox",
link : event.buildLink( 'home' )
}
)
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.
.send()
.onSuccess( function( result, mail ){
// Process the success
})
.onError( function( result, mail ){
// Process the error
});
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.
newMail( mailer : "files" ),,,
newMail()
.setMailer( "files" )
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:
@tokenName@
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.
// Via constructor
newMail(
to : "[email protected]",
from : "[email protected]",
subject : "Mail Services Rock",
type : "html",
bodyTokens : {
user : "Luis",
product : "ColdBox",
link : event.buildLink( 'home' )
}
)
.setBody("
<p>Dear @user@,</p>
<p>Thank you for downloading @product@, have a great day!</p>
<p><a href='@link@'>@link@</a></p>
")
.send()
// Body Tokens Method
newMail(
to : "[email protected]",
subject : "Mail Services Rock",
type : "html",
)
.setBodyTokens( {
user : "Luis",
product : "ColdBox",
link : event.buildLink( 'home' )
})
.setBody("
<p>Dear @user@,</p>
<p>Thank you for downloading @product@, have a great day!</p>
<p><a href='@link@'>@link@</a></p>
")
.send()
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:
/**
* Render or a view layout combination as the body for this email. If you use this, the `type`
* of the email will be set to `html` as well. You can also bind the view/layout with
* the args struct and use them accordingly. You can also use body tokens that the service will
* replace for you at runtime.
*
* @view The view to render as the body
* @args The structure of arguments to bind the view/layout with
* @module Optional, the module the view is located in
* @layout Optional, If passed, we will render the view in this layout
* @layoutModule Optional, If passed, the module the layout is in
*/
Mail function setView(
required view,
struct args = {},
module = "",
layout,
layoutModule = ""
)
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:
newMail(
to : "[email protected]",
subject : "Mail Services Rock",
type : "html",
)
.setBodyTokens( {
user : "Luis",
product : "ColdBox",
link : event.buildLink( 'home' )
})
.setView( view : "emails/newUser" )
.send()
newMail(
to : "[email protected]",
subject : "Mail Services Rock",
type : "html",
)
.setView( view : "emails/newUser", layout : "emails" )
.send()
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:
/**
* Add attachment(s) to this payload using a list or array of file locations
*
* @files A list or array of files to attach to this payload
* @remove If true, ColdFusion removes attachment files (if any) after the mail is successfully delivered.
*/
Mail function addAttachments( required files, boolean remove = false )
The files
argument can be a list of file locations or an array of file locations to send.
Example
newMail(
subject = "Hello",
from = "[email protected]",
to = "[email protected]",
body = "Here are your docs"
)
.addAttachments( "c:\temp\reports\report.pdf", true )
.addAttachments( expandpath( "/reports/anotherReport.pdf" ), true )
.addAttachments( [
expandPath( "/logs/maillog.txt" )
expandPath( "/logs/maillog2.txt" )
], true )
.send();
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
/**
* Attach a file or adss a header to the email payload
*
* @contentID The Identifier for the attached file.
* @disposition How the attached file is to be handled: attachment, inline
* @file Attaches file to a message. Mutually exclusive with name argument.
* @type The MIME media type for the attachment.
* @name The name of the email header to attach. See https://cfdocs.org/cfmailparam. Mututally exclusive with file
* @value The value of the header
* @remove Tells ColdFusion to remove any attachments after sucdcesful mail delivery
* @content Lets you send the contents of a ColdFusion variable as an attachment
*/
Mail function addMailParam(
contentID,
disposition,
file,
type,
name,
value,
boolean remove,
content
)
Example
newMail()
.configure(
from = "[email protected]",
to = "[email protected]",
subject = "Mail With Params - Hello Luis"
)
.setBody( "Hello This is my great unit test" )
.addMailParam(
name = "Disposition-Notification-To",
value = "[email protected]"
)
.addMailParam( name = "Importance", value = "High" )
.send();
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
/**
* Add a new mail part to this mail payload
*
* @charset The charset of the part, defaults to utf-8
* @type The valid mime type: text/plain or text/html
* @wraptext Specifies the maximum line length, in characters of the mail text.
* @type The MIME media type for the attachment.
* @body The body of the email according to the type.
*/
Mail function addMailPart(
charset = "utf-8",
type,
numeric wraptext,
body
){
Example
newMail(
from = "[email protected]",
to = "[email protected]",
subject = "Mail MultiPart No Params - Hello Luis"
)
.addMailPart(
type = "text",
body = "You are reading this message as plain text, because your mail reader does not handle it."
)
.addMailPart( type = "html", body = "<h1>This is the body of the message.</h1>" )
.send()
Mail Helper Methods
We have also registered several methods to help you when sending mail:
setReadReceipt( email )
- Set the read receipt emailsetSendReceipt( email )
- Set the send receipt emailsetHtml( body )
- Set a multi-part body for htmlsetText( body )
- Set a multi-part body for textaddAttachments( files, remove=false)
- Easily add attachmentsgetMemento()
- Get the entire mail settings for the payloadhasErrors():boolean
- Verifies if there are any errors in the mailinggetResultMessages():array
- Get's the array of messages of the sending of the mailgetResults():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:
mail.setAdditionalInfo( struct );
mail.getAdditionalInfo();
mail.setAdditionalInfoItem( key, value );
mail.getAdditionalInfoItem( key );
Last updated
Was this helpful?