The ColdBox Mail services module will allow you to send email the OO way in multiple protocols for many environments. The supported protocols are:
- CFMail - Traditional
cfmailsending - Null - Ignores emails sent to it.
- InMemory - Store email mementos in an array. Perfect for testing.
- Files - Write emails to disk
- Postmark API - Send via the PostMark Service (https://postmarkapp.com/)
You can easily add your own mail protocols by building upon our standards.
Apache License, Version 2.0.
- https://github.com/coldbox-modules/cbmailservices
- http://forgebox.io/view/cbmailservices
- Changelog
- Lucee 5+
- ColdFusion 2016+
Just drop into your modules folder or use the box-cli to install
box install cbmailservices
The mail services registers all mail components so you can use them in your application.
You will need to update the your ColdBox.cfc with a mailsettings structure with your preferred mail settings and mail protocol to use. All the keys that can go into the mailsettings struct map 1-1 to the cfmail tag except for the tokenMarker and protocol keys. See below for more information on other protocols you can use.
mailsettings = {
// The default token Marker Symbol
tokenMarker = "@",
// protocol
protocol = {
class = "cbmailservices.models.protocols.CFMailProtocol",
properties = {}
}
};This will register a mailService@cbmailservices in WireBox that you can leverage for usage.
// build one-off mail
var mailService = getInstance( "mailService@cbmailservices" );
var oMail = mailService.newMail(
to="email@email.com",
from="no_reply@ortussolutions.com",
subject="Mail Services Rock",
type="html",
bodyTokens={
user="Luis",
product="ColdBox",
link=event.buildLink( 'home' )
}
);
// add 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 );You can also inject mailService into your components as you would with other modules to avoid the getInstance() call.
property name="mailService" inject="MailService@cbmailservices";The Mail object has some additional methods to allow you to pass additional information so protocols can leverage them:
setAdditionalInfo( struct );
getAdditionalInfo();
setAdditionalInfoItem( key, value );
getAdditionalInfoItem( key );The mail services can send mail via different protocols. The available protocols are:
CFMailProtocolNullProtocolInMemoryProtocolFileProtocolPostmarkProtocol
You register the protocols in the mailsettings via the protocol structure:
// FileProtocol
protocol = {
class = "cbmailservices.models.protocols.FileProtocol",
properties = {
filePath = "logs",
autoExpand = true
}
};
// NullProtocol
protocol = {
class = "cbmailservices.models.protocols.NullProtocol",
properties = {}
};
// InMemoryProtocol
protocol = {
class = "cbmailservices.models.protocols.InMemoryProtocol",
properties = {}
};
// PostMark
protocol = {
class = "cbmailservices.models.protocols.PostmarkProtocol",
properties = {
APIKey = ""
}
};In order to create your own custom protocol you will create a CFC that inherits from cbmailservices.models.AbstractProtocol and make sure you implement the init() and send() method.
The module will register two interception points. PreMailSend and PostMailSend. These interception points are useful to alter the mail object before it gets sent out, and/or perform any functions after the mail gets sent out. An example interceptor would be:
component extends="coldbox.system.Interceptor"{
void function configure(){
}
boolean function preMailSend( event, interceptData, buffer, rc, prc ){
var environment = getSetting('environment');
var appName = getSetting('appName');
var mail = interceptData.mail;
var subject = mail.getSubject()
if(environment eq 'development'){
//change recipient if we are on development
mail.setTo('johndoe@example.com');
//prefix the subject if we are on development
mail.setSubject('<DEV-#appName#> #subject#');
}
return false;
}
boolean function postMailSend( event, interceptData, buffer, rc, prc ){
if(interceptData.result.error eq true){
//log mail failure here...
}
return false;
}
}Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.ortussolutions.com
Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.
"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God. And not only so, but we glory in tribulations also: knowing that tribulation worketh patience; And patience, experience; and experience, hope: And hope maketh not ashamed; because the love of God is shed abroad in our hearts by the Holy Ghost which is given unto us. ." Romans 5:5
"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12