User Guide Cancel

cfmail

Last updated on Aug 1, 2024 | Also applies to ColdFusion

ColdFusion

Open app

CFML Reference User Guide
ColdFusion functions
ColdFusion Tags
1. ColdFusion tag summary
2. ColdFusion tags by category
  1. Application framework tags
    1. cfapplication
    2. cfassociate
    3. cferror
    4. cfimport
    5. cfinterface
    6. cflock
    7. cfscript
    8. cfthread
  2. Communications tags
  3. Database manipulation tags
  4. Data output tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcol
    5. cfcontent
    6. cfdocument
    7. cfdocumentitem
    8. cfdocumentsection
    9. cfflush
    10. cfheader
    11. cflog
    12. cfoutput
    13. cfpresentation
    14. cfpresentationslide
    15. cfpresenter
    16. cfprocessingdirective
    17. cfprint
    18. cfreport
    19. cfreportparam
    20. cfsilent
    21. cftable
  5. Debugging tags
    1. cfdump
    2. cftimer
    3. cftrace
  6. Exception handling tags
    1. cfcatch
    2. cferror
    3. cffinally
    4. cfrethrow
    5. cfthrow
    6. cftry
  7. Extensibility tags
    1. cfchart
    2. cfchartdata
    3. cfchartseries
    4. cfcollection
    5. cfcomponent
    6. cfexecute
    7. cfftp
    8. function
    9. cfindex
    10. cfinterface
    11. cfinvoke
    12. cfinvokeargument
    13. cfobject
    14. cfproperty
    15. cfreport
    16. cfreportparam
    17. cfreturn
    18. cfsearch
    19. cfsharepoint
    20. cfspreadsheet
    21. cfwddx
    22. cfxml
  8. File management tags
    1. cfdirectory
    2. cffile
    3. cffileupload
    4. cfftp
    5. cfzip
    6. cfzipparam
  9. Flow-control tags
    1. cfabort
    2. cfbreak
    3. cfcase
    4. cfcontinue
    5. cfdefaultcase
    6. cfelse
    7. cfelseif
    8. cfexecute
    9. cfexit
    10. cfif
    11. cfinclude
    12. cflocation
    13. cfloop
    14. cfrethrow
    15. cfswitch
    16. cfthrow
    17. cftry
  10. Forms tags
    1. cfapplet
    2. cfcalendar
    3. cffileupload
    4. cfform
    5. cfformgroup
    6. cfformitem
    7. cfgrid
    8. cfgridcolumn
    9. cfgridrow
    10. cfgridupdate
    11. cfinput
    12. cfpdf
    13. cfpdfform
    14. cfpdfformparam
    15. cfpdfparam
    16. cfpdfsubform
    17. cfselect
    18. cfslider
    19. cftextarea
    20. cftree
    21. cftreeitem
  11. Internet Protocol tags
    1. cfajaximport
    2. cfajaxproxy
    3. cfftp
    4. cffeed
    5. cfimap
    6. cfhttp
    7. cfhttpparam
    8. cfldap
    9. cfmail
    10. cfmailparam
    11. cfmailpart
    12. cfpop
    13. cfsprydataset
  12. Page processing tags
    1. cfcache
    2. cfcontent
    3. cfflush
    4. cfheader
    5. cfhtmlhead
    6. cfinclude
    7. cfprocessingdirective
    8. cfsetting
    9. cfsilent
  13. Security tags
  14. Variable manipulation tags
    1. cfcookie
    2. cfdump
    3. cfparam
    4. cfregistry
    5. cfsavecontent
    6. cfschedule
    7. cfset
    8. cfsetting
  15. Other tags
    1. cfimage
    2. cflog
    3. cfregistry
3. Tags a-b
4. Tags c
  1. cfcache
  2. cfcalendar
  3. cfcase
  4. cfcatch
  5. cfchart
  6. cfchartdata
  7. cfchartseries
  8. cfclient
  9. cfclientsettings
  10. cfcol
  11. cfcollection
  12. cfcomponent
  13. cfcontent
  14. cfcontinue
  15. cfcookie
  16. Tags d-e
5. Tags f
6. Tags g-h
  1. cfgraph
  2. cfgraphdata
  3. cfgrid
  4. cfgridcolumn
  5. cfgridrow
  6. cfgridupdate
  7. cfheader
  8. cfhtmlhead
  9. cfhtmltopdf
  10. cfhtmltopdfitem
  11. cfhttp
  12. cfhttpparam
