Using the CFMAIL Tag

Team-Fly

---

	ColdFusion® MX: From Static to Dynamic in 10 Steps By Barry Moore
	Table of Contents
	Step 7.  Using Email with ColdFusion MX

---

Using the <CFMAIL> Tag

The <CFMAIL> tag is used to create SMTP mail from within your ColdFusion templates. The mail is then passed to the nominated SMTP server for delivery.

The <CFMAIL> tag is quite easy to use. The following code shows a simple example of the use of the <CFMAIL> tag:

 <CFMAIL TO="[e-mail]"          FROM="[e-mail]"          SUBJECT="Using CFMAIL">  It is really this easy!  </CFMAIL>

The <CFMAIL> tag has three required attributes: TO, FROM, and SUBJECT. All other attributes are optional. These required attributes function exactly the same way they would with a traditional email client, such as Outlook Express. The TO attribute specifies to whom the message will be delivered, the FROM attribute identifies whom the message is from, and the SUBJECT attribute specifies what text should appear in the subject line of the email. Everything between the opening and closing <CFMAIL> tags is the body of the email message. See Table 7.1 for a list of commonly used <CFMAIL> attributes. For a complete list of attributes, see the Reference section of the www.LearnColdFusionMX.com web site.

Table 7.1. <CFMAIL> Attributes

Attribute	Description
TO	Required. Recipient's email address(es). Multiple addresses must be separated by a comma.
FROM	Required. The sender's email address.
SUBJECT	Required. Text that will appear in the subject line.
BCC	Blind carbon copy address(es).
CC	Carbon copy address(es).
MAXROWS	Used with the QUERY attribute to specify the maximum number of emails to generate.
PORT	Used with the SERVER attribute to specify the SMTP server port. Not required if the server uses the default value of 25.
QUERY	Specifies the <CFQUERY> name to use to generate email.
SERVER	The SMTP server name. Overrides the SMTP server setting in ColdFusion Administrator.
TIMEOUT	Specifies how long to wait for an SMTP connection. Overrides the value set in ColdFusion Administrator.
TYPE	The only valid value is HTML. Specifies that the email message contains HTML tags.

If you do not have access to ColdFusion Administrator, you can nominate the SMTP server you would like to use from within the <CFMAIL> tag itself by using the SERVER attribute. You can also use the PORT attribute to specify the SMTP server port if it is different from the default value of 25. The following example shows the use of the SERVER attribute:

 <CFMAIL TO="[e-mail]"          FROM="[e-mail]"          SUBJECT="Using CFMAIL"          SERVER="smtpserver.myisp.com">  It is really this easy!  </CFMAIL>

In this example, we have added the SERVER attribute to the opening <CFMAIL> tag and have specified the name of an SMTP mail server provided by our Internet service provider. If you are unsure of your mail server's name, you can usually find this information by checking the settings of your email client. For example, if you use Outlook Express, you can find the name of your mail server by selecting Accounts from the Tools menu. In the Internet Accounts dialog box, choose the Mail tab, highlight your server, and click on the Properties button. On the Server tab of the Properties dialog box, note the value in the Outgoing Mail (SMTP) box. This is your SMTP mail server's name; you should be able to use this value as the SERVER attribute in your <CFMAIL> tags.

If you use the SERVER attribute in your <CFMAIL> tag, it will override any value that might already be set in ColdFusion Administrator.

In the preceding examples, we just used plain text for our email message, but this is not your only option. You can use ColdFusion variables as well. This means that you can dynamically create emails just like you can dynamically create web pages. The use of the <CFMAIL> tag is very similar to that of the <CFOUTPUT> tag. We can include ColdFusion variables between the opening and closing <CFMAIL> tags in the same way we would use variables between <CFOUTPUT> tags. The following code illustrates this:

 <CFSET UserName="Emma">  <CFSET UserEmail="[e-mail]">  <CFMAIL TO="#UserEmail#"          FROM="[e-mail]"          SUBJECT="Using CFMAIL"          SERVER="smtpserver.myisp.com">  Hello #UserName#, nice to hear from you!  </CFMAIL>  <CFOUTPUT> Your email to #UserName# has been sent. </CFOUTPUT>

In the preceding code, we use <CFSET> to set the value of two local variables: UserName and UserEmail. Then we use the value of the UserEmail variable in our <CFMAIL> tag to set the TO address for the email. The body of the email message uses the value of the UserName variable to personalize the email. Further down the template, we use <CFOUTPUT> and the UserName variable to display a confirmation message in the browser.

You can see that using ColdFusion variables to create our email messages can be quite a powerful thing. It gives us the capability to create dynamic, personalized, automated email systems to interact with our web site users. The use of variables with <CFMAIL> is not limited to local variables; you can use variables from other scopes, such as URL and FORM. In the section "Advanced <CFMAIL> Attributes" later in this step, we will also see how to use database queries to send bulk email.

NOTE

You can address ColdFusion email to more than one person by placing multiple email addresses in the TO attribute. Multiple email addresses should be separated by a comma, as illustrated in the following code. You can also use the CC and BCC attributes to send carbon copies and blind carbon copies, respectively.

 <CFMAIL TO="[e-mail],[e-mail]"          CC="[e-mail]"          BCC="[e-mail]"          FROM="[e-mail]"          SUBJECT="Using CFMAIL"          SERVER="smtpserver.myisp.com">  Hello everyone, nice to hear from you!  </CFMAIL>

---

Team-Fly

Top