CF_MAIL and CF_MAILPARAM Custom ColdFusion Tags

Current Version: 1.0 (30-May-2003)

> Description
> Attributes
> Result Values
> Example
> Downloads
> License and Disclaimer

Description

 

CF_MAIL and the companion CF_MAILPARAM are designed as a "drop-in" replacement for ColdFusion's CFMAIL and CFMAILPARAM tags. The tags are meant to emulate the behavior of CF version 5. This CF_MAIL should not be confused with any other cf_mail custom tag that may be out there (there are at least a couple available with the same name). CF_MAIL is a solution to CF's sometimes-unreliable mailing functionality. The underlying code places mail directly in our mail server's outgoing queue skipping any intermediate processes (specifically, it utilizes functionality of the inFusion Mail Server (iMS) from http://www.CoolFusion.com/ via the iMSMail COM object). We highly recommend that all our ColdFusion hosting clients make use of CF_MAIL in their applications.

Attributes

 

CF_MAIL supports the following attributes of CFMAIL:

  • TO
  • FROM
  • SUBJECT
  • CC
  • BCC
  • MIMEATTACH
  • MAILERID

 

CF_MAIL does NOT support the following attributes (they are ignored if present):

  • QUERY - if a non-blank query parameter is passed CF_MAIL returns an error
  • MAXROWS
  • STARTROW
  • GROUP
  • GROUPCASESENSITIVE
  • SERVER
  • PORT
  • TIMEOUT

 

CF_MAILPARAM supports all the attributes of CFMAILPARAM:

  • FILE
  • NAME
  • VALUE

 

For more information on all the above attributes, please see the documentation for CFMAIL. The implementation of the supported attributes is identical to CFMAIL. Note that you should always use a known valid FROM address because if the mail delivery fails, the failure notice will be sent to this address. Using an unverified address a user entered in a Web form is typically not a good idea.

CF_MAIL can also accept a few unique attributes:

  • WORDWRAP - integer; optional; default: 0 (zero); If not zero, wrap message text at specified column.
  • THROWERROR - boolean; optional; default: true; If true, causes errors to be generated, or thrown (same behavior as CFMAIL). If false, execution status is always returned in cf_mail.statusCode and cf_mail.statusMessage result variables (see below).
  • DEBUG - boolean; optional; default: false; If true, prints a bunch of debug info after sending mail (only useful for debugging the cf_mail tag code itself).

 

Result Values

 

CF_MAIL returns two variables after execution, cf_mail.statusCode and cf_mail.statusMessage, in the variables scope of the calling document. As the names suggest, the first will be a numerical code and the latter is a message explaining the result. By default only a result of 0 (zero), meaning "Success," will be returned because CF_MAIL will throw an error if one arises. However if THROWERROR is set to false, you can use the cf_mail.statusCode to examine the result and take appropriate action.

cf_mail.statusCode can have the following values (values <100 are success codes, >= 200 are error codes):

Code : Description
   0 : Default success result

 200 : Unknown error condition (eg. error creating object)
 210 : No Closing Tag
 211 : Non-blank QUERY attribute detected 
        (tag does not support it)
 215 : TO attribute is blank or not an email address
 216 : FROM attribute is blank or not an email address
 220 : SMTPTO is blank or not an email address 
        (after processing TO address(es))
 221 : SMTPFROM is blank or not an email address 
        (after processing FROM address)

 

Example

 

<cf_mail to="somewhere@example.com"
         cc="Some Body <somebody@example.com>"
         bcc="another@example.com,yetanother@example.com"
         from="John <someone@example.com>"
         subject="Test Subject">
   <cf_mailparam name="X-Mailer" value="foobar">
   <cf_mailparam file="c:\temp\test.txt">
   ... message text ...
</cf_mail>

Downloads

 

If you intend to simply use the tag on our servers, there is nothing to download or install, simply use CF_MAIL in place of CFMAIL in your CF code. To test on your own server w/out having the CF_MAIL tag installed, your code could switch to using CFMAIL (based on global variable which indicates where the site is running, for instance).

But if you want your own copy of the tag, you can download it here. CF_MAIL requires ColdFusion version 5 or higher to run. Note that if you want to actually make the tag send out mail, you'll need to be running the inFusion Mail Server (iMS) from http://www.CoolFusion.com/. You can also use the tag for testing purposes (the mail won't actually be sent but you can review the mail that is generated to check formatting, etc.) by using our "developer's kit," available below. The kit contains installation and usage instructions, the CF_MAIL tag, as well as a more powerful mail sending solution, a custom tag called CFX_IMSMAIL and instructions for it. If you are already familiar with iMS then you should know that this CF_MAIL tag calls the iMSMail COM object (available at ftp://ftp.coolfusion.com/pub/ods/imsmail/ and also included in our dev kit), so make sure it is properly installed before using.

 

License and Disclaimer

 

Hosting customers of World Design Group are free to utilize CF_MAIL on our servers in the same fashion they would use CFMAIL and need not worry about any licensing issues.

CF_MAIL is also distributed as free software under the terms of the Perl Artistic License. The code is Copyright 2003 by Maxim Paperno and World Design Group, Inc.

CF_MAIL was written and is maintained by Maxim Paperno of World Design Group. You can contact me at MPaperno@WorldDesign.com.

THIS PROGRAM IS PROVIDED AND DISTRIBUTED "AS IS", WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.