Contents

cfmail

Description

Uses an SMTP server to send e-mail message(s), optionally containing query output.

Category

Other

Implemented

Usage Syntax

<cfmail  
	to="String"
	from="String"
	[cc="String"]
	[bcc="String"]
	subject="String"
	[type="String"]
	[maxRows="number"]
	[mimeattach="String"]
	[query="String"]
	[group="String"]
	[groupCaseSensitive="Boolean"]
	[startRow="number"]
	[server="String"]
	[port="number"]
	[mailerID="String"]
	[timeout="number"]
	[replyto="String"]
	[failto="String"]
	[username="String"]
	[password="String"]
	[wraptext="number"]
	[charset="String"]
	[spoolenable="Boolean"]
	[tls="Boolean"]
	[usetls="Boolean"]
	[priority="String"]
	[starttls="Boolean"]
	[ssl="Boolean"]
	[usessl="Boolean"]
	[secure="Boolean"]
	[proxyServer="String"]
	[proxyPort="number"]
	[proxyUser="String"]
	[proxyPassword="String"]
 />

[] = Optional attribute

The tag cfmail also allows arrays and structs as input for the email defintion. Check out the following example:

example: 

<cfset email=' "aaa bbb , ccc "'' dddd " <mic@streit.ch>'> <-- please note the quotes and the commas -->
<cfmail from="#{label:"abc",email:'mic@streit.ch'}#" to="#[{label:"Susi's Café",email:'michael@streit.ch'},email]#" subject="new (#server.ColdFusion.ProductName#)" spoolenable="no">
  special from
</cfmail>

This allows you to specify all different kind of sender addresses.

Attributes