7. Tags i
  1. cfif
  2. cfimage
  3. cfimap
  4. cfimapfilter
  5. cfimpersonate
  6. cfimport
  7. cfinclude
  8. cfindex
  9. cfinput
  10. cfinsert
  11. cfinterface
  12. cfinvoke
  13. cfinvokeargument
8. Tags j-l
9. Tags m-o
10. Tags p-q
  1. cfparam
  2. cfpdf
  3. cfpdfform
  4. cfpdfformparam
  5. cfpdfparam
  6. cfpdfsubform
  7. cfpod
  8. cfpop
  9. cfpresentation
  10. cfpresentationslide
  11. cfpresenter
  12. cfprint
  13. cfprocessingdirective
  14. cfprocparam
  15. cfprocresult
  16. cfprogressbar
  17. cfproperty
  18. cfquery
  19. cfqueryparam
11. Tags r-s
  1. cfregistry
  2. cfreport
  3. cfreportparam
  4. cfrethrow
  5. cfreturn
  6. cfsavecontent
  7. cfschedule
  8. cfscript
  9. cfsearch
  10. cfselect
  11. cfservlet
  12. cfservletparam
  13. cfset
  14. cfsetting
  15. cfsharepoint
  16. cfsilent
  17. cfslider
  18. cfspreadsheet
  19. cfsprydataset
  20. cfstoredproc
  21. cfswitch
12. Tags t
  1. cftable
  2. cftextarea
  3. cftextinput
  4. cfthread
  5. cfthrow
  6. cftimer
  7. cftooltip
  8. cftrace
  9. cftransaction
  10. cftree
  11. cftreeitem
  12. cftry
13. Tags u-z
  1. cfupdate
  2. cfwddx
  3. cfwebsocket
  4. cfwindow
  5. cfxml
  6. cfzip
  7. cfzipparam
CFML Reference
1. Reserved words and variables
2. Ajax JavaScript functions
3. ColdFusion ActionScript functions
4. ColdFusion mobile functions
5. Application.cfc reference
6. Script functions implemented as CFCs
7. ColdFusion Flash Form style reference
8. ColdFusion event gateway reference
9. ColdFusion C++ CFX Reference
10. ColdFusion Java CFX reference
11. WDDX JavaScript Objects
Cloud services

Description

Sends an e-mail message that optionally contains query output, using an SMTP server.

Syntax

<cfmail 
from = "e-mail address" 
to = "comma-delimited list" 
bcc = "comma-delimited list" 
cc = "comma-delimited list" 
charset = "character encoding" 
debug = "yes|no" 
failto = "e-mail address" 
group = "query column" 
groupcasesensitive = "yes|no" 
idnaversion="IDNA encoding"
mailerid = "header id" 
maxrows = "integer" 
mimeattach = "path" 
password = "string" 
port = "integer" 
priority = "integer or string priority level" 
query = "query name" 
remove = "yes|no" 
replyto = "e-mail address" 
server = "SMTP server address" 
spoolenable = "yes|no" 
startrow = "query row number" 
subject = "string" 
timeout = "number of seconds" 
type = "mime type" 
username = "SMTP user ID" 
useSSL = "yes|no" 
useTLS = "yes|no" 
wraptext = "column number" 
sign = "true|false" 
keystore = "location of keystore" 
keystorepassword = "password of keystore" 
keyalias = "alias of key" 
keypassword = "password for private key"
encrypt "true|false"
recipientcert = <path to the public key cert>
encryptionalgorithm = "DES_EDE3_CBC, RC2_CBC, AES128_CBC, AES192_CBC, AES256_CBC"> 

(Optional) Mail message body and/or cfmailparam tags 

</cfmail>

Note:

You can specify this tag's attributes in an attributeCollection attribute whose value is a structure. Specify the structure name in the attributeCollection attribute and use the tag's attribute names as structure keys.

History

ColdFusion (2018 release): Added the attribute idnaversion.

ColdFusion 11: Added the attributes, encrypt, recipientcert , and encryptionalgorithm .

ColdFusion 8.0.1: Added the attribute Remove.

ColdFusion 8: Added priority, useSSL, and useTLS attributes.

ColdFusion MX 7:

