Sending E-Mails | ColdFusion MX Professional Projects

You can integrate the e-mail application through the <cfmail> and <cfpop> tags. The application with the <cfmail> tag generates e-mail messages based on the settings of the tag. You can send simple or HTML formatted e-mails, form contents, query results, and file attachments, and you can create an application to manage undelivered mail messages.

Sending a Simple E-Mail

You can use the <cfmail> tag to send an e-mail message. Table 27.1 describes the attributes of the <cfmail> tag. Because the text in the <cfmail> tag is treated as though it were in a <cfoutput> tag, there's no need to include <cfoutput> in the <cfmail> tag.

Table 27.1: The <cfmail> Tag Attributes
Attribute	Description	Optional?
To	Accepts a single recipient address or a comma-separated list of recipients.	No
From	Displays the e-mail address of the sender.	No
Cc	Accepts the list of recipient addresses to which a carbon copy of the message has to be sent.	Yes
Bcc	Same as Cc, except the recipient address doesn't appear in the message header.	Yes
Subject	Displays the subject of the message.	Yes
Type	Specifies whether an HTML-formatted message or plain text is being sent.	Yes
Maxrows	Limits the number of e-mails being sent.	Yes
Server	Specifies the SMTP server to be used for sending the e-mail. It overrides the value specified in the ColdFusion Administrator page.	Yes
Port	Specifies the TCP/IP port used by the SMTP server to send the e-mail. The default value is 25.	Yes
Timeout	Specifies how long ColdFusion waits before a mail server connection fails. This value is in seconds. It overrides the timeout interval set in ColdFusion Administrator.	Yes
Mailerid	Identifies the application that has sent the e-mail. The default Mailerid for ColdFusion is ColdFusion Application Server. This Mailerid appears in the x-mailer line of the message.	Yes
SpoolEnable	Saves a copy of the message until the sending operation is completed.	Yes
Query	Specifies the query from which the text for the message will be taken.	Yes
Group	Specifies the column of a query result to be grouped.	Yes
Groupcasesensitive	Is used along with the Group attribute. It indicates whether the grouped column should be treated as case-sensitive or not. The default value for this attribute is yes.	Yes
Startrow	Specifies the first row of the query result to be accessed.	Yes

The following code sends a simple e-mail to the address specified in the To attribute. The subject of the message and the address of the sender are specified in the Subject and From attributes, respectively. You can save this template under the wwwroot directory of inetpub, as follows: C:\inetpub\wwwroot\sendmail.cfm.

 <HTML> <HEAD> <TITLE>Sending Mail Example -- sendmail.cfm Template</TITLE> <HEAD> <BODY BGCOLOR="Yellow ">     <H3>Click the Send button to send mail.</H3>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\sendmail.cfm">       <INPUT TYPE="Submit" VALUE="Send">     </FORM>     <CFMAIL TO="Gary@yahoo.com" SUBJECT="Test Mail" FROM="Tina@hotmail.com">       This is a test mail. Please acknowledge its receipt.     </CFMAIL> </BODY> </HTML>

You can use the other attributes to send a copy and a blank copy of the e-mail, as in the following example. You can specify the SMTP server to override the server set in ColdFusion Administrator:

 <!--- sendmail_2.cfm template --- > <HTML> <HEAD> <TITLE>Sending Mail Example -- sendmail_2.cfm Template</TITLE> <HEAD> <BODY BGCOLOR="Yellow ">     <H3>Click the Send button to send mail.</H3>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\sendmail_2.cfm">       <INPUT TYPE="Submit" VALUE="Send">     </FORM>     <CFMAIL TO="Gary@yahoo.com" SUBJECT="Test Mail" FROM=Tina@hotmail.com              CC="Jack@yahoo.com" BCC="John@usa.net" SERVER="127.0.04"              PORT="25" TIMEOUT="120">          This is a test mail using more attributes. Please acknowledge its          receipt. The SMTP server through which the mail is sent is 127.0.04          in this example.      </CFMAIL> </BODY> </HTML>

Sending E-Mail Using HTML Tags

