2010-04-14 - Jakarta Taglibs has been retired.

For more information, please explore the Attic.

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. The first way requires the name of the SMTP host to use. The second requires the name of a JNDI Resource for a JavaMail Session. The third requires the name of a JNDI Resource for a JavaMail MimePartDataSource. Refer to your servlet container documentation to determine which of these three methods you should use. During the creation of an e-mail message, the addresses are checked for the correct format. 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>
<!-- Or 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 Used to 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 Used to set the mail server that will send the mail.
port Used to set the mail server port that will be used to send the mail.
message Used to 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 Used to set the user name for mail session authentication.
password Used to set the password for mail session authentication.
header Used to set extra headers in the message. See Documentation for further information on other e-mail headers.
setrecipient Used to 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 Used to 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 Used to set one or more Reply-To addresses in the message.
from Used to set the From address of the message.
attach Used to 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 Used to set the subject in the message.
send Used to 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 Used to get messages explaining errors that occurred in setting any of the addresses.
 

Tag Reference

mail Availability: 1.0

Used to 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 BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 server  No   Yes  1.0
 

This attribute allows you to set the SMTP host if it is going to be other than localhost.

 port  No   Yes  1.0
 

This attribute allows you to 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
 

This attribute allows a message to be created using a predefined, JNDI named Session object.

 mimeMessage  No   No  1.0
 

This attribute 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
 

This attribute allows you to set the SMTP user to login

 password  No   Yes  1.0
 

This attribute allows you to 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.

VariablesNone
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

Used to set the mail server that will send the mail.

Tag BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

Used to set the mail server port that will be used to send the mail.

Tag BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

Used to 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 BodyJSP    
Restrictions

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

AttributesNameRequired Runtime Expression Evaluation Availability
 type  No   No  1.0
 

This attribute has 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
 

This attribute 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.

VariablesNone
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

Used to set the user name for mail session authentication.

Tag BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

Used to set the password for mail session authentication.

Tag BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

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

Tag BodyJSP    
Restrictions

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

AttributesNameRequired 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).

VariablesNone
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

Used to 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 BodyJSP    
Restrictions

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

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

VariablesNone
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

Used to 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 BodyJSP    
Restrictions

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

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

VariablesNone
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

Used to set one or more Reply-To addresses in the message.

Tag BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

Used to set the From address of the message.

Tag BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

Used to 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 BodyJSP    
Restrictions

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

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

VariablesNone
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

Used to set the subject in the message.

Tag BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

Used to 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 BodyJSP    
Restrictions

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

AttributesNone
VariablesNone
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

Used to get messages explaining errors that occurred in setting any of the addresses.

Tag BodyJSP    
Restrictions

Must be nested within send tag.

AttributesNameRequired Runtime Expression Evaluation Availability
 id  Yes   No  1.0
 

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

VariablesNameScopeAvailability
  id attribute value   Start of tag to end of page  1.0
 

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

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