cfmail

Description

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

Category

Communications tags, Internet protocol tags

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" 
    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"> 
 
(Optional) Mail message body and/or cfmailparam tags 
 
</cfmail>

See also

cfmailparam, cfmailpart, cfpop, cfftp, cfhttp, cfldap, Wrap; Using ColdFusion with mail servers in Sending and Receiving E-Mail in the Developing ColdFusion Applications

History

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

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 cfmailparamand 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 addressing

Mail addresses can have any of the following forms:

Specifying mail servers

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.

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>