The cfmail tag no longer lets you send multipart mail by embedding the entire MIME-encoded message in the tag body. Use the cfmailpart tag, instead.
The cfmail tag renders non-proportional fonts proportionately. This is a behavior change from ColdFusion 5. ColdFusion MX 7 uses UTF-8 and sends this in the mail header (Content-Type: text/plain; charset=UTF-8). ColdFusion 5 uses ISO-8859-1 (Latin 1). To avoid this behavior, add the charset= " ISO-8859-1" attribute to restore the default ColdFusion 5 encoding. Alternatively, you can change the encoding on the Mail page in the ColdFusion Administrator.
ColdFusion MX 6.1:
Added the following attributes: charset, failto , replyto , username, password and wraptext .
Added support for multiple mail servers in the server attribute.
Added several configuration options to the ColdFusion Administrator Mail Settings page.
ColdFusion MX: Added the SpoolEnable attribute.ColdFusion 9: Added support for digitally signing the mail. The following are the relevant attributes that are newly added: sign, keystore , keystorepassword , keyalias , keypassword and remove.

Attributes

Attribute	Req/Opt	Default	Description
bcc	Optional		Addresses to which to copy the message, without listing them in the message header. To specify multiple addresses, separate the addresses with commas.
cc	Optional		Addresses to which to copy the message. To specify multiple addresses, separate the address with commas.
charset	Optional	Character encoding selected in ColdFusion Administrator Mail page; utf-8	Character encoding of the mail message, including the headers. The following list includes commonly used values: utf-8 iso-8859-1 windows-1252 us-ascii shift_jis iso-2022-jp euc-jp euc-kr big5 hz-gb-2312 euc-cn utf-16 For more information on character encodings, see www.w3.org/International/O-charset.html.
debug	Optional	no	yes: sends debugging output to standard output. By default, if the console window is unavailable, ColdFusion sends output to cf_root\runtime\logs\coldfusion-out.log on server configurations. no: does not generate debugging output.
failto	Optional		Address to which mailing systems must send delivery failure notifications. Sets the mail envelope reverse-path value.
from	Required		E-mail message sender: A static string; for example, "support@mex.com" A variable; for example, "#GetUser.EMailAddress#". This attribute does not have to be a valid Internet address; it can be any text string without white spaces.
to	Required		Message recipient e-mail addresses: Static address, for example, "support@.com". Variable that contains an address, for example, "#Form.Email#". Name of a query column that contains an address, for example, "#EMail#". An e-mail message is sent for each returned row. To specify multiple addresses, separate the addresses with commas.
subject	Required		Message subject. Can be dynamically generated. For example, to send messages that give customers status updates: "Status of Order Number #Order_ID#".
group	Optional	CurrentRow	Query column to use when you group sets of records to send as a message. For example, to send a set of billing statements to a customer, group on "Customer_ID." Case-sensitive. Eliminates adjacent duplicates when data is sorted by the specified field.
groupcasesensitive	Optional	No	Boolean. Whether to consider case when using the group attribute. To group on case-sensitive records, set this attribute to Yes.
idnaversion	Optional	2008	Choose the IDNA encoding to be applied. If no IDNAversion attribute is specified, then the encoding specified in the JVM flag will be applied. If idnaversion is specified, then the respective encoding will be applied.
keyalias	Optional		Alias of the key with which the certificate and private key are stored in the keystore. If it is not specified, the first entry in the keystore is chosen as the alias.
keypassword	Optional		Password for your private key. If not specified, the keystorepassword is used.
keystore	Optional		The location of the keystore file, for example, C:\OpenSSL\bin\keystore.jks.
keystorepassword	Optional		The password of the keystore. This is stored in ColdFusion configuration files.
mailerid	Optional	ColdFusion Application Server	Mailer ID to be passed in X-Mailer SMTP header, which identifies the mailer application.
maxrows	Optional		Maximum number of messages to send when looping over a query.
mimeattach	Optional		Path of the on-disk or in-memory file to attach to message. Attached file is MIME-encoded. ColdFusion attempts to determine the MIME type of the file; use the cfmailparam tag to send an attachment and specify the MIME type.
password	Optional		A password to send to SMTP servers that require authentication. Requires a username attribute.
port	Optional		TCP/IP port on which SMTP server listens for requests (normally 25). A value here overrides the Administrator.
priority	Optional	3	The message priority level. Can be one of the following values: An integer in the range 1-5; 1 represents the highest priority. One of the following string values, which correspond to the numeric values: highest or urgent, high, normal, low, and lowest or non-urgent.
query	Optional		Name of cfquery from which to draw data for messages. Use this attribute to send more than one message, or to send query results within a message.
remove	Optional	no	If yes, ColdFusion removes attachment files (if any) after the mail is successfully delivered.
replyto	Optional		Addresses to which the recipient is directed to send replies.
server	Optional		SMTP server address, or (Enterprise edition only) a comma-delimited list of server addresses, to use for sending messages. At least one server must be specified here or in the ColdFusion Administrator. A value here overrides the Administrator. A value that includes a port specification overrides the port attribute. For details, see Usage.
sign			Digitally signs the mail. If set to true, all messages that you send will have digital signature.
spoolenable	Optional		Whether to spool mail or always send it Immediately. Overrides the ColdFusion Administrator Spool mail messages to disk for delivery setting. yes: saves a copy of the message until the sending operation is complete. Pages that use this option might run slower than the ones that use the No option. no: queues the message for sending, without storing a copy until the operation is complete. If a delivery error occurs when this option is No, ColdFusion generates an Application exception and logs the error to the mail.log file.
startrow	Optional	1	Row in a query to start from.
timeout	Optional		Number of seconds to wait before timing out connection to SMTP server. A value here overrides the Administrator.
type	Optional	text/plain	MIME type of the message. Can be a valid MIME media type or one of the following: text: specifies text/plain type. plain: specifies text/plain type. html: specifies text/html type. For a list of all registered MIME media types, see www.iana.org/assignments/media-types/.
username	Optional		A user name to send to SMTP servers that require authentication. Requires a password attribute.
useSSL	Optional		Whether to use Secure Sockets Layer.
useTLS	Optional		Whether to use Transport Level Security.
wraptext	Optional	Do not wrap text	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.
encrypt	Optional	false	If the Email should be encrypted.
recipientcert	Optional	false	The path to the public key certificate of the recipient.
encryptionalgorithm	Optional		The encryption algorithm to use. The valid algorithms are: DES_EDE3_CBC RC2_CBC AES128_CBC AES192_CBC AES256_CBC The encryption support is provided through S/MIME.

