CFMAIL

CFMAIL

The CFMAIL tag enables you as a developer to have your web application act as an email client, creating and sending email to anyone or anything that has a valid email address.

Creating an email message inside your web application using CFMAIL isn't that much different from what you do when you create an email message manually using Outlook or Eudora. The process is essentially the same. Just as Outlook can't do anything with the email other than create it, neither can ColdFusion's CFMAIL tag do anything with the mail message other than get it ready to be sent to the mail server that you've specified.

Let's start by looking at a simple example. In this example, we want our template to send an email message to [e-mail] that says "Hello Pengo!".

Assuming that we've already set up our ColdFusion Administrator to connect with our mail server, the following code accomplishes our goal:

 <cfmail from="[e-mail]"          to="[e-mail]"          subject="Hello">  Hello Pengo!  </cfmail> 

If your mail server was set up correctly in the ColdFusion Administrator, in just a few moments, [e-mail] should be reading the wonderfully cheery greeting.

Now, what if you had no access to the ColdFusion Administrator, but you still wanted to send this message automatically from within one of your templates? In such a case, you'd need to make use of some of the additional parameters of the CFMAIL tag to specify the mail server that you are going to use, the port on which you'll send, and so on:

 <cfmail from="[e-mail]"          to="[e-mail]"          subject="Hello"          server="IP Address or host name of the mail server"          port="Port on the mail server to send to">  Hello Pengo!  </cfmail> 

Of course, this is a very simple example of how CFMAIL works, but it should clearly illustrate how the CFMAIL tag is essentially acting as another mail client for, in this case, your web application.

In most cases, you won't know in advance the email address of the person to whom you're sending the email. In most situations, you'll want to be able to automatically send email to a user in response to a request he or she has made to your site.

Let me give you a real-world example. Let's say that you have a site that requires username/password access to certain areas. You want users to be able to register with your site, specifying the email addresses and passwords they'd like to use. After they've done this, you'd like to automate the entire process of creating username/password combinations and emailing the information to them. With CFMAIL, this can be done quite easily:

1. A user visits your site and requests a username/password combination by filling out a form that asks for the email address and password he or she would like to use.

2. After the form is submitted, the email address and password is dumped into a database where you keep your users' information.

3. The same "action" page where you inserted the email address and password into the database could also automatically email the new account information back to the user by making use of the CFMAIL tag in the following manner:

    <cfmail from="[e-mail]"          to="#form.emailAddress#"          subject="Your account has been created">  Based on your recent request for a username and password to our site, an  account has been created for you.   Your account information is as  follows:  Username: #form.emailAddress#  Password: #form.password#  </cfmail> 

In addition to plain-text email, CFMAIL enables you to send email in Hypertext Markup Language (HTML) format and to attach files as you would with any other mail client.

When you send mail in plain-text format, the message is sent exactly as it is formatted, with all whitespace and carriage returns included.

The CFMAIL tag behaves similarly to the CFOUTPUT tag, in that any variables contained within them are evaluated and the evaluation is included in the resulting output.

Table 11.1 describes the attributes that can be used with the CFMAIL tag to control how mail is sent.

Table 11.1. Attributes That Can Be Used with CFMAIL

