CF_ADVANCEDEMAIL and CF_ADVANCEDEMAILPARAM

Use CF_ADVANCEDEMAIL together with CF_ADVANCEDEMAILPARAM to write a MIME compliant email to the specified spooldir. Together they have many options of customizing the email message. Not only can this tag be used in cases where CFMAIL fails (see ColdFusion bug #18459), but it offers many extra possibilities like email messages which have a plaintext 'failover' for HTML impaired email clients and inline images in HTML email messages.

CF_ADVANCEDEMAIL Syntax

<CF_ADVANCEDEMAIL
	FROM="emailaddress of sender"
	TO="emailaddress of recipient"
	BCC="emailaddress of recipient"
	SERVER="SMTP server name or IP"
	SPOOLDIR="spooldir"
	CFVERSION="CF Server version"
	TYPE="TEXT/HTML/ALTERNATIVE"
	INLINE="TRUE/LOCAL/FALSE"
	EXCLUDE="comma separated list of file extensions to be excluded"
	MODE="SUMMARYONLY/VIEWONLY/DEBUG/SILENT"
	VARIABLE="name of return-variable"
	TEMPDIR="fully qualified path"
	FORMAT="CF/MDAEMON/MS-SMTP"
	TIMEOUT="timeout"
	PORT="port"
	CACHE="TRUE/FALSE"
	TIMEZONEOVERRIDE="+/-hh,+/-mm"
>

	optional:
	
	HTML email message
	
	<CF_ADVANCEDEMAILPARAM
		CACHE="TRUE/FALSE"
		FILE="filename of attachment"
		MIME="MIME-type of attachment"
		>
	
	<CF_ADVANCEDEMAILPARAM
		NAME="headername"
		VALUE="headervalue"
		>
	
	<CF_ADVANCEDEMAILPARAM
		URL="fully qualified URL"
		>
	
	<CF_ADVANCEDEMAILPARAM
		CONTENTTYPE="HTML/TEXT"
		>
			Content
		</CF_ADVANCEDEMAILPARAM>

</CF_ADVANCEDEMAIL>

FROM

Required. The emailaddress of the sender of the email.

TO

Required. The emailaddress of the intended recipient of the email.

BCC

Optional. The emailaddress of the intended recipient of the email.

SERVER

Required. The SMTP server to use.

SPOOLDIR

Required. The directory that ColdFusion uses as spooldir for emailmessages. On Windows platforms this usually is c:\cfusion\mail\spool\. The directory should end with a \ or a /.

CFVERSION

Optional. The cfversion is used for backward compatibility to specify the CF version. Default is "4.5.0" (which is the correct setting for CF 4.5.1 as well).

TYPE

Optional. The TYPE attribute takes 1 of 3 values (see "Usage" for more details):

HTML. The email message will be send as an HTML message. This requires the presence of an HTML email message.
TEXT. The email message will be send as a text message. This requires the presence of eiher an HTML message from which the text message is extracted automatically or a text message.
ALTERNATIVE. Both an HTML and a text message will be send. This requires the presence of an HTML message.

INLINE

Optional. Whether or not to convert images that are in the source of the HTML message to inline images. TRUE places all images inline, Local all local images and FALSE doesn't lace any images inline (but what would you need cf_advancedemail for then???). Default is "TRUE".

EXCLUDE

Optional. List of extensions that should never be included. Primarily to exclude dynamically generated images. Default is "cfm,cfml,dbm,jsp,cgi,pl,exe,dll,js".

MODE

Optional. The MODE attribute takes 1 of 4 values:

SUMMARYONLY. The tag will display a summary of the message to the screen, but not attempt to send an email. Usefull for discovering all the features of CF_ADVANCEDEMAIL.
VIEWONLY. The tag will display a summary of the message and the generated output to the screen, but not attempt to send an email.
DEBUG. The output is send to the screen together with the summary and the email message is written to the spooldir.
SILENT. Just write the email message to the spooldir. Default.

VARIABLE

Optional. If specified the output is not written to a file but returned as a variable with this name.

TEMPDIR

Optional. Required when retrieving images from remote locations through the web. Use this to specify a tempdir where cf_advancedemail can store temporary files. The directory should end with a / or a \.

FORMAT

Optional. The FORMAT attribute takes 1 of the following values:

CF. The email will be written in a format compatible with the SMTP service integrated with CF. Default.
TEXT. The email will be written as a plain text file. In combination with the use of the SPOOLDIR attribute this can be used to write to the pickup directory of any SMTP server capable of picking up plain text email messages.
BODY. The email will be written as just the body, without any headers but with attachments.

TIMEOUT

Optional. Timeout for trying to connect to the SMTP-server in seconds. Default is 60 seconds.

PORT

Optional. The port of the SMTP-server to be used. Default is 25.

CACHE

Optional. Can be used to disable caching of attachments and inline images. When "FALSE" every time a file is to be attached it will be read from the harddisk. When "TRUE" a check will be done first to see whether the attachment is already in memory and if so the version in memory will be used without requiring the reading and coding of the file. Default is "TRUE".

TIMEZONEOVERRIDE

Optional. CF_ADVANCEDEMAIL uses GetTimeZoneInfo() to get the time zone and format the dat part of a message correctly. Although this works perfectly, the email is generated on the server, and the server might be in a different timezone. Use TIMEZONEOVERRIDE to specify the difference between the server timezone and the desired timezone. Format is "+/-hh,+/-mm" where hh is the difference in hours and mm the difference in minutes.
Test this thoroughly!!! I have not yet created a failsafe method for totalling minutes into hours etc.

Content

Between the opening and closing tags of CF_ADVANCEDEMAIL the actual content of the email message is specified. This includes additional headers like "Subject" and "BCC", attached files and offcourse the body of the email message. The main method of specifying this content is by use of CF_ADVANCEDEMAILPARAM tags.

CF_ADVANCEDEMAILPARAM Syntax

<CF_ADVANCEDEMAILPARAM
	CACHE="TRUE/FALSE"
	FILE="fully qualified path of file to be attached"
	MIME="mimetype"
	NAME="header name"
	VALUE="header value"
	URL="Fully qualified URL"
	CONTENTTYPE="TEXT/HTML"
>

	optional:
	HTML or text email message

</CF_ADVANCEDEMAIL>

CACHES

Optional. When "TRUE" the file will be read from cache if present. "FALSE" forces a read from the harddisk. Default is "TRUE".

FILE

Optional. Mutually exclusive with the "NAME" attribute. Fully qualified path of a file to be attached.

MIME

Optional. Use with the "FILE" attribute to specify the mime-type of the file. Defaults to "image/gif" for files with the extension ".gif", "image/jpg" for files with the extension ".jpg, .jpeg", "image/png" for files with the extension ".png", "text/html" for files with the extension ".html,.htm,.shtml,.shtm,.shm,.cfml,.cfm" and "unknown/unknown" for all others.

NAME

Optional. Mutually exclusive with the "FILE" attribute. Name of the header. Can be "Subject", "Reply-to" etc, as long as it is a RF2C822 compliant name. The use of "BCC" and "CC" is deprecated and will be ignored. Proper placement is in the <CF_ADVANCEDEMAIL> tag.

VALUE

Optional for this tag but required when using the "NAME" attribute. The value to be associated with the header name.

TEMPDIR

Optional. Required when the URL attribute is used. Use this to specify a temporary directory where cf_advancedemail can temporarily store images. Requires no end tag.

URL

Optional. Use this to specify a URL from where cf_advancedemail should get the body of the email message. Forces the INLINE attribute of cf_advancedemail to TRUE. Requires the use of a TEMPDIR attribute. Requires no end tag.

CONTENTTYPE

Optional. Use this to specify that the following code is either the text or the HTML email message. Requires end tag.

MESSAGE

Optional. Use in conjunction with the "CONTENTTYPE" attribute to type either the HTML or the text that is to be the email message. Requires end tag.

</CF_ADVANCEDEMAILPARAM>

Optional for the tag but required when using the "CONTENTTYPE" attribute.

Usage

Use CF_ADVANCEDEMAIL to send an email with inline images, in both HTML and plaintext, with multiple attachments. To say it simple: CF_ADVANCEDEMAIL should be bought by Allaire to be the next CFMAIL ;).
The following are prerequisits for the use of this tag:

