ActivMail Bulk Email messaging for ColdFusion, solve CFMAIL problems.
ActivMail - Version 2.1.0.3
Tag Reference

CF_Mail is a wrapper tag for CFX_ActivMail a ColdFusion CustomTag for sending large amounts of email reliably. CF_Mail acts as a replacement to ColdFusion's CFMAIL, and has very similar attributes.

See Also: <CF_MailAttachment> and <CF_MailHeader>

Common Attributes

Attribute Name Required Data Type Notes
SENDMODE no String Must be set to one of the following:
Normal - sends one message to the server containing all the recipients
Query - the TO addresses are found in a query object passed in through the query attribute, and uses the TO attribute to determine which column. (Not supported in Lite Version)
Bulk - deprecated use query, sends a separate message for each recipient, each containing that recipient's name in the To: field (Not supported in Lite Version)
TYPE no String Either HTML or TEXT. Used to automatically set the TEXTMESSAGE attribute (if type=TEXT) or the HTMLMESSAGE (if type=HTML) using the tag's body content. See examples below, default is text.
SERVER no string The IP or DNS name of a SMTP server. Use a comma separated list of servers for fast performance (eg server1,server2,...,serverN). If no server is specified the tag will use the server that CFMAIL uses (the value set in CF Administrator), and if it can't figure out it defaults to 127.0.0.1 (localhost).
To use SMTP Authentication pass a username and password with each server. For example SERVER="user:pass@server.com,server2.com". Additionally you can specify ports for each server using a colin SERVER="user:pass@server.com:25". (Only one server is supported in Lite Version)
QUERY no query The name of a query that contains TO addresses, and fields used as tokens. (Not supported in Lite Version)
FROM yes string An email address specifying who the message is from. Should be in the form email@address.com or First Last <email@address.com> Contains one email address, or The name of a column in a query (sendmode=query only) if you want each message to have its own from address (for bounce tracking).
TO yes list The field/column name that contains email addresses in the query (for sendmode = query).
For other sendmodes, A comma delimited list of email addresses to send, each address on the list will receive a COPY of the message (the address will be in the TO field. Should be in the form email@address.com or First Last <email@address.com>
SUBJECT no string Text that will be the subject of the message.
CC no string An email address that will receive ONE copy of the message, but will show up on all messages in the CC field. Should be in the form email@address.com or First Last <email@address.com>
BCC no string An email address that will receive ONE copy of the first message sent. Should be in the form email@address.com or First Last <email@address.com>
REPLYTO no string An email address that will be used when a recipient replies to the message sent, but will show up on all messages in the CC field. Should be in the form email@address.com or First Last <email@address.com>
FAILTO no string The email address to be used as the Return Path for bounces. This address is sent during in the SMTP MAIL FROM command, this value may be different from the FROM attribute. When two different values are specified the FROM attribute is only used in the From: header. If this attribute is omited the FROM attribute value is used.
HTMLMESSAGE no string HTML content for the message. If the TEXTMESSAGE attribute is also called then the message will be sent as a Multi-Part message with a HTML part for email readers that support it, and a Plain Text part for those that do not.
TEXTMESSAGE no string PLAIN TEXT content for the message, sends a plain text message. If the HTMLMESSAGE attribute is also called then the message will be sent as a Multi-Part message with a HTML part for email readers that support it, and a Plain Text part for those that do not.
TOKENS no boolean When true tokens will be looked for in the message, see tokens example below. (Not supported in Lite Version)



Advanced Attributes

TOKENCHAR no char The character used to identify tokens, the default is %
DELIMITER no string Default is a Comma(,) Sets the separator for the TO list, see Java's StringTokenizer class for more info.
PORT no integer Sets the SMTP server port to connect to. Default is 25
LOGFILE no file Specifies a file on the server to create a log file. The file will be appended to if it exists. See theLog Reference.
VERBOSE no boolean When true Turns on Verbose logging, recommended setting is TRUE, default setting is FALSE. Verbose logging will log the time and email address after each message is sent in the LOGFILE. See theLog Reference.
CONNECTIONLIMIT no integer The number of messages to be sent on one SMTP connection. Most SMTP servers have a setting for a maximum number of messages to be sent on one connection. For best performance set this value to be the SMTP servers connection limit, the higher the value, the faster the messages will send. When the tag sends this amount of messages, it will close the socket, and create a new connection to the SMTP server. Default value is 20, recommended values 100 or 1000. Consult your system administrator before changing the SMTP connection limit on your SMTP server, low values for this setting are a typical anti-spam policies.
TIMEOUT no integer Number of seconds before closing a unresponsive socket to the SMTP server. Default value is 10.
SLEEP no integer If ActivMail is too fast for you, you can slow it down by putting in the number of miliseconds to sleep after it sends each message.
LINELENGTH no integer The maximum number of characters on a line in a plain text message. This will not chop words unless the word length is greater than this setting. The default value is 78, maximum aloud value is 950, SMTP RFC standard specifies that no line be longer than 1000 characters including the CRLF chars.
MEMORYTHRESHOLD no integer A number representing the percentage of free memory must be present before adding more messages to the queue. Default is 35 (makes sure 35% of max Java heap size is always present), it is important not to set this value too low (keep at least 4096KB of memory free), having too high of a value will result in an increased latency while queueing messages. If you have other Java CFX tags, or Java CFOBJECT calls running on the server be sure that you leave enough memory for those tags as well.
QUEUELIMIT no integer For Advanced Users Only, use MEMORYTHRESHOLD instead. The number of messages that are aloud to be in the message queue. If your JVM runs out of memory then consider using this attribute to limit the number of message objects it creates in memory. Note using this attribute will slow down execution time for the CFX tag (does not effect background thread performance), but is recommended to solve JVM out of Memory Errors. Default is value is unlimited.
TTL no integer For message failures, if a message fails for some reason it will stay in the ActivMail Queue until the TTL value decrements down to zero, this is useful for letting the server recover if it crashes, or letting other SMTP servers take over if one fails.
VERIFY no boolean Verifies the connection to at least one SMTP server in the list before sending messages, on failure a java.net.ConnectException is thrown. Default is true.
ERRORFILE no filepath For Debugging, redirects java's System.err messages to this file.
TEXTCHARACTERSET no string The character set of the string used for TEXTMESSAGE. The default value is us-ascii.
TEXTENCODING no string The encoding method used for the TEXTMESSAGE, default is 7bit. If you pass in either quoted-printable or base64 your text will be automatically encoded using the respective method. If you pass in any other value it is up to you to encode the string properly.
HTMLCHARACTERSET no string The character set of the string used for HTMLMESSAGE. The default value is iso-8859-1.
HTMLENCODING no string The encoding method used for the HTMLMESSAGE, default is quoted-printable. If you pass in either quoted-printable or base64 your text will be automatically encoded using the respective method. If you pass in any other value it is up to you to encode the string properly.


Examples
The following code will send an email to bob@jones.com, fred@jones.com, and buddy@jones.com

<CF_MAIL
   TO="bob@jones.com,fred@jones.com,buddy@jones.com"
   FROM="Billy Jones <billy@jones.com>"
   SUBJECT="Billy's got a new cow">
Hi, just wanted to announce that I've got a new cow!
</CF_MAIL>


The next example selects email addresses from a query, and dynamically makes the TO list using CF's ValueList() function. This example will also send a multi-part message, because both TEXTMESSAGE and HTMLMESSAGE is specified. This will also generate a verbose logfile with the date in the filename.

<cfquery name="qry" datasource="ds">
   SELECT email, name
   FROM farmers
</cfquery>

<CF_MAIL
   QUERY="qry"
   FROM="Billy Jones <billy@jones.com>"
   TO="email"
   SUBJECT="Hey %name% I got a new cow"
   VERBOSE="1"
   TOKENS="1"
   TYPE="HTML"
   TEXTMESSAGE="Hi %name%, just wanted to announce that I've got a new cow.">
Hi %name%, just wanted to announce that <b>I've got a new cow</b>.
</CF_MAIL>


The following QUERY could be used to generate an address that looks like First Last <email@address.com> with fields in a database named FirstName, LastName, and Email. Using this format recipients will see their name in the TO box of the message, instead of just the email address.


<cfquery name="qry" datasource="ds">
   SET CONCAT_NULL_YIELDS_NULL OFF
   SELECT firstname + ' ' + lastname + ' <' + email + '>' AS Email
   FROM users
</cfquery>

Note: SET CONCAT_NULL_YIELDS_NULL OFF is used to prevent SQL Server from making the result of the concatenation NULL if any of the fields are null. If your name, and email address fields do not allow nulls then you may remove that line. If your email address field allows NULL's and you are concatenating with a name, you should add an extra statement to the where clause that removes null addresses (eg WHERE email <> ''). The above example was designed for SQL Server, if you are running other servers check your database server's documentation.

ActivMail Documentation


Copyright © CFDEV.COM 2004