Usage

Sends a mail message to the specified address. Mail messages can include attachments. The tag body can include CFML code to generate mail output. The cfmailparam and cfmailpart tags can only be used in the cfmail tag body. Mail messages can be single or multipart. If you send a multi-part mail message, all message content must be in cfmailpart tags; ColdFusion ignores multipart message text that is not in cfmailpart tags.

Note:

The cfmail tag does not make copies of attachments when spooling mail to disk. If you use the cfmail tag to send a message with an attachment with spooling enabled and you use the cffile tag to delete the attachment file, ColdFusion might not send the mail because the mailing process might execute after the file was deleted. (When this happens, the mail log includes a FileNotFound exception and the e-mail is not sent.) You can prevent this problem by setting SpoolEnable="No" in the attribute or disabling spooling in the ColdFusion Administrator. Disabling spooling causes the e-mail to be delivered immediately.

If you set type="text", sometimes whitespace might be compressed in the messages that you send. To resolve this, in the ColdFusion Administrator, go to Server Settings > Settings and then deselect the option Enable Whitespace Management.

Mail addressing

Mail addresses can have any of the following forms:

Format	Example
user (server)company.com
<user@server>	<rsmith@company.com>
DisplayName <user@server>	Rob Smith <rsmith@company.com>
"DisplayName" <user@server>	"Rob Smith" <rsmith@company.com>
user@server (DisplayName)	rsmith@company.com (Rob Smith)

Specifying mail servers

The server attribute can specify one or more mail servers.

Note:

If you specify multiple mail servers in ColdFusion Standard, the cfmail tag uses only the first server in the specification. ColdFusion logs a warning message to the mail log file and ignores the additional servers.

For each server, you can optionally specify a user name, password, and port. These values override the corresponding attributes, if any. The server attribute has the following format:

[user:password@]server[:port],[user:password@]server[:port],....

For example, the following line specifies one server, mail.myco.com that uses the default port and no user or password, and a second server with a user, password, and specific port:

server=mail.myco.com,mail_admin:adm2qzf@mail2.myco.com:24