<CFFILE> is enabled
The location of the email spooldir is known

<CF_ADVANCEDEMAIL> throws an error when it encounters one. Use the "MODE" attribute to specify what output should be returned.
<CF_ADVANCEDEMAIL> creates a structure named ADVANCEDEMAIL in the request scope. It will not throw an error if the structure already exists, but will simply use the present structure, what might cause data integrity problems for other operations (extremely unlikely that ADVANCEDEMAIL will have problems). It is necessary to use the request scope to enable caching of information to reduce file operations and to transfer data from the CF_ADVANCEDEMAILPARAM tags to the CFADVANCEDEMAIL tags.
It is recommended NOT to use a structure named ADVANCEDEMAIL in the request scope.
If required the structure can be cleared programmatically using <cfset temp=StructClear(request.AdvancedEmail)>. This will also delete all cached information.

Contrary to the way <CFMAIL> works <CF_ADVANCEDEMAIL> does not automagically start an implied <CFOUTPUT> block inside the tag. The reason is that I want to allow everybody the freedom to loop anyway he wants inside <CF_ADVANCEDEMAIL>.
The downside is that a <CFOUTPUT> tag must be explicitly specified when using <cfsetting enablecfoutput="yes">.

Examples

To send an email quick and dirty use the syntax below. CF_ADVANCEDEMAIL will automatically use the title (Requested image of property) as the Subject of the email message, and will send a version with all the tags stripped out along as a text message. Because the image in the HTML resides on a local disk it is automatically attached as an inline image.

