Sending Mail with ColdFusion

ColdFusion provides out-of-the-box support for sending email through Simple Mail Transfer Protocol (SMTP) mail servers with the <cfmail> tag. The ColdFusion Application Server does not ship with its own built-in SMTP mail server. To provide messaging services for your application, you must have access to a separate SMTP server (the same is true for POP mail, described later in this chapter).

Sending Simple Text Email

<cfmail>'s behavior is similar to that of <cfoutput>. Whereas <cfoutput> sends information back to the Web browser, <cfmail> outputs the same information to an email message. The additional attributes of <cfmail> correspond to those fields required to correctly format an email message.

<cfmail> can contain CFML, and it resolves variables just like <cfoutput>. However, although <cfmail> accepts a query attribute, its behavior depends on how the query is used. This issue is discussed in detail later in this chapter.

You can specify multiple recipients by providing a comma-separated list of qualified email addresses, as follows:

 <cfmail to="[e-mail],[e-mail]"         from="[e-mail]"         subject="Hope you're feeling better!"         cc="[e-mail]"         bcc="[e-mail]"> <cfif recipient is "alive"> Hey, get well soon ... hope I'm not too late. </cfif> This message was sent #DateFormat(Now())#. </cfmail> 

Lists were covered in Chapter 13, "Lists."

You can specify a default SMTP mail server in ColdFusion Administrator. Alternatively, you can specify SMTP settings in the <cfmail> tag itself, which will override the default settings. If no SMTP server is specified, a standard ColdFusion run-time error occurs.

TIP

Text inside an email message is not like text on a Web page. White space can be very important in an email message, and every space, tab, and return affects the formatting. So you need to be careful how you format ColdFusion code within the <cfmail> tag.

Long lines of text without line breaks may cause some email clients to display the message improperly. It is good practice to force text wrapping in your message by starting a new line at the end of every 65 characters or so. Several third-party Custom Tags are available to help implement text wrapping.

CAUTION

If you place a single period (.) on its own line in the body of a generated email message, some SMTP servers see it as a command to end the message and may truncate your text at that point.

Sending HTML Email

You can use <cfmail> to send HTML mail by setting the appropriate attribute, as shown in the following example:

 <cfmail from="[e-mail]"         to="[e-mail]"         subject="This Month in Fun Stuff!"         type="HTML"> <h1>November Fun Stuff</h1> <p>Jump for joy fun stuff brings you <strong>plenty</strong> of things to keep you <font color="red">amused</font> for hours.</p> </cfmail> 

The type attribute sets headers for the receiving email client; these headers serve as instructions that the email message contains embedded HTML to be rendered. Images in the HTML are typically referenced with absolute URLs to servers online and are not included in the HTML message itself.

CAUTION

Not all email clients can handle HTML mail. Indeed, even among those clients that can, some users may have set their preferences to view email as text rather than HTML. HTML mail in a text email client is difficult to read.

If you reference images in your message, the recipient must be online to be able to see them. Otherwise, all she'll see are a series of broken images. References to images should consist of complete (absolute) URLs, not relative URLs.

Query-Driven Email

Just like <cfoutput>, <cfmail> can loop over a query object, as shown here, resolving each record in the query into an individual and personalized email:

 <cfmail query="GetCustomers"         from="[e-mail]"         to="#EMail#"         subject="Registration Verification"> Dear #FirstName#, We'd like to verify ... blah ... blah ... </cfmail> 

You can use the GROUP attribute in a fashion similar to that of GROUP in <CFOUTPUT>. You also can group sets of records to send a series of individual email messages, each with the records of a particular group category.

Using a nested set of <cfoutput> tags has a slightly different effect than you might expect. The code behaves as though you are using group, except that all the records belong to a single group category. The text within the nested <cfoutput> tag is repeated for every row in the nominated query, as shown in the following example, while the text surrounding it serves as the header and footer for a single email message:

 <cfmail query="ProductRequests"         from="[e-mail]"         to="[e-mail]"         subject="MegaDeveloper Status Report"> Here is a list of people who have inquired about MegaDeveloper over the last seven days: <cfoutput> #FirstName# #LastName# (#Company#) - #EMailAddress# </cfoutput> Regards, The WebMaster [e-mail] </cfmail> 

Sending File Attachments

<cfmailparam> is a subtag of <cfmail>. To send MIME-encoded file attachments, you can use it as follows:

 <cfmail from="[e-mail]"         to="[e-mail]"         subject="Monthly Reports"> <cfmailparam file="c:\reports\jan.xls"> <cfmailparam file="c:\reports\feb.xls"> Here is a copy of the sales numbers. Regards </cfmail> 

The file attribute must specify an absolute path on the ColdFusion server to the file being attached. You can specify multiple files by using multiple <cfmailparam> tags.

A common misconception is that users can combine an email form and a file attachment in their Web applications. The file must be on the ColdFusion server, not the client's workstation, in order for the mail attachment to work. Web-based mail clients use a two-step process for attachments: uploading the files to the server, then sending and attaching the files to the email.

Chapter 39, "System Integration," discussed uploading files to the server.

NOTE

In earlier versions of ColdFusion, the mimeattach attribute was used to specify a single file attachment only. This attribute has been superseded by the <cfmailparam> tag, but the server continues to be backward-compatible.

Inline Attachments

Attachments can also be used within the message body. For example, an HTML e-mail message may refer to an image that is included with the message as an attachment (instead of needing a URL back to a server). To do this use <cfmailparam> and specify disposition="inline" and a contentid. That contentid can then be used within the message body, like this:

 <cfmail from="[e-mail]"         to="[e-mail]"         subject="Hi there">         type="html"> <cfmailparam file="c:\images\ben.gif"              disposition="inline"              content> <img src="/books/2/445/1/html/2/cid:ben"> </cfmail> 

Additional Mail Headers

You can set additional mail headersbeyond those that you can specify directly from the <CFMAIL> attributesby using <cfmailparam> as follows:

 <cfmail from="[e-mail]"         to="[e-mail]"         subject="Shipping!"> <cfmailparam name="Reply-To"              value="[e-mail]"> The new CF Certification Study Guide is shipping! </cfmail>