facebook google plus twitter
Webucator's Free ColdFusion MX Tutorial

Lesson: Sending Email with ColdFusion

Welcome to our free ColdFusion MX tutorial. This tutorial is based on Webucator's Comprehensive ColdFusion Training course.

Lesson Goals

  • To configure email settings in ColdFusion Administrator.
  • To use <cfmail> to send confirmation emails and password reminders.
  • To send email as plain text or HTML.
  • To include email attachments.

Configuring Settings

Some of the mail server settings that can be set in ColdFusion Administrator are listed below. To modify these settings, open ColdFusion Administrator and click on the Mail menu.

Mail Server Settings

  • Mail Server - the default mail server
  • Verify Mail Server Connection - when checked, verifies that ColdFusion can connect to the mail server when the "Submit Changes" button is clicked.
  • Backup mail servers (Enterprise edition only) - a comma-delimited list of backup servers to try if the default mail server is inaccessible.
  • Maintain Connection to Mail Server (Enterprise edition only) - when checked, mail server connections are kept open after sending a mail message, which improves performance when delivering multiple messages.
  • Connection Timeout - the number of seconds to wait for a response from the mail server.
  • Server Port - usually 25.

Mail Spooling Settings

  • Spool Interval - number of seconds mail server waits to process spooled mail.
  • Mail Delivery Threads (Enterprise Edition only) - the maximum number of simultaneous threads used to deliver spooled mail.
  • Spool mail messages for delivery - when checked, mail messages are sent to the mail spooler for delivery. When unchecked, ColdFusion tries to deliver the message right away. Generally, you will want this checked.
  • Maximum number of messages spooled to memory (Enterprise Edition only) - the maximum number of messages ColdFusion MX should spool to memory before switching to disk spooling. Memory spooling is only available in the Enterprise Edition.

Mail Logging Settings

  • Error Log Severity - the severity of SMTP errors ColdFusion should log to the mail.log log.
  • Log all mail messages sent by ColdFusion - when checked, all messages are logged to the mailsent.log log (To, From, and Subject fields only).

Mail Character Set Settings

Default CFMail Charset - the character set used by the <cfmail> tag. UTF-8 for most languages.

Using <cfmail>

Emails are sent with the <cfmail> tag. The table below shows some of <cfmail>'s most common attributes.

<cfmail> Attributes
Attribute Description
to Required. Recipient email address.
from Required. Sender email address.
subject Required. Email subject.
cc Email addresses to be copied.
bcc Email addresses to be blind copied.
replyto Address to receive replies.
type HTML. If omitted, the email will be sent as plain text.
username SMTP username
password SMTP password
query Query to use when sending multiple emails.
server SMTP server address. Overrides setting in ColdFusion Administrator.
timeout Seconds to wait before timing out. Overrides setting in ColdFusion Administrator.

Here is an example of a simple <cfmail> tag.

Code Sample:

Email/Demos/SimpleMail.cfm
<cfmail to="ndunn@webucator.com" from="info@runnershome.com" subject="Hello There">Hello there!

Thanks for visiting.

Best regards,

RunnersHome</cfmail>

Expressions in pound signs within <cfmail> tags are evaluated. <cfoutput> tags are not required and will likely cause an error or undesired results. For this file to work, you must have a valid mail server set up in ColdFusion Administrator. Alternatively, you can configure the <cfmail> tag to select the server using the server, username, and password attributes. Your mail server may also require a valid from email.

Sending a Confirmation Email

The code sample below shows how to send a confirmation email with <cfmail>.

Code Sample:

Email/Demos/Register.cfm
---- C O D E   O M I T T E D ----
	<cfif FORM.password EQ FORM.password2>
		<cfquery name="emailcheck" datasource="#APPLICATION.datasource#">
			SELECT *
			FROM Users
			WHERE email='#FORM.email#'
		</cfquery>
		<cfif emailcheck.RecordCount EQ 0>
			<cfquery datasource="#APPLICATION.datasource#">
				INSERT INTO Users
				(firstname, lastname, email, password)
				VALUES ('#FORM.firstname#', '#FORM.lastname#', '#FORM.email#', '#FORM.password#')
			</cfquery>
			<cfset SESSION.firstname = FORM.firstname>
			<cfset SESSION.lastname = FORM.lastname>
			<cfset SESSION.userid = emailcheck.userid>
			<cfmail to="#FORM.email#" from="runners@runnershome.com"
									subject="Successful Registration">
				Congratulations!  You have successfully registered for Runners Home!
			</cfmail>
			Thanks for registering!
		<cfelse>
			<p>It appears you have already registered.</p>
		</cfif>
	<cfelse>
		<p class="errors"><b>Your passwords
		do not match. Please <a href=
		"Register.cfm">try again</a>.</p>
	</cfif>