You can send HTML-formatted text to the recipients using the Type attribute of the <cfmail> tag. To view the HTML-formatted message correctly, the recipient needs to have an HTML-enabled e-mail reader, such as Microsoft Outlook or Netscape Navigator. You can use only one value with the Type attribute of the <cfmail> tag. When this value is set to HTML, an entry is made in the header of the e-mail to tell the e-mail client that the incoming message is formatted using HTML. The following code embeds HTML-formatted text in the e-mail body:

 <HTML> <HEAD> <TITLE> Sending Mail Using HTML Text Example -- sendhtmlmail.cfm Template </TITLE> <HEAD> <BODY BGCOLOR="Yellow ">     <H3>Click the Send button to send mail.</H3>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\sendmail.cfm">       <INPUT TYPE="Submit" VALUE="Send">     </FORM>     <CFMAIL TO="Gary@yahoo.com" SUBJECT="Test Mail"              FROM="Tina@hotmail.com" TYPE="HTML">          <H2><CENTER> HTML formatted Mail </CENTER></H2>          <br>          <br>          This is a test mail supporting <B>HTML</B> format. <P> Please          acknowledge its receipt.          <HR>          <Ul>            <LI> Sender is Tina.            <LI> Receiver is Gary.            <LI> Subject is Test Mail.          </UL>     </CFMAIL> </BODY> </HTML>

Sending E-Mail Using Forms

You can create a dynamic Web application by using forms. The data filled out in forms can be used for sending e-mails. For example, you can send the feedback of a Web site to the authorities. The following code samples accept the user feedback and then send it to the Web site manager.

The sample code to accept user feedback is as follows:

 <!--- Code Listing for feedback.cfm Template --- > <HTML> <HEAD> <TITLE> Mailing Form Contents Example </TITLE> </HEAD> <BODY BGCOLOR="yellow">      <H1> Feedback Form </H1>      <HR>      <P>      <FORM METHOD = "Post" ACTION = "sendfeedback.cfm">        <TABLE BORDER="0" CELLPADDING="5">          <TR>            <TD>              <B>How would you rate the Web site's presentation? </B>            </TD>            <TD>              <SELECT NAME = "presentation">                <OPTION VALUE = "A" SELECTED> Very good(A) </OPTION>                <OPTION VALUE = "B"> Good (B) </OPTION>                <OPTION VALUE = "C"> Satisfactory (C) </OPTION>              </SELECT>            </TD>            </TR>          <TR>            <TD>              <B> How would you rate the Web site's information? </B>            </TD>            <TD>              <SELECT NAME = "presentation">                <OPTION VALUE = "A" SELECTED> Very good(A) </OPTION>                <OPTION VALUE = "B"> Good (B) </OPTION>                <OPTION VALUE = "C"> Satisfactory (C) </OPTION>              </SELECT>            </TD>          </TR>          <TR>           <TD>             <B>How would you rate the Web site overall? </B>           </TD>           <TD>             <SELECT NAME = "presentation">               <OPTION VALUE = "A"SELECTED >Very good(A) </OPTION>               <OPTION VALUE = "B"> Good (B) </OPTION>               <OPTION VALUE = "C"> Satisfactory (C) </OPTION>             </SELECT>           </TD>         </TR>         <TR>           <TD>             <B> Please send your remarks. </B>           </TD>           <TD>             <INPUT TYPE="Text" NAME=" remarks" size="120">           </TD>         </TR>         <TR>           <TD>             <B> Name </B>           </TD>           <TD>             <INPUT TYPE="Text" NAME="username" size="20">           </TD>         </TR>         <TR>           <TD></TD>           <TD>             <INPUT TYPE = "submit" VALUE = "send">           </TD>         </TR>       </TABLE>     </FORM> </BODY> </HTML>

The output of the template is shown in Figure 27.4.

click to expand
Figure 27.4: The output of the feedback.cfm template.

