Jakarta Project: Mailer Tag library

 

Version: 1.1

 

Table of Contents

 

Overview

This custom tag library is used to send e-mail.

E-mail can be sent in three ways.

  1. SMTP host
  2. JNDI Resource for a JavaMail Session
  3. JNDI Resource for a JavaMail MimePartDataSource

After the e-mail message has been created the send tag spawns a thread to send the message in the background so that the user does not have to wait for the SMTP host if it is busy. 

<!-- Create a message by entering the name of the SMTP host. -->
<!-- The default for this attribute is localhost; for a host other -->
<!-- than localhost supply it's name with the server attribute -->
<!-- as in the example below.  The body of the e-mail is supplied in the -->
<!-- message tag. The send tag is necessary to send the message. -->

<mt:mail server="home.net" 
         to="foo@home.net"
         from="bar@home.net" 
         subject="mail taglib">

    <mt:message>[body of message]</mt:message>

    <mt:send/>

</mt:mail>



<!-- Using a JNDI named JavaMail Session object defined by the -->

<!-- session attribute. -->

<mt:mail session="java:comp/env/session" 
         to="foo@home.net"
         from="bar@home.net" 
         subject="mail taglib">

    <mt:message>[body of message]</mt:message>

    <mt:send/>

</mt:mail>





<!--  Using a JNDI named JavaMail MimePartDataSource object -->
<!--  defined by mimeMessage attribute. -->

<mt:mail mimeMessage="java:comp/env/message" 
         to="foo@home.net"
         from="bar@home.net" 
         subject="mail taglib">

    <mt:message>[body of message]</mt:message>

    <mt:send/>

</mt:mail>

How e-mail is delivered depends on the JavaMail SMTP host settings. The JavaMail SMTP host can be configured by your Servlet Container so that bounced or undeliverable e-mails are returned to the sender by setting the folowing properties.

Name Type Description
mail.smtp.dsn.notify String Property determines if the user will be notified of undeliverable mail. Either NEVER, or some combination of SUCCESS, FAILURE, and DELAY (separated by commas).
mail.smtp.dsn.ret String Determines what part of the undeliverable message will be returned in the message to the sender. Either FULL or HDRS.
mail.smtp.sendpartial boolean If set to true, and a message has some valid and some invalid addresses, send the message anyway, reporting the partial failure with a SendFailedException. If set to false (the default), the message is not sent to any of the recipients if there is an invalid recipient address.

 

Requirements

This custom tag library requires a servlet container that supports the JavaServer Pages Specification, version 1.1 or higher. JavaMail 1.2 and the JavaBeans Activation Framework should be installed as extensions to your JVM.

 

Configuration

Follow these steps to configure your web application with this tag library:

To use the tags from this library in your JSP pages, add the following directive at the top of each page: 

<%@ taglib uri="http://jakarta.apache.org/taglibs/mailer-1.1" prefix="mt" %>

where "mt" is the tag name prefix you wish to use for tags from this library. You can change this value to any prefix you like.

 

Tag Summary

Mailer Tags

mail Create an e-mail message. Most attributes set via a tag within the body of this tag will take precedence and override any value that was set as an attribute in this tag. In the case of the three add tags, however, an address set as an attribute will not be overridden, but will be the first address in the list.
server Set the mail server that will send the mail.
port Set the mail server port that will be used to send the mail.
message Set the body of the message. Message will appear as it is written, any carriage returns and spaces in the JSP will be present in the delivered message.
user Set the user name for mail session authentication.
password Set the password for mail session authentication.
header Set extra headers in the message.
setrecipient Set any type of recipient to an e-mail. Two attributes are required, type and setress. Type may be either "to", "cc", or "bcc" and address should be a string representation of the recipients e-mail address.
addrecipient Add any type of recipient to an already existant list of recipients in an e-mail message. Two attributes are required, type and address. Type may be either "to", "cc", or "bcc" and address should be a string representation of the recipients e-mail address.
replyto Set one or more Reply-To addresses in the message.
from Set the From address of the message.
attach Add an attachment to an e-mail message. It is possible to add an attachment in one of three ways. First give the name of the file that is to be added. Second give the URL that points to the resource that is to be added. Third include the attachment in the body of the attach tag, in this case it is necessary to use the type attribute and give the mime type of the attachment.
subject Set the subject in the message.
send Send the message. If an error occured while creating the e-mail message and it cannot be sent, the body of this tag will be output to the browser. It is within the body of this tag where the page author can include an error message if it is desired.
error Get messages explaining errors that occurred in setting any of the addresses.
 

 

