ColdFusion MX: From Static to Dynamic in 10 Steps

By Barry Moore

Advanced <CFMAIL> Attributes

So far, we have seen how to use <CFMAIL> to send relatively simple email messages using either plain text or HTML. In this section, we will look at a few more advanced topics, such as adding multiple attachments and sending email to multiple recipients.

Using the <CFMAILPARAM> Tag

The <CFMAIL> tag is not the only tag that deals with sending email. There is an additional tag called <CFMAILPARAM>. The <CFMAILPARAM> tag has two functions:

• Adding custom email headers

• Adding attachments

All SMTP email messages contain several email headers that are not usually visible to the recipients of the message. These headers are used by mail servers and email client applications to route and handle email. One example of a common header you might be familiar with is the Reply To header. If you want to send email from one account but have replies redirected to another account if the recipient clicks the Reply button, you can specify an optional Reply To address. Many email clients give you the capability to enter this information if you want.

For example, if you are using Microsoft Outlook and want to send out some product information to a customer using your normal everyday email account, but you'd like replies from that customer to go to a special sales account, you would need to nominate a different Reply To address. This is done in Outlook by choosing Options from the toolbar of your email message. After choosing Options, you will be presented with a dialog box that enables you to specify a different Reply To address, as shown in Figure 7.8.

To include these optional headers for messages you send using <CFMAIL>, you can add them using the <CFMAILPARAM> tag as follows:

<CFMAIL TO="customer@anysite.com" FROM="automail@work.com" SUBJECT="Product Information" SERVER="mail.server.name"> <!--- add custom email header ---> <CFMAILPARAM NAME="Reply-To" VALUE="realperson@work.com"> Here is the product information you requested --product information here-- --------------------------- Official My Company Email. </CFMAIL>

In this code, we specify the name of the email header we would like to include using the NAME attribute. We then specify the value we'd like that header to have using the VALUE attribute.

ColdFusion sends this message using the <CFMAIL> tag. Recipients of the message see automail@work.com as the sender's address on the message. If a recipient responds to this message using the Reply button in his email client, that reply email will be sent to realperson@work.com, which is a live email address of one of our staff members.

The other use of the <CFMAILPARAM> tag is to add attachments to outgoing messages. For example, we might have a form set up in which our web site users can request more information on certain products. We would then want ColdFusion to send them Acrobat or Word documents as attachments to an email.

To accomplish this, you would simply use the <CFMAILPARAM> tag to attach the files using the FILE attribute to specify the name of the file. The files must be available to the server machine either locally, on the server's hard drive, or on a network share that the server can access. You must also use fully qualified path names to the files; relative path names are not supported. The following example illustrates the use of <CFMAILPARAM> to attach an Abode Acrobat file to an email message:

<CFMAIL TO="customer@anysite.com" FROM="#automail@work.com" SUBJECT="Product Information" SERVER="mail.server.name"> <!--- add custom email header ---> <CFMAILPARAM NAME="Reply-To" VALUE="realperson@work.com"> <!--- add attachments from the server's C: drive ---> <CFMAILPARAM FILE="C:\Products\Infosheets\Product1.pdf"> <CFMAILPARAM FILE="C:\Products\Infosheets\Product2.pdf"> Here is the product information you requested --------------------------- Official My Company Email. </CFMAIL>

As you can see from the preceding code, we can attach multiple documents to an email simply by using a <CFMAILPARAM> tag for each attachment. The two <CFMAILPARAM> tags used here attach two Adobe Acrobat files to our email. Both of these files are located on the C: drive of our web server.

Using Query Information with <CFMAIL>

Another handy feature is the capability to send bulk email. To this point, we have just been sending email to a few recipients at a time through the use of the TO, CC, and BCC attributes. To reach the maximum number of people, we would like to have the capability to bulk email hundreds or even thousands of people at a time.

The <CFMAIL> tag gives us this capability through its support of the QUERY attribute. As previously mentioned, the <CFMAIL> tag functions in a similar fashion to the <CFOUTPUT> tag. This includes the <CFMAIL> tag's capability to loop through query results. Let's have a look at an example.

<CFQUERY NAME="qMailingList" DATASOURCE="Contacts"> SELECT FirtsName,LastName,EmailAddress FROM Contacts </CFQUERY> <CFMAIL QUERY="qMailingList" TO="#EmailAddress#" FROM="ceo@work.com" SUBJECT="Bulk Email-o-Rama"> <!--- you can use fields from the query in your email ---> Hello #FirstName# #LastName#, I am personally taking the time to send you this email because you are important to me! </CFMAIL>

To send bulk mail using <CFMAIL>, you must first query a data source that contains the list of email addresses to which you want to send mail. Then you use the QUERY attribute of the <CFMAIL> tag to tell <CFMAIL> which query to use. After you have nominated the query to use, <CFMAIL> will function just like <CFOUTPUT>. You will be able to use fields from the query within your CFMAIL posting. This includes the capability to use the database information in both the <CFMAIL> tag attributes and the message body. Like the <CFOUTPUT> tag, the <CFMAIL> tag will loop over the resulting recordset until it runs out of data.

In the preceding example, we query an existing data source called Contacts and name that query qMailingList. We then use the QUERY attribute of the <CFMAIL> tag to indicate that we want to use information from that query in our <CFMAIL> output block.

We use a field from the query called EmailAddress in the TO attribute to address the message. In the body of the message, we use two more fields from the query to personalize the email message for that person. The <CFMAIL> tag will then loop through query results and send a copy of the email to everyone in the database.

As you can see, the capability to use query information with <CFMAIL> can be a very powerful feature. Remember, however, that the ColdFusion Server software on your web server must loop through all these emails while simultaneously serving web pages to the public. If you set up a template to loop through thousands of emails (that might include HTML markup and attachments), this will undoubtedly have an impact on your server's performance, and regular web site browsing might slow. This is especially true if the SMTP server and the web server are on the same machine.

You can address these issues by enhancing the hardware that your server uses. You could also try to send your bulk email during off-peak hours when the load on the server is lower.