The sample code to send the feedback to the Web site manager is as follows:

 <!--- sendfeedback.cfm template --- > <HTML> <HEAD> <TITLE>Sending the Feedback Details </TITLE> </HEAD> <BODY>     <CFMAIL To = "webmanager@jsmartin.com" From = "#form.username#"              SUBJECT = "feedback from #form.username">        Your registration form has been accepted. Welcome to our newsgroup. </CFMAIL> <!--- You can take the user to the home page from here. Since it is an example, I am taking you back to the feedback form. --- >     <CFLOCATION URL="c:\inetpub\wwwroot\article\feedback.cfm"> </BODY> </HTML>

Sending Query-Based E-Mail

You can include query results in the text of the e-mail. Suppose you need to send a list of students enrolled in the tenth grade to the principal. In this case, you can use a query to generate the required list on the student table. The result can be sent via e-mail to the principal. The code to achieve the same result is in the studentquery.cfm template. Before running this example, you need to create the student database.

 <!--- studentquery.cfm template ---> <HTML> <HEAD> <TITLE> Mailing Query Results -- Example</TITLE> </HEAD> <BODY BGCOLOR="BLUE">     <CFQUERY NAME = "studentlist" DATABASE = "student">       Select * from student where grade = "10" order by firstname     </CFQUERY>     <CFMAIL QUERY = "studentlist" TO = "principal@univeristy.org"              FROM= "trcoordinator@univerity.org"              SUBJECT = "List of 10th Grade students"              TIMEOUT = "950" TYPE = "HTML">       <H1>Student List</H1>       <P>       <TABLE>         <TR>           <TH> Firstname </TH>           <TH> Lastname </TH>           <TH> Grade </TH>           <TH> City </TH>           <TH> Phone Number </TH>         </TR>         <CFOUTPUT>          <TR>            <TD> #firtsname# </TD>            <TD> #Lastname# </TD>            <TD> #grade# </TD>            <TD> #city# </TD>            <TD> #phoneno# </TD>          </TR>         </CFOUTPUT>        </TABLE>      </CFMAIL>      <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\studentquery.cfm">        <TABLE BORDER=0 CELLPADDING=5">          <TR>            <TD>              <H2>Click the Send button to send mail. </H2>            </TD>          </TR>          <TR>            <TD>              <INPUT TYPE="submit" VALUE="Send">            </TD>          </TR>        </TABLE>      </FORM> </BODY> </HTML>

In the preceding example, the Query attribute specifies the results accessible to the <cfmail> tag. The result of the query may generate a single row or multiple rows. To iterate through all the rows and display them to the recipient, you can use the <cfoutput> tag.

Grouping the Query Results

You can group the query results that are being sent by e-mail. For example, if the principal needs a city-wide list of the tenth grade students, you need to change the code accordingly:

 <!--- studentquery_2.cfm template ---> <HTML> <HEAD> <TITLE> Mailing Grouped Query Results -- Example </TITLE> </HEAD> <BODY BGCOLOR="BLUE">     <CFQUERY NAME = "studentlist" DATABASE = "student">       Select * from student where grade = "10" order by city     </CFQUERY>     < ! --- Initialize a variable with space --- >     <CFSET X = "    ">     <! --- for each query record group the output and append it to X--->     <CFOUTPUT QUERY = "studentlist" GROUP = "City">       <CFSET X = X&"# deptname # **********">       <CFOUTPUT>       <CFSET X = X&"             # firstname #             # lastname #             # grade #             # phoneno #">       </CFOUTPUT>     </CFOUTPUT>     <CFMAIL QUERY = "studentlist" TO = "principal@univeristy.org"              FROM= "trcoordinator@univerity.org"              SUBJECT = "Area-wide List of 10th Grade Students" TIMEOUT = "950"              TYPE = "HTML">       <H2>Area-wide List of 10th Grade Students</H2>       <HR>       #X#     </CFMAIL>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\studentquery_2.cfm">       <TABLE BORDER=0 CELLPADDING=5">         <TR>           <TD>             <H2>Click the Send button to send mail. </H2>           </TD>         </TR>         <TR>           <TD>             <INPUT TYPE="submit" VALUE="Send">           </TD>         </TR>       </TABLE>     </FORM> </BODY> </HTML>