Attribute	Description
To	This is a required attribute that specifies to whom the email should be sent. There are three ways in which you can specify a to address. You can enter the address manually ([e-mail]), you can use a variable that resolves to an email address (#form.emailAddress#), or you can use the name of a query column that contains email addresses. If you use a query column variable in the to parameter, remember that a copy of the email is sent to each email address contained in the query result set.
From	This is a required attribute that lets the recipient of the email know from whom the mail is coming. Again, this address can be specified manually or by using a variable that resolves to a valid email address. When placing an address in the from field, make sure that you use an address that the mail server will accept. Many mail servers process only those messages that come from addresses that are permitted to relay through their systems. If you have questions as to whether the address you're using is allowed to relay in this way, contact your mail administrator.
Cc	This is an optional attribute that enables you to specify a recipient that you'd like to have cc'd on the message.
Bcc	This is an optional attribute that enables you to specify a recipient that you'd like to have bcc'd (blind carbon copied) on the message. This user receives a copy of the message in its entirety, but the original recipient is not aware that this person was included.
Subject	This is a required attribute that specifies the subject of the email being sent. All or any part of the subject text can be generated dynamically through use of a variable.
Type	This is an optional attribute that enables you to distinguish between plain-text email and email that you want to be displayed as HTML in the recipients' mail clients. If you specify TYPE="HTML",any HTML tags you've placed in the content or body of the message are processed for display.
Maxrows	This is an optional attribute that enables you to specify the maximum number of emails that you want this instance of CFMAIL to generate. This is an especially useful attribute if your TO field is generated from a query result set, yet you want to email only to the first 50 or 100 users in the list.
MIMEattach	This is an optional attribute that enables you to specify a local file that you want to have Multipurpose Internet Mail Extension (MIME) encoded and attached to the email that you are sending.
Query	This is an optional attribute that enables you to specify the name of a query to use when you want to send multiple email messages or you want your message content to contain information drawn from the results of a previous query.
Group	This is an optional attribute that is used in conjunction with the QUERY attribute. It enables you to group messages by any specified field contained within the query.
Groupcasesensitive	By default, when using the GROUP attribute of CFMAIL, the grouping is always case-sensitive. If you want to ignore this case sensitivity in your grouping, you need to explicitly use this attribute by setting its value to No.
Startrow	This is another of the optional attributes that can be used when you are constructing email using the results of a query. This attribute enables you to specify at which row in the query result set you want to begin processing the query.
Server	This is a required attribute and should contain the IP address or host name of the mail server that you want to use to process your mail messages. If you omit this attribute, ColdFusion defaults to attempting to use the mail server that has been defined in the ColdFusion Administrator.
Port	This is an optional attribute that enables you to specify at which port your mail server is listening for incoming SMTP requests. Usually, this will be port 25 (which is the default), but you can change that default here if you have special environmental considerations.
Mailerid	This is an optional parameter that enables you to pass in a mailer ID that will be used in the header of your mail message. The default header that is passed in reads "ColdFusion Application Server"; however, you might want to change this depending on your specific application needs.
Timeout	This is an optional parameter that enables you to specify how long you want your CFMAIL routine to wait for a connection to the mail server you've specified before timing out. If you leave this attribute blank, ColdFusion defaults to using the value contained in the ColdFusion Administrator Mail Settings page.

Attaching Files to Your Messages

In many cases, rather than just sending a flat email to your users, you'll want to send them a file, such as a document or image, in response to their request. CFMAIL provides you with two ways in which you can accomplish this task. The first is through the use of the MIMEattach parameter of the CFMAIL tag itself. By using this parameter, you can specify the file that you want appended to the message that is being sent to the user:

 <cfmail from="[e-mail]"          to="#form.emailAddress#"          subject="Here is the file you requested."          MIMEattach="C:\Temp\file.jpg">  Hi,  Attached you will find the file that you requested when you visited my site.   Enjoy!  </cfmail> 

Although this method of attaching files will work just fine, it doesn't give much in the way of flexibility. For example, suppose you want to attach an image, but you want to have that image appear as part of the email. With the MIMEattach parameter of CFMAIL, this isn't possible. Luckily, there is another way in which you can attach files that does give you this flexibility:

 <cfmail from="[e-mail]"          to="#form.emailAddress#"          subject="Here is the file you requested.">  Hi,  Below you will see the file you requested when you visited my site.   Enjoy!  <cfmailparam file="C:\Temp\file.jpg">  </cfmail> 

The CFMAILPARAM tag enables you to attach either a file or additional header to an email message. For CFMAILPARAM to work, it must be nested within a CFMAIL tag as in the previous example. This is becoming the more common way to attach files with CFMAIL because of the increased flexibility in the way in which you can present the attachment to the recipient.

Table 11.2 gives you an overview of the CFMAILPARAM tag and its attributes.

Table 11.2. Attributes of the CFMAILPARAM Tag

Attribute	Description
File	There are two attributes that can be used with the CFMAILPARAM tag to tell it what you are attempting to do: file and name. If FILE is included, there is no need for name, and vice versa. However, one or the other is always required. Here, you would simply specify the path to the file that you want to attach to the message.
Name	This is a required attribute if you do not specify a FILE parameter. This enables you to name the header that you are going to insert.
Value	This is the value of the header that you want to insert. This attribute is used only when you were using CFMAILPARAM name= and not file.

Now that you have an understanding of how you can use CFMAIL to create and send email messages and attachments, we'll move our discussion to CFPOP, which enables you to use ColdFusion Server to retrieve and manage messages that already exist on a remote mail server.