Sends an e-mail message that optionally contains query output, using an SMTP server.
Communications tags, Internet protocol tags
<cfmailfrom = "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" mailerid = "header id
" maxrows = "integer
" mimeattach = "path
" password = "string
" port = "integer
" priority = "integer or string priority level
" query = "query name
" 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
">
(Optional) Mail message body and/or cfhttpparam tags
</cfmail>
cfmailparam, cfmailpart, cfpop, cfftp, cfhttp, cfldap, Wrap; Using ColdFusion with mail servers in "Sending and Receiving E-Mail" in the ColdFusion Developer's Guide
ColdFusion 8: Added priority, useSSL, and useTLS attributes.
ColdFusion MX 7:
ColdFusion MX 6.1:
ColdFusion MX: Added the SpoolEnable attribute.
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; |
Character encoding of the mail message, including the headers. The following list includes commonly used values:
For more information on character encodings, see www.w3.org/International/O-charset.html. |
debug |
Optional |
no |
|
failto |
Optional |
|
Address to which mailing systems should send delivery failure notifications. Sets the mail envelope reverse-path value. |
from |
Required |
|
E-mail message sender:
This attribute does not have to be a valid Internet address; it can be any text string. |
to |
Required |
|
Message recipient e-mail addresses:
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. |
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 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:
|
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. |
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. |
spoolenable |
Optional |
|
Whether to spool mail or always send it Immediately. Overrides the ColdFusion Administrator Spool mail messages to disk for delivery setting.
|
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:
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. |
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.
Mail addresses can have any of the following forms:
Format |
Example |
---|---|
user@server |
rsmith@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) |
The server attribute can specify one or more mail 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.
<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>