In the preceding code, the query result of the student table is stored in the studentlist query object. A variable X is initialized with a space. The query result data is appended to it by using the <cfoutput> tags. There are two loops. The first starts with the outermost <cfoutput> tag, and the second starts with the inner <cfoutput> tag. The first loop iterates for each unique value contained in the column specified in the Group attribute of the <cfoutput> tag, which is city. The inner loop iterates for each employee in the current group. The grouped results are appended to the X variable. The <cfmail> tag sends the data to the principal.

If the Group attribute is used in the <cfmail> tag instead of the <cfoutput> tag, the entire output of the code changes. The following code explains this point:

 <!--- studentquery_3.cfm template ---> <HTML> <HEAD> <TITLE> Mailing Grouped Query Results -- Example 2 Shows the Incorrect Result </TITLE> </HEAD> <BODY BGCOLOR="BLUE">     <CFQUERY NAME = "studentlist" DATABASE = "student">       Select * from student where grade = "10" order by city     </CFQUERY>     <CFMAIL QUERY = "studentlist" GROUP="city"              TO = "principal@univeristy.org"              FROM= "trcoordinator@univerity.org"              SUBJECT = "Area-wise List of 10th Grade Students"              TIMEOUT = "950" TYPE = "HTML">       <H2> #city# </H2>       <HR>       <CFOUTPUT>         #firstname#         #lastname#         #grade#         #phoneno#       </CFOUTPUT>     </CFMAIL>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\studentquery_2.cfm">       <TABLE BORDER=0 CELLPADDING=5">         <TR>           <TD>             <H2>Click the Send button to send mail. </H2>           </TD>         </TR>         <TR>           <TD>             <INPUT TYPE="submit" VALUE="Send">           </TD>         </TR>       </TABLE>     </FORM> </BODY> </HTML>

In the preceding example, the <cfmail> tag generates a separate message for each group of data in the query. The principal receives different e-mails for each city group, instead of getting a single e-mail with grouped city results. Therefore, you should group the data in the <cfoutput> tag and not in the <cfmail> tag to get the correct results.

You can use the Groupcasesensitive attribute in the preceding example. If this attribute is set to TRUE, "Shelton" and "SHELTON" are considered to be two different cities.

Sending an E-Mail to Multiple Recipients

The following code shows how you can send an e-mail message to multiple recipients using a comma-delimited list of addresses in the To attribute of the <cfmail> tag:

 <!--- sendmultiplemail.cfm template ---> <HTML> <HEAD> <TITLE>Sending Mail to Multiple Recipients Example</TITLE> <HEAD> <BODY BGCOLOR="Yellow">     <H3>Click the Send button to send mail.</H3>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\sendmultiplemail.cfm">       <INPUT TYPE="Submit" VALUE="Send">     </FORM>     <CFMAIL TO="Gary@yahoo.com, Anne@usa.net, Adi@jsmartin.com,                  devzjob@hotmail.com"              SUBJECT="Multiple recipient test mail"              FROM="Tina@hotmail.com">        This is a test mail with multiple recipients. Please acknowledge its        receipt.      </CFMAIL> </BODY> </HTML>

Caution

To send e-mails successfully, you need to use valid e-mail IDs.

Generating a Recipient List Dynamically

The second way to send e-mail to multiple recipients is by using a query. You can generate a list of recipients using query results. The following example demonstrates the use of the query result in the To attribute of the <cfmail> tag. In the following example, the training coordinator informs all the students to attend a seminar on Internet protocols:

 <!--- seminar.cfm template --- > <HTML> <HEAD> <TITLE>Recipient List Through Query Result -- Example </TITLE> </HEAD> <BODY>     <CFQUERY NAME = "studentlist" DATASOURCE = "student" >       Select firstname, emailid from student order by firstname     </CFQUERY>     <CFMAIL TO = "#emailid#" FROM = "trainingcoordinator@devuniverisity.org"             SUBJECT = "Seminar on Internet Protocol" QUERY = "studentlist">       There is a seminar on Internet Protocols on December 15 in Hall Number 2.       Those who wish to attend should enroll at the reception desk by December 11.     </CFMAIL> </BODY> </HTML>