Tag Reference

mail Availability: 1.0

Create an e-mail message. Most attributes set via a tag within the body of this tag will take precedence and override any value that was set as an attribute in this tag. In the case of the three add tags, however, an address set as an attribute will not be overridden, but will be the first address in the list.

Tag Body JSP       
Restrictions

None

Attributes Name Required Runtime Expression Evaluation Availability
  server   No   Yes  1.0
 

Set the SMTP host if it is going to be other than localhost.

  port   No   Yes  1.0
 

Set the port used on the SMTP host if it is going to be other than the default of 25.

  session   No   No  1.0
 

Allows a message to be created using a predefined, JNDI named Session object.

  mimeMessage   No   No  1.0
 

Allows a message to be created using a predefined, JNDI named MimePartDataSource.

  authenticate   No   No  1.1
 

A value of true of false tells the mailer taglib if the mail server uses authentication. The default value is false. If the value is set to true and the mail server uses authentication, there are two methods which can be used to authenticate the user to the mail server.

  1. Provide the user and password attributes.
  2. Do not provide the user and password attributes, the user will be prompted for a name and password before the mail is sent.

  user   No   Yes  1.0
 

Set the SMTP user to login

  password   No   Yes  1.0
 

Set the SMTP user password to login

  to   No   No  1.0
 

The To address of the e-mail. Accepts a comma separated list of addresses.

  replyTo   No   No  1.0
 

The Reply-To address of the e-mail. Accepts a comma separated list of addresses.

  from   No   No  1.0
 

The From address of the e-mail.

  cc   No   No  1.0
 

The Carbon Copy address of the e-mail. Accepts a comma separated list of addresses.

  bcc   No   No  1.0
 

The Blind Carbon Copy address of the e-mail. Accepts a comma separated list of addresses.

  subject   No   No  1.0
 

The Subject of the e-mail.

Variables None
Examples Send a basic message: set the to, from, and subject attributes. The server attribute is not set, therefore the default setting of localhost will be used for the SMTP host.  
  


 
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib">
     <mt:message>[body of message]</mt:message>
     <mt:send/> 
</mt:mail>

server Availability: 1.1

Set the mail server that will send the mail.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes None
Variables None
Examples Send a basic message: set the to, from, and subject attributes. Set the server with the SeverTag.  
  

   
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib">
     <mt:server>some.mailserver.com</mt:server>
     <mt:message>[body of message]</mt:message>
     <mt:send/> 
</mt:mail>

port Availability: 1.1

Set the mail server port that will be used to send the mail.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes None
Variables None
Examples Send a basic message: set the to, from, and subject attributes. Set the server with the ServerTag, and port with PortTag.  
  

   
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib">
     <mt:server>some.mailserver.com</mt:server>
     <mt:port>26</mt:port>
     <mt:message>[body of message]</mt:message>
     <mt:send/> 
</mt:mail>

message Availability: 1.0

Set the body of the message. Message will appear as it is written, any carriage returns and spaces in the JSP will be present in the delivered message.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes Name Required Runtime Expression Evaluation Availability
  type   No   No  1.0
 

Two possible values: text or html. If text is selected the body of the message is just plain text (it has no html tags within it). If html is selected then the body of the message can contain HTML tags. The default value for this attribute is text.

  charset   No   No  1.0
 

Specifies the character set of the message. If this attribute is not specified, no value will be included with the type of the message, leaving the default in place.

Variables None
Examples Send a basic message: set the to, from, and subject attributes. The type attribute is not used in the message tag, it defaults to text.  
  

   
      
<mt:mail to="foo@home.net" 
         from="bar@home.net"
         subject="mail taglib">
     <mt:message>[body of message]</mt:message>
     <mt:send/> 