When you specify multiple mail servers in ColdFusion Enterprise, ColdFusion tries the available servers in the order they are listed until it connects to a server. ColdFusion does not try to connect to a server that was unavailable in the last 60 seconds.

Digital Signature

To add digital signature to your mail, specify the attributes sign, keystore, keystorepassword, keyalias, and keypassword as provided in the following example:

<cfmail from="Sender@Company.com" server="sendmail.myCo.com" sign="true" keystore="C:\OpenSSL\bin\hello.jks" keystorepassword="digital" to="Recepient@Company.com" keyalias="crypto" keypassword="signature" subject="Mail with Digital Signature">

To add digital signature to all the mails you send, instead of adding the attributes to the tag, specify the settings in the Server Settings > Settings page of the ColdFusion Administrator.

If you do not specify the attributes in the tag, the Administrator settings are applied. Also, in the tag, if you set sign = "true" and do not specify the attributes keystore, keystorepassword, keyalias, and keypassword, then the values for these attributes specified using ColdFusion Administrator are applied.

Example

<h3>cfmail Example</h3> 

<!--- Delete the surrounding comments to use this example. 

<cfif IsDefined("form.mailto")> 
<cfif form.mailto is not "" AND form.mailfrom is not "" AND form.Subject is not ""> 
<cfmail to = "#form.mailto#" from = "#form.mailFrom#" subject = "#form.subject#"> 
This message was sent by an automatic mailer built with cfmail: 
= = = = = = = = = = = = = = = = = = = = = = = = = = = 
#form.body# 
</cfmail> 
<h3>Thank you</h3> 
<p>Thank you, <cfoutput>#mailfrom#: your message, #subject#, has been sent to 
#mailto#</cfoutput>.</p> 
</cfif> 
</cfif> 
<p> 
<form action = "cfmail.cfm" method="POST"> 
<pre> 
TO: <input type = "Text" name = "MailTo"> 
FROM: <input type = "Text" name = "MailFrom"> 
SUBJECT: <input type = "Text" name = "Subject"> 
<hr> 
MESSAGE BODY: 
<textarea name ="body" cols="40" rows="5" wrap="virtual"></textarea> 
</pre> 
<!--- Establish required fields. ---> 
<input type = "hidden" name = "MailTo_required" value = "You must enter a recipient"> 
<input type = "hidden" name = "MailFrom_required" value = "You must enter a sender"> 
<input type = "hidden" name = "Subject_required" value = "You must enter a subject"> 
<input type = "hidden" name = "Body_required" value = "You must enter some text"> 
<p><input type = "Submit" name = ""></p> 
</p> 
</form>

In ColdFusion 11, you can encrypt your mails using the following procedure:

Get the certificate of the user for whom you wanted to send the mail (.p7c format).
Specify the path to the generated certificate for the recipientcert attribute. For instance:
<cfmail ... encrypt="true" ENCRYPTIONALGORITHM = "DES_EDE3_CBC" recipientcert="#path#cert.p7c" >
Configure the mail server from your ColdFusion Administrator.
Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from the Oracle website for the JRE version that ColdFusion is configured with (if you are using an encryption algorithm whose key size is greater than 128).
Send the mail. See the following example.

<cfset path = GetDirectoryFromPath(getCurrentTemplatePath())>

<cfset algorithms = "DES_EDE3_CBC,RC2_CBC,AES128_CBC,AES192_CBC,AES256_CBC">

<cfloop index="algo" list="#algorithms#">

<cfmail to="joe@work.com" from="bob@work.com" 
subject="Sending a mail with the encryption algo : #algo#" 
sign ="false" 
encrypt="true" 
ENCRYPTIONALGORITHM = "#algo#" 
recipientcert="#path#cert.p7c" > 
This message is encrypted using the algorithm : #algo#. 
</cfmail>

</cfloop>

Example using attribute idnaversion

<cfprocessingdirective pageencoding="utf-8">
<cfmail to="sample@example.com" 
    from="test@example.com" 
    username="username" 
    password="password" 
    server="localhost" 
    subject="hello" 
    debug="true" 
    idnaversion="2003">
    Hello World !
</cfmail>

Get help faster and easier

New user?

cfmail

Description

Category

Syntax

See also

History

Attributes

Usage

Mail addressing

Specifying mail servers

Digital Signature

Example

Example using attribute idnaversion

Get help faster and easier

Ask the Community

Contact Us