# CFMAIL

CFMAIL allows you to send email messages via an SMTP server.

See also CFMAILPARAM.

### Syntax

    <CFMAIL TO="recipient"
        FROM="sender"
        CC="copy_to"
        BCC="blind_copy_to"
        SUBJECT="msg_subject"
        TYPE="msg_type"
        MAXROWS="max_msgs"
        MIMEATTACH="path"
        QUERY="query_name"
        GROUP="query_column"
        GROUPCASESENSITIVE="yes/no"
        STARTROW="query_row"
        SERVER="servername"
        PORT="port_ID"
        MAILERID="headerid"
        TIMEOUT="seconds">

#### TO

Required. The name of the recipient(s) of the email message. This can be either a static address (as in, TO="support@allaire.com"), a variable that contains an address (such as, TO="#Form.Email#"), or the name of a query column that contains address information (such as, TO="#EMail#"). In the latter case, an individual email message is sent for every row returned by the query.

#### FROM

Required. The sender of the email message. This attribute may be either static (e.g., FROM="support@allaire.com") or dynamic (as in, FROM="#GetUser.EMailAddress#").

#### CC

Optional. Indicates additional addresses to copy the email message to; "CC" stands for "carbon copy."

#### BCC

Optional. Indicates additional addresses to copy the email message without listing them in the message header. "BCC" stands for "blind carbon copy."

#### SUBJECT

Required. The subject of the mail message. This field may be driven dynamically on a message-by-message basis. For example, if you want to do a mailing that updates customers on the status of their orders, you might use a subject attribute like SUBJECT="Status for Order Number #Order_ID#".

#### TYPE

Optional. Specifies extended type attributes for the message. Currently, the only valid value for this attribute is "HTML". Specifying TYPE= "HTML" informs the receiving email client that the message has embedded HTML tags that need to be processed. This is only useful when sending messages to mail clients that understand HTML (such as Netscape 2.0 and above email clients).

#### MAXROWS

Optional. Specifies the maximum number of email messages you want to send.

#### MIMEATTACH

Optional. Specifies the path of the file to be attached to the email message. Attached file is MIME-encoded.

#### QUERY

Optional. The name of the CFQUERY from which you want to draw data for message(s) you want to send. Specify this attribute to send more than one mail message, or to send the results of a query within a single message.

#### GROUP

Optional. Specifies the query column to use when you group sets of records together to send as a single email message. For example, if you send a set of billing statements out to your customers, you might group on "Customer_ID." The GROUP attribute, which is case sensitive, eliminates adjacent duplicates in the case where the data is sorted by the specified field. See the Usage section for exceptions.

#### GROUPCASESENSITIVE

Optional. 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

Optional. Specifies the row in the query to start from.

#### SERVER

Required. The address of the SMTP server to use for sending messages. The server name specified in the ColdFusion Administrator is used if no server is specified.

#### PORT

The TCP/IP port on which the SMTP server listens for requests. This is almost always 25.

#### MAILERID

Optional. Specifies a mailer ID to be passed in the X-Mailer SMTP header, which identifies the mailer application. The default is Allaire ColdFusion Application Server.

#### TIMEOUT

Optional. The number of seconds to wait before timing out the connection to the SMTP server.

### Example

    <!--- This view-only example shows the use of CFMAIL --->
    <HTML>
    <HEAD>
    <TITLE>CFMAIL Example</TITLE>
    </HEAD>
    <BODY bgcolor=silver>
    <H3>CFMAIL Example</H3>
    <P>This view-only example shows the use of CFMAIL.  If your CFAS mail
    settings are configured successfully and the comments are removed,
    you will be able to use this code to send simple email.
    <!---
    <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>.
        </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 for this message">
    <INPUT TYPE="Hidden" NAME="MailFrom_required" VALUE="You must enter a
      sender for this message">
    <INPUT TYPE="Hidden" NAME="Subject_required" VALUE="You must enter a
      subject for this message">
    <INPUT TYPE="Hidden" NAME="Body_required" VALUE="You must enter some text
      for this message">
    <P><INPUT TYPE="Submit" NAME="">
    </FORM>  --->
    ...