Sending Email with ColdFusion
- 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.
| 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
---- Code Omitted ----<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>---- Code Omitted ----
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.
| 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
---- Code Omitted ----<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>---- Code Omitted ----
Exercise: Sending a Password by Email
In this exercise, you will create a Password Reminder page that allows users to have their passwords sent to them by email.
- Open Email/Exercises/PasswordReminder.cfm in your editor.
- Write code that looks for the user's password in the users table.
- 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.
- 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.
- You will need to specify a valid mail server.
- 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>
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 Email with ColdFusion Conclusion
In this lesson of the ColdFusion tutorial, you learned to administer and send email using ColdFusion.