</mt:mail> 
               
             
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib">
     <mt:message type="html">
        [body of message containing html formatting]
     </mt:message>
     <mt:send/>
</mt:mail>

user Availability: 1.2

Set the user name for mail session authentication.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes None
Variables None
Examples Send a basic message: set the to, from, subject, and authentication attributes. Set the user name and password with their tags  
  

   
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib" 
         authenticate="true">
     <mt:user>george</mt:user>
     <mt:password>rumplestiltskin</mt:password>
     <mt:message>[body of message]</mt:message>
     <mt:send/> 
</mt:mail>

password Availability: 1.2

Set the password for mail session authentication.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes None
Variables None
Examples Send a basic message: set the to, from, subject, and authentication attributes. Set the user name and password with their tags  
  

   
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib" 
         authenticate="true">
     <mt:user>george</mt:user>
     <mt:password>rumplestiltskin</mt:password>
     <mt:message>[body of message]</mt:message>
     <mt:send/> 
</mt:mail>

header Availability: 1.0

Set extra headers in the message. See Documentation for further information on other e-mail headers.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes Name Required Runtime Expression Evaluation Availability
  name   Yes   No  1.0
 

The name of the header to be set.

  value   No   No  1.0
 

The value of the extra header to be set. This can also be placed in the body of the tag (see example).

Variables None
Examples Set the header Precedence with the value as an attribute.  
  

   
         
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib">
     <mt:header name="Precedence" value="bulk"/>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail> 

          

<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mail taglib">
     <mt:header name="Precedence">bulk</mt:header>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail>

setrecipient Availability: 1.0

Set any type of recipient to an e-mail. Two attributes are required, type and address. Type may be either "to", "cc", or "bcc" and address should be a string representation of the recipients e-mail address.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes Name Required Runtime Expression Evaluation Availability
  type   Yes   No  1.0
 

The type of address to be set either "to", "cc", or "bcc".

  address   No   No  1.0
 

The valid address that is to be set.

Variables None
Examples Set the to address in the e-mail message to jdoe@home.net using the address attribute.  
  

   
         
<mt:mail from="bar@home.net" 
         subject="mailer taglib">
     <mt:setrecipient type="to" address="jdoe@home.net"/>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail> 

          

<mt:mail to="jdoe@home.net" 
         from="bar@home.net" 
         subject="mailer taglib">
     <mt:setrecipient type="cc">foo@home.net,geo@place.net</mt:setrecipient>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail>

addrecipient Availability: 1.0

Add any type of recipient to an already existant list of recipients in an e-mail message. Two attributes are required, type and address. Type may be either "to", "cc", or "bcc" and address should be a string representation of the recipients e-mail address.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes Name Required Runtime Expression Evaluation Availability
  type   Yes   No  1.0
 

The type of address list either "to", "cc", or "bcc" this address is to be added to.

  address   No   No  1.0
 

The valid address that is to be set.

Variables None
Examples Add the to address jdoe@home.net in the e-mail message using the address attribute.  
  

   
         
<mt:mail from="bar@home.net" 
         subject="mailer taglib">
     <mt:addrecipient type="to" address="jdoe@home.net"/>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail> 

          

<mt:mail to="jdoe@home.net" 
         from="bar@home.net" 
         subject="mailer taglib">
     <mt:addrecipient type="bcc">foo@home.net,geo@place.net</mt:addrecipient>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail>

replyto Availability: 1.0

Set one or more Reply-To addresses in the message.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes None
Variables None
Examples Set the replyto address in the e-mail message to sax@home.net.  
  

   
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mailer taglib">
     <mt:replyto>sax@home.net</mt:replyto>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail>
               
             
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="mailer taglib">
     <mt:replyto>sax@home.net,cur@blank.com</mt:replyto>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail>

from Availability: 1.0

Set the From address of the message.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes None
Variables None
Examples Set the from address in the e-mail message to bar@home.net.  
  

   
      
<mt:mail to="joe@place.home">
     <mt:from>bar@home.net</mt:from>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail>

attach Availability: 1.0