Name Type Required Default Description
to String / Array / Struct Yes The name of the e-mail message recipient.
- string (to=' "aaa bbb , ccc " dddd " <mic@stre.it>')
- array of structs with keys "label" and "email" or string (to="#[{label:"Susi's Café",email:'michael@streit.ch'},email]#")
- structs with keys "label" and "email" (from="#{label:"abc",email:'mic@streit.ch'}#")
from String / Array / Struct Yes The sender of the e-mail message.
- string (to=' "aaa bbb , ccc " dddd " <mic@stre.it>')
- array of structs with keys "label" and "email" or string (to="#[{label:"Susi's Café",email:'michael@streit.ch'},email]#")
- structs with keys "label" and "email" (from="#{label:"abc",email:'mic@streit.ch'}#")
cc String / Array / Struct No Indicates addresses to copy the e-mail message to; "cc" stands for "carbon copy."
- string (to=' "aaa bbb , ccc " dddd " <mic@stre.it>')
- array of structs with keys "label" and "email" or string (to="#[{label:"Susi's Café",email:'michael@streit.ch'},email]#")
- structs with keys "label" and "email" (from="#{label:"abc",email:'mic@streit.ch'}#")
bcc String / Array / Struct No Indicates addresses to copy the e-mail message to, without listing them in the message header.
"bcc" stands for "blind carbon copy."
- string (to=' "aaa bbb , ccc " dddd " <mic@stre.it>')
- array of structs with keys "label" and "email" or string (to="#[{label:"Susi's Café",email:'michael@streit.ch'},email]#")
- structs with keys "label" and "email" (from="#{label:"abc",email:'mic@streit.ch'}#")
subject String Yes The subject of the mail message. This field may be driven dynamically on a message-by-message basis
type String No Specifies extended type attributes for the message.
maxRows number No Specifies the maximum number of e-mail messages to send.
mimeattach String No Specifies the path of the file to be attached to the e-mail message. An attached file is MIME-encoded.
query String No The name of the cfquery from which to draw data for message(s) to send. Specify this attribute to send more than one mail message, or to send the results of a query within a message.
group String No Specifies the query column to use when you group sets of records together to send as an e-mail message. For example, if you send a set of billing statements to customers, you might group on "Customer_ID." The group attribute, which is case sensitive, eliminates adjacent duplicates when the data is sorted by the specified field. See the Usage section for exceptions.
groupCaseSensitive Boolean No Boolean indicating whether to group with regard to case or not. The default value is YES; case is considered while grouping. If the query attribute specifies a query object that was generated by a case-insensitive SQL query, set the groupCaseSensitive attribute to NO to keep the recordset intact.
startRow number No Specifies the row in the query to start from.
server String No The address of the SMTP server to use for sending messages. If no server is specified, the server name specified in the ColdFusion Administrator is used.
port number No The TCP/IP port on which the SMTP server listens for requests. This is normally 25.
mailerID String No Specifies a mailer ID to be passed in the X-Mailer SMTP header, which identifies the mailer application. The default is ColdFusion Application Server.
timeout number No The number of seconds to wait before timing out the connection to the SMTP server.
replyto String No Address(es) to which the recipient is directed to send replies.
failto String No Address to which mailing systems should send delivery failure notifications. Sets the mail envelope reverse-path value.
username String No A user name to send to SMTP servers that require authentication. Requires a password attribute.
password String No A password to send to SMTP servers that require authentication. Requires a username attribute.
wraptext number No Specifies the maximum line length, in characters of the mail text. If a line has more than the specified number of characters, replaces the last white space character, such as a tab or space, preceding the specified position with a line break. If there are no white space characters, inserts a line break at the specified position. A common value for this attribute is 72.
charset String No Character encoding of the mail message
spoolenable Boolean No
tls Boolean No
usetls Boolean No alias for tls
priority String No
starttls Boolean No alias for tls
ssl Boolean No
usessl Boolean No alias for ssl
secure Boolean No alias for ssl
proxyServer String No Host name or IP address of a proxy server.
proxyPort number No The port number on the proxy server from which the object is requested. Default is 80. When used with resolveURL, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document.
proxyUser String No When required by a proxy server, a valid username.
proxyPassword String No When required by a proxy server, a valid password.

Example Usage

<---  Basic, plain text e-mail, with attachment: --->
<cfmail from="sender@host"
		to="recipient@host"
		subject="Hello"
		wraptext="72"
		mimeattach="#expandPath('images/logo.gif')#"
>This is the e-mail message body.</cfmail>

<---  HTML formatted e-mail: --->
<cfmail from="sender@host"
		to="recipient@host"
		cc="recipient2@host"
		bcc="recipient3@host"
		subject="Hello"
		type="html"
		charset="utf-8"
		priority="5"
>
	<h1>Hello!</h1>
	<p>This is an HTML e-mail message body.</p>
</cfmail>

<---  E-mails based on query output: --->
<cfmail query="myContacts"
		from="sender@host"
		subject="New Site"
		to="#myContacts.email# (#myContacts.firstName# #myContacts.lastName#)"
		type="html"
		group="companyName"
		groupcasesensitive="false"
		failto="bounces@host"
		mailerid="Acme Mail Sender"
		maxrows="500"
		replyto="replies@host"
		startrow="501"
>
	<p>Dear #myContacts.firstName#,</p>
	<p>Please visit our new site at <a href="http://localhost/">localhost</a></p>
</cfmail>

<---  No spooling, send immediately: --->
<cfmail from="sender@host"
		to="recipient@host"
		subject="Hello"
		type="html"
		spoolenable="false"
		timeout="25"
>
	<h1>Hello!</h1>
	<p>This is an HTML e-mail message body.</p>
</cfmail>

<---  Specify SMTP server: --->
<cfmail from="sender@host"
		to="recipient@host"
		subject="Hello"
		type="html"
		server="smtp.gmail.com"
		username="homer.simpson@gmail.com"
		password="doh!doh!"
		port="587"
		usetls="true"
>
	<h1>Hello!</h1>
	<p>This is an HTML e-mail message body.</p>
</cfmail>