---- C O D E   O M I T T E D ----

Sending Email as HTML

Email can be sent in plain text format or in HTML format. The default is plain text format. Setting the type attribute of the <cfmail> tag can be set to "html" (only possible value) indicates that the message is in HTML format. You can then use HTML tags within the body of the message. HTML-enabled email clients will render the message as an HTML page.

Using <cfmailpart>

Of course, you do not always know what type of email client the mail recipient will have. By nesting <cfmailpart> tags within <cfmail>, you can provide alternative email messages in plain text and HTML format.

<cfmailpart> Attributes
Attribute Description
type Required. Options are text, plain, and html. text and plain both specify text/plain format. html specifies HTML format.
wraptext Used for plain text emails to specify the number of characters per line. If omitted, text will not wrap.
charset Character encoding.

Code Sample:

Email/Demos/Register-2.cfm
---- C O D E   O M I T T E D ----

			<cfmail to="#FORM.email#" from="runners@runnershome.com"
						subject="Successful Registration">
			
			<cfmailpart type="text" wraptext="72">
				Congratulations!  You have successfully registered for Runners Home!
			</cfmailpart>
			
			<cfmailpart type="html">
				<b>Congratulations!</b>  You have successfully registered for Runners Home!<br> <img src="http://www.astroleague.org/al/regional/congrats-fireworks.gif">
			</cfmailpart>
			</cfmail>
---- C O D E   O M I T T E D ----

Attaching Files

Files can be attached using the <cfmailparam> tag. The syntax is as follows:

<cfmailparam file = "#ExpandPath("Logs/RunningLog.txt")#" type="image/gif">

There is no limit to the number of <cfmailparam> tags that can be included within a <cfmail> tag.

Sending a Password by Email

Duration: 15 to 25 minutes.

In this exercise, you will create a Password Reminder page that allows users to have their passwords sent to them by email.

  1. Open Email/Exercises/PasswordReminder.cfm in your editor.
  2. Write code that looks for the user's password in the users table.
  3. If the password is found, email it to the user and return an appropriate message to the browser. Send the message in both HTML and plain text format.
  4. If the password is not found (i.e, there is no such email address in the users table), return a message saying no such user exists.
  5. You will need to specify a valid mail server.
  6. When you are done, try it out in your browser.

Code Sample:

Email/Exercises/PasswordReminder.cfm
<cfparam name="FORM.email" default="">
<html>
<head>
<title>Password Reminder</title>
</head>
<body>

<cfif NOT isDefined("FORM.submitted")>
	<h2>Password Reminder</h2>
	<cfoutput>
	<form method="post" action="#CGI.SCRIPT_NAME#">
	</cfoutput>
	<input type="hidden" name="submitted" value="true">
	<table>
	<tr>
		<td>Email:</td>
		<td>
		<input type="text" name="email"
							value="<cfoutput>#FORM.Email#</cfoutput>" size="30">
		</td>
	</tr>
	<tr>
		<td colspan="2" align="right">
			<input type="submit" value="Remind Me">
		</td>
	</tr>
	</table>
	</form>
<cfelse>
	<!---
	Write code that looks for the user's password
	in the Users table. If the password is found, 
	email it to the user.
	If the password is not found (i.e, there is
	no such email address in the Users table),
	return a message saying no such user exists.
	--->
</cfif>

</body>
</html>

Solution:

Email/Solutions/PasswordReminder.cfm
---- C O D E   O M I T T E D ----
<cfelse>
	<cfquery name="pwcheck" datasource="#APPLICATION.datasource#">
		SELECT password
		FROM Users
		WHERE email='#FORM.email#'
	</cfquery>
	<cfif pwcheck.RecordCount EQ 1>
		<cfmail to="#FORM.email#" from="info@RunnersHome.com" subject="Password Reminder">
			<cfmailpart type="html">
			Your password is: <b>#pwcheck.password#</b>
			</cfmailpart>
			<cfmailpart type="text">
			Your password is: #pwcheck.password#
			</cfmailpart>			
		</cfmail>
		<p>Your password has been sent.</p>
	<cfelse>
		<p>Email address not found.</p>
		<p><a href="Register.cfm">Register now.</a></p>
	</cfif>
---- C O D E   O M I T T E D ----