<cf_advancedemail 
	from="me@mydomain.com"
	to="you@yourdomain.com"
	server="smtp.mydomain.com"
	spooldir="C:\cfusion\mail\spool\"
>
	<html>
	<head>
		<title>Requested image of property</title>
	</head>
	<body>
		<p>Please contact me if this images is not clear enough.</p>
		<p><img src="C:\images\pool.jpg"></p>
		<p>Cheers,<br>Me</p>
	</body>
	</html>
</cf_advancedemail>

With an email client that can not read HTML messages the message would not be very well-formatted. Some extra linebreaks in the HTML would do the trick, but you can also be a little more elaborate and write a special text message like below. Please note the use of CF_ADVANCEDEMAILPARAM to specify the text and HTML messages.

<cf_advancedemail 
	from="me@mydomain.com"
	to="you@yourdomain.com"
	server="smtp.mydomain.com"
	spooldir="C:\cfusion\mail\spool\"
>
	<cf_advancedemailparam contenttype="Text">
		You need an HTML capable email client for this message. You can also read it at http://www.mydomain.com/specialpage.cfm
		
		Cheers,
		Me
	</cf_advancedemailparam>
	<cf_advancedemailparam contenttype="HTML">
		<html>
		<head>
			<title>Requested image of property</title>
		</head>
		<body>
			<p>Please contact me if this images is not clear enough.</p>
			<p><img src="C:\images\pool.jpg"></p>
			<p>Cheers,<br>Me</p>
		</body>
		</html>
	</cf_advancedemailparam>
</cf_advancedemail>

You do not need to use CF_ADVANCEDEMAILPARAM to specify the HTML message. If not present, the entire text between the opening and closing CF_ADVANCEDEMAIL tags is used as the HTML-message (excluding CF tags and custom tags of course).
Functionally the message below is exactly the same as the one above.

<cf_advancedemail 
	from="me@mydomain.com"
	to="you@yourdomain.com"
	server="smtp.mydomain.com"
	spooldir="C:\cfusion\mail\spool\"
>
	<cf_advancedemailparam contenttype="Text">
		You need an HTML capable email client for this message. You can also read it at http://www.mydomain.com/specialpage.cfm
		
		Cheers,
		Me
	</cf_advancedemailparam>
	<html>
	<head>
		<title>Requested image of property</title>
	</head>
	<body>
		<p>Please contact me if this images is not clear enough.</p>
		<p><img src="C:\images\pool.jpg"></p>
		<p>Cheers,<br>Me</p>
	</body>
	</html>
</cf_advancedemail>

Use additional CF_ADVANCEDEMAILPARAM tags to specify extra headers and attachments.
Notice the CACHE="FALSE" attribute to make sure that every customer gets the database that is created specially for him in the same loop and the mime type that is set so people can open the database from their email client directly.

<cf_advancedemail 
	from="me@mydomain.com"
	to="you@yourdomain.com"
	server="smtp.mydomain.com"
	spooldir="C:\cfusion\mail\spool\"
>
	<cf_advancedemailparam name="BCC" value="yourwife@herdomain.com">
	<cf_advancedemailparam contenttype="Text">
		You need an HTML capable email client for this message. You can also read it at http://www.mydomain.com/specialpage.cfm
		
		Cheers,
		Me
	</cf_advancedemailparam>
	<cf_advancedemailparam file="C:\databases\custominfo.mdb" cache="FALSE" mime="application/access">
	<cf_advancedemailparam contenttype="HTML">
		<html>
		<head>
			<title>Requested image of property</title>
		</head>
		<body>
			<p>Please contact me if this images is not clear enough.</p>
			<p><img src="C:\images\pool.jpg"></p>
			<p>Cheers,<br>Me</p>
		</body>
		</html>
	</cf_advancedemailparam>
	<cf_advancedemailparam name="BCC" value="youraccountant@hisdomain.com">
</cf_advancedemail>

Note to ISP's

To my knowledge this tag entails no security issues other than those related to CFMAIL. Due to the different filename format there is ZERO POSSIBILTY for this email to overwrite email send by CFMAIL that might be residing in the spooldir.
If you want to enable this tag in a high security environment I suggest that you hardcode the spooldir into the template. This will allow you to disable <CFFILE ACTION="write"> for all your users, but still enable it for only this tag using Advanced Security and CFIMPERSONATE.

Questions, remarks and suggestions can be mailed to jochemd@oli.tudelft.nl