Add an attachment to an e-mail message. It is possible to add an attachment in one of three ways. First give the name of the file that is to be added. Second give the URL that points to the resource that is to be added. Third include the attachment in the body of the attach tag, in this case it is necessary to use the type attribute and give the mime type of the attachment.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes Name Required Runtime Expression Evaluation Availability
  file   No   No  1.0
 

The name of the file to be included as an attachment. The name of the file must be a path or file name realative to the root directory of the web application. If the value of the file attribute equals "" (it is left empty) the tag will extract the name of the file from the body of the tag.

  url   No   No  1.0
 

The URL of a resource to be included as an attachment. The URL must be given as the full url like http://www.somedomain.com. If the value of the url attribute equals "" (it is left empty) the url will be extracted from the body of the tag.

  type   No   No  1.0
 

The mime type of the attachment that is included within the body of the attach tag.

Variables None
Examples Add the file mail/duck.gif as an attachment to the e-mail message.  
  

   
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="test">
     <mt:message>[body of message]</mt:message>
     <mt:attach file="mail/duck.gif"/>
     <mt:send/>
</mt:mail>
               
             
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="test">
     <mt:message>[body of message]</mt:message>
     <mt:attach url="">
        http://www.someplace.com/stuff.html
     </mt:attach>
     <mt:send/>
</mt:mail>
               
             
      
<mt:mail to="foo@home.net" 
         from="bar@home.net" 
         subject="test">
     <mt:message>[body of message]</mt:message>
     <mt:attach type="text/html">
        <h1>This is just a test</h1>
     </mt:attach>
     <mt:send/>
</mt:mail>

subject Availability: 1.0

Set the subject in the message.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must occur before send tag.

Attributes None
Variables None
Examples Set subject to "learning about the mail tag library" in the e-mail message.  
  

   
      
<mt:mail>
     <mt:setrecipient>foo@home.net</mt:setrecipient>
     <mt:from>bar@home.net</mt:from>
     <mt:subject>learning about the mail tag library</mt:subject>
     <mt:message>[body of message]</mt:message>
     <mt:send/>
</mt:mail>

send Availability: 1.0

Send the message. If an error occured while creating the e-mail message and it cannot be sent, the body of this tag will be output to the browser. It is within the body of this tag where the page author can include an error message if it is desired.

Tag Body JSP       
Restrictions

Must be nested within a mail tag.
Must be the last tag nested within the mail tag.

Attributes None
Variables None
Examples Send a message in which the following "An error has occurred, please back up and check that the addresses you gave are in the correct format" will be printed if an error occurs while trying to put the message together.  
  

   
      
<mt:mail to="foo@home.net" from="bar@home.net">
     <mt:subject>learning about the mail tag library</mt:subject>
     <mt:message>[body of message]</mt:message>
     <mt:send>
       An error has occurred, please back up and check that the 
       addresses you gave are in the correct format.
     </mt:send>
</mt:mail>

error Availability: 1.0

Get messages explaining errors that occurred in setting any of the addresses.

Tag Body JSP       
Restrictions

Must be nested within send tag.

Attributes Name Required Runtime Expression Evaluation Availability
  id   Yes   No  1.0
 

Script variable id for use with standard jsp:getProperty tag.

Variables Name Scope Availability
   id attribute value   Start of tag to end of page  1.0
 

Name used to retrieve the random string later in the page.

  Properties Name Get Set Availability
     error  Yes  No  1.0
   

The current error in the error list as a string.

Examples Set text to be displayed if an error occurs when creating the e-mail message. The message will use the error messages from the tag to be more specific as to the errors encountered.  
  

   
      
<mt:mail to="foo@home.net" from="bar@home.net">
     <mt:subject>learning about the mail tag library</mt:subject>
     <mt:message>[body of message]</mt:message>
     <mt:send>
        The following error(s) have occured: 
      <mt:error id="err">
         <jsp:getProperty name="err" property="error"/>
       </mt:error>
     </mt:send>
</mt:mail>

 

Examples

See the example application mailer-examples.war for examples of the usage of the tags from this custom tag library.

 

Java Docs

Java programmers can view the java class documentation for this tag library as javadocs.

 

Revision History

Review the complete revision history of this tag library.