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

CFX_ActivMail is a ColdFusion CustomTag for sending large amounts of email reliably.

All 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.
Bulk - deprecated use query, sends a separate message for each recipient, each containing that recipient's name in the To: field
SERVER yes string The IP or DNS name of a SMTP server. Use a comma separated list of servers for fast performance (eg server1,server2,...,serverN).
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".
QUERY no query The name of a query that contains TO addresses, and fields used as tokens.
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 token example below.
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.
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 STMP 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.
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.
THREADLIFE no integer Number of seconds that a sender thread will stay alive for, default is 60, if set to zero the thread doesn't die until server is restarted.
GETSTATUS no anything Sets variables in the calling template with information about ActivMail status, the varaibles it sets are activmail.queueSize, activmail.messagesSent, activmail.threads, activmail.jvmFreeMemory, and activmail.jvmTotalMemory. See example below.
ATTACHMENTS no string A pipe | delimited list of attachments. Each attachment uses key value pairs for example: attachments="file=c:\test.xml,type=text/xml|file=c:\test.txt" attaches two files. See the CF_MailAttachment tag for more info.
HEADERS no string A pipe | delimited list of headers, for example headers="name: value|x: y"
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

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

The next example selects email addresses from a query. This example will also send a multi-part message, because the HTML message is specified in the tag body (type=HTML), and the TEXTMESSAGE is specified as a tag attribute (note you can do this with type=TEXT and HTMLMESSAGE as well). This will also generate a verbose logfile with the date in the filename.

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

<CFX_ActivMail
   SERVER="localhost"
   QUERY="qry"
   FROM="Billy Jones <billy@jones.com>"
   TO="email"
   SUBJECT="Hey %name% I got a new cow"
   LOGFILE="c:/temp/maillog#Year(Now())##Month(Now())##Day(Now())#-#GetTickCount()#.xml"
   VERBOSE="1"
   SENDMODE="query"
   TOKENS="1"
   TEXTMESSAGE="Hi %name%, just wanted to announce that I've got a new cow."
   HTMLMESSAGE="Hi %name%, just wanted to announce that <b>I've got a new cow</b>."
>

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.


Querying ActivMail Status

Run this code sample to display information about ActivMail while or after it is running. You can use this to make a progress bar for the user as messages are queuing as well.


<CFX_ActivMail getstatus="1">

<cfset percentFree = Round((activmail.jvmFreeMemory / activmail.jvmTotalMemory) * 100)>
<cfset freeMemoryKB = Round(activmail.jvmFreeMemory / 1024)>
<cfset totalMemoryKB = Round(activmail.jvmTotalMemory / 1024)>

<cfoutput>
  Messages In Queue: #activmail.queueSize#<br>
 Messages Sent Since CF Start: #activmail.messagesSent#<br>
 Active Sender Threads: #activmail.threads#<br>
 Percent JVM Memory Free: #percentFree#%<br>
 KB JVM Memory Free: #freeMemoryKB# KB<br>
 KB JVM Memory Total: #totalMemoryKB# KB<br>
 ActivMail Version: #activmail.version#<br>
 </cfoutput>

ActivMail Documentation


Copyright © CFDEV.COM 2004