The CFMAIL tag is the key to sending mail in ColdFusion.
The basic mechanism is this: The structure of the e-mail (such the recipient list, the subject line, and sender) are specified as attributes to the CFMAIL tag. The content of the message is placed between opening and closing CFMAIL tags.
The critical attributes used in the CFMAIL tag are:
TO Specifies the e-mail address (or addresses) of the recipients
FROM Specifies the content of the From line of the message
SUBJECT Specifies the Subject line of the e-mail
Let’s consider a simple example:
SUBJECT-‘A SamPle ColdFusion Email’>
In this small example. you use the three attribute values just discussed to cause Cold-Fusion to send an e-mail to someoneOsome. doea+n, with a From address of thesenderOanother .doma! n and a Subject line that reads A Sampl e ColdFus; on E-mail. The body of the message contains one line: This is my test message.
The resulting e-mail message would look something like this:
Subject: A Sample ColdFusion E-mail
This is my test message
Of course, if this were all that the CFMAILtag could do, it wouldn’t be very useful in the context of ColdFusion. The CFMAILtag provides much more, including the capability to specify recipients who will receive a copy, the message type, and MIME attachments, as web as the ability to work interactively with database query results in much the same way that the CFOUTPUTtag does,
Using Additional Message Strudure’ Attributes
In addition to the three attributes we have already discussed, the CFMAILtag also can take the following attributes, which further define the structure of the outgoing message: Specifies the recipients of a copyof the m~ge (which becomes the CC line in the outgoing message)
Bee Specifies the recipients of a blind copy of the message (which becomes the BCC line in the outgoing message); recipients of a blind copy are not listed in the message header so the intended recipients are unaware that they have received the message.
TYPE Specifies the content type of the message. By default, all outgoing messages are assumed to be plain text messages. You can use the TYPEattribute to specify a single alternate type, HTML. HTML messages can be read by HTML-enabled mail programs such as Microsoft Outlook or Netscape Communicator.
NAMEATTACH Specifies the path and filename of a file to be attached to the outgoing e-mail message as a MIME attachment. MIME attachments are the standard type of attachment and are supported by all leading mail client packages.
SERVER Specifies an alternate SMTP mail server. By default, the mail server specified in the ColdFusion Administrator (as described earlier in this chapter) is used for sending outgoing messages.
PORT Specifies an alternate TCP lIP port to use when connecting to the S0.ITPmail server. By default, the port specified in the ColdFusion Administrator is used.
TIMEOUT Specifies an alternate connection timeout in seconds to use when connecting to the SMTP mail server. By default, the timeout specified in the ColdFusion Administrator is used.
MAILERID Specifies a mailer ID that appears in the X-Mailer line of the message header. Coldfusion’s default is ColdFusion Application Server. Generally, you will not need to provide an alternate value.
The TYPE Attribute
Using the TYPE attribute, you can create HTML e-mail messages that will be formatted correctly bye-mail client software that supports HTML messages. Examples of such software include Microsoft Outlook, Outlook Express, Netscape Communicator, and Netscape Navigator 3.
To do this, you need to add TYPE=”HTML” to your CFMAIL tag. Then you can create a message-containing HTML tags:
SUBJECT-‘A Sample ColdFusion E-mail’
<Hl>An HTML message</Hl>
This is my test message
The result is a message that looks like the one displayed in Figure 21.3 (Microsoft Outlook is being used here to display the message).
The MIMEATrACH Attribute
With the MIMEATIACH attribute, you can attach any type of file to your e-mail including, but not limited to, HTML files, Microsoft Word files, and image files. To do this, the MIMEATIACH attribute is used to specify the path and filename of the file you want to attach, and then ColdFusion does the rest of the work. For instance, to attach a Microsoft Word document to a message, you would use a CFMAIL tag similar to the one in the following example:
SUBJECT-“A Sample ColdFusion E-mail ‘.
Thi s is my test message. I have attached a Mi crosoft Word file.
Working with Dynamic Data
You can use dynamic data with the CFMAIL tag in several ways, including:
• Generating e-mail from the contents of a form
• Generating message content from the results of a query (from a database table, for example)
• Generating recipient lists from the results of a query
Generating E-Mail from the Contents of a Form
As with most everything in Cold Fusion, you can use the contents of variables, including those that are the result of data submitted in a form, to specify values for tag attributes. For instance, consider a simple example in which a Web site enables users to send a quick, standardized greeting to a friend bye-mail. The Web site could use a form similar to Listing 21.1.
What has happened here is that the contents of the to field in the form are used to address the message, and the contents of the name field are used to personalize the message.
Of course, our senag reeti n9. cfm template has a fundamental problem: What nappens if no e-mail address is specified? You need to add some error handling to account for this possibility, as shown in Listing 21.2.
Now, if the user forgets to provide an e-mail address, tiIh1.ey will ‘bepresented with an error. message like the’ one in Figure 21.5, and no attemplt will be made to send an e-mail.
Let’s take this use of forms one step further and see how CFMAIL can be used to quickly set up a contact form that gets submitted bye-mail to a predetermined address. CC;nsider the standard contact form shown in Listing 21.3.
So far. this looks like a fairly generic contact form, With ColdFusion, though, you can easily create the submit contact , cfm template that will process the contents of the form,
generate a contact e-rnail to the appropriate recipient, and inform the Web user that the form has been submitted (see Listing 21.4).
Here you have used ColdFusion to easily create a template that not only sends the contents of the form as a formatted e-mail, but also informs the Web user that their form has been submitted. This code is easier to generate than a similar CGI-BIN form to a mail handler written in a language such as Perl orC and is more effective than the less elegant approach of using mai 1 to: firstname.lastname@example.org as the value of the FORM tag’s ACTION attribute. In the latter case, the form gets submitted in an unforrnatted style to the e-mail address, and the user receives no confirmation that the message has been sent.
Generating MesSJlge Content from a Query’
As you did with the CFOUTPUTtag, you can use the results of a query to generate dynamic output for a mail message. Consider a theoretical example: Y6u have a data source named GuestData that contains a single table called Contacts, which is a list of contact names and e-mail addresses received from a guest book on your Web site. You want to create an e-mailbased report of all the e-mail addresses in this table. You could use ColdFusion to create the following template:
This template will produce an e-mail message whose body looks like.the following:
Someone’some.where — Some Person
AnotheroneOelse.where — Another Person
YetanotherOwho.else – Yet Another Person
In this example, you have used the QUERYattribute k>specify which query results are accessible to the CFMAIltag and then used the CFOUTPUTtag in the body of the message to iterate through all the rows of the query result and display the relevant information.