The e-mail reaches all the students whose e-mail IDs are available in the emailid column of the student table. For each row of the student table, a separate e-mail is generated.

You can use the maxrow, startrow, group, and groupcasesensitive attributes along with the query attribute in the <cfmail> tag. You can limit the number of rows to process for query results by using the Maxrows attribute. For example, if Maxrows is set to 25 and there are 50 students, only 25 e-mails will be generated.

You can use the Startrow attribute to specify the row from which the program should start processing. For example, if the total number of students is 50, set the startrow value to 20 to send the e-mail to the last 30 students.

Inserting Attachments

You can insert attachments or add a custom header to the e-mail message using the <cfmailparam> tag in the <cfmail> tag. You can insert multiple files. For each file to be added, you need to use a separate <cfmailparam> tag. Use the File attribute to specify the path of the file to be inserted. You can insert only those files that are located on the local ColdFusion server, or on a network drive accessible from that server. You need to upload the file to the ColdFusion server using the <cffile> tag before inserting it as an attachment. The code to send an e-mail message with an attachment is as follows:

 <!--- Sendattachment.cfm template ---> <HTML> <HEAD> <TITLE>Sending Mail with an Attachment -- Example </TITLE> <HEAD> <BODY BGCOLOR="Yellow">     <H3>Click the Send button to send mail.</H3>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\sendattachment.cfm">       <INPUT TYPE="Submit" VALUE="Send">     </FORM>     <CFMAIL TO=Gary@yahoo.com              SUBJECT="Test Mail with attachment" FROM="Tina@hotmail.com">       <CFMAILPARAM FILE="c:\data\first.doc">       <CFMAILPARAM FILE="c:\data\second.txt">       <CFMAILPARAM FILE="c:\data\third.doc">       This is a test mail having three attachments. Please acknowledge its       receipt.     </CFMAIL> </BODY> </HTML>

You can use the Name and Value attributes of the <cfmailparam> tag to add headers to the e-mail:

 <!--- Sendattachment_2.cfm template ---> <HTML> <HEAD> <TITLE>Sending Mail with an Attachment -- Example </TITLE> <HEAD> <BODY BGCOLOR="Yellow">     <H3>Click the Send button to send mail.</H3>     <FORM METHOD="Post" ACTION="c:\inetpub\wwwroot\sendattachment_2.cfm">       <INPUT TYPE="Submit" VALUE="Send">     </FORM>     <CFMAIL TO=Gary@yahoo.com              SUBJECT="Test Mail with attachment" FROM="Tina@hotmail.com">       <CFMAILPARAM FILE="c:\data\first.doc">       <CFMAILPARAM FILE="c:\data\second.txt">       <CFMAILPARAM NAME="Reply TO" VALUE="ria@devzjob.com">       Dear Gary,         This is a test mail having two attachments. Please acknowledge its         receipt.       Regards       Tina     </CFMAIL> </BODY> </HTML>

Undelivered E-Mails

The SMTP mail server of ColdFusion uses a spooled architecture, which means that the pages requesting an e-mail message aren't processed immediately but are sent to the background. ColdFusion isn't designed to handle hundreds of e-mails because it uses an SMTP server to do the job. This SMTP server may not receive the request for processing because of the following reasons:

Poor or non-existent network connection
E-mail server going offline
Missing e-mail address in the To attribute
Incorrect e-mail address
Invalid SMTP server specified in the Server attribute

The unprocessed e-mails reside on the ColdFusion server under the ColdFusion installation directory, mail\undelivr\. The program also creates an entry in the mail.log file, along with the diagnostic information about the cause of the error.

The exact location of the undelivr folder can be found from the following system registry: HKEY_LOCAL_MACHINE/Software/Allaire/ColdFusion/Current Version/Mail/Base Directory. You can resend undelivered messages by moving the temporary files back to the spool folder, located in the following path: C:\cfusion\mail\spool.

You can move the files to the spool either manually or by creating a timed application, which checks the undelivr folder at the scheduled intervals and moves the files back to the spool folder.