Jakarta Project: mailer2 tag library

Version: 1.0

Table of Contents

Overview

The mailer2 tag library is a complete rewrite of the original Mailer Tag Library. It has the following features:

Requirements

This tag library requires the following:

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/mailer2" 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

Main Tags
mailJSP tag <mt:mail> constructs an e-mail message. It is the root element of this tag library. <mt:mail> can have the following child tags: <mt:addrecipient>, <mt:attach>, <mt:header>, or <mt:part>. The message will be sent unless the var attribute has been set.
headerJSP tag <mt:header> adds additional headers to an e-mail message. It is a child of <mt:mail> or <mt:part>.
addrecipientJSP tag <mt:addrecipient> adds to, cc, or bcc recipients to an e-mail message. It is a child of <mt:mail>.
attachJSP tag <mt:attach> is used to add attachments to an e-mail message. It is a child of <mt:mail> or <mt:part>. Either the url, or the file, or the message or both name and type attributes should be present. If the url attribute is present, the name and type are derived from the HTTP response. If the filename attribute is present, the name and type are also automatically derived from the filename and a MIME type table. If the message attribute is present, the type is "message/rc822" and the name is the subject of the attached message. If both name and type are present, the body content of the tag is added as an attachment.
partJSP tag <mt:part> is used to create a multipart mail. It is used for HTML and plain text multipart mail alternatives or multipart/digest messages that contain several messages. It is a child of <mt:mail>. Allowed children are <mt:header> and <mt:attach>. Multiple <mt:parts> can be added to an <mt:mail> tag. The type attribute of <mt:mail> should then be one of the multipart/* variants, e.g. multipart/mixed, multipart/related or multipart/alternative. The attachments inside <mt:part> and its optional body content are assumed to be multipart/related. This enables the creation of HTML formatted e-mail. References to images should be be made using cid: URLs.
sendJSP tag <mt:send> sends a previously stored message. <mt:send> does not have any child tags.
replytoJSP tag <mt:replyto> adds a reply-to address to an e-mail message. It is a child of mt:mail.
 
S/MIME signing and encryption tags
signJSP tag <mt:sign> is used to S/MIME sign a previously stored message. <mt:sign> does not have any child tags.
encryptJSP tag <mt:encrypt> is used to S/MIME sign and encrypt a previously stored message. <mt:encrypt> does not have any child tags.
 
Loading and saving messages
saveJSP tag <mt:save> is used to save a previously stored message to the file system. <mt:save> does not have any child tags.
loadJSP tag <mt:load> is used to load a message from the file system. <mt:load> does not have any child tags.
 

Tag Reference

mail Availability: 1.0

JSP tag <mt:mail> constructs an e-mail message. It is the root element of this tag library. <mt:mail> can have the following child tags: <mt:addrecipient>, <mt:attach>, <mt:header>, or <mt:part>. The message will be sent unless the var attribute has been set.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 bcc  No   Yes  1.0
 

Comma separated list of e-mail addresses to send the message to as blind carbon copy

 cc  No   Yes  1.0
 

Comma separated list of e-mail addresses to send the message to as carbon copy

 from  Yes   Yes  1.0
 

The e-mail address from whom the message is sent, or set the context-param org.apache.taglibs.mailer2.from

 importance  No   Yes  1.0
 

The importance of the message, either "low", "normal" or "high"

 mimemessage  No   Yes  1.0
 

The name of a JNDI lookup javax.mail.internet.MimePartDataSource to configure the mail Session

 password  No   Yes  1.0
 

The password to use with PLAIN or LOGIN SMTP authentication, or set the context-param org.apache.taglibs.mailer2.password

 port  No   Yes  1.0
 

The port of the mail server, default 25, or set the context-param org.apache.taglibs.mailer2.port

 replyto  No   Yes  1.0
 

The e-mail address to reply-to

 scope  No   Yes  1.0
 

Scope to store the message in instead of sending it directly, either "page" (default), "request", "session", or "application"

 type  No   Yes  1.0
 

The Content-Type of the message, default "text/plain"

 encoding  No   Yes  1.0
 

The character set encoding of the message, default unspecified

 server  No   Yes  1.0
 

The name of the mail server, default "localhost", or set the context-param org.apache.taglibs.mailer2.server

 session  No   Yes  1.0
 

The name of a JNDI lookup javax.mail.Session to configure the mail Session

 subject  No   Yes  1.0
 

The subject of the e-mail message

 to  No   Yes  1.0
 

Comma separated list of e-mail addresses to send the message to

 username  No   Yes  1.0
 

The username to use with PLAIN or LOGIN SMTP authentication, or set the context-param org.apache.taglibs.mailer2.username

 var  No   No  1.0
 

Name of variable to store message in the scope indicated by the scope attribute, instead of sending it directly

 background  No   Yes  1.0
 

Whether the mail should be sent in a background thread, default true. If true then no feedback (e.g. exceptions) will be returned to the user. ServletContext.log() is used instead

VariablesNone
ExamplesExample usage of the <mt:mail> tag. Note: the use of the cid: URL scheme to access an embedded logo in an HTML formatted mail message 
 


<mt:mail subject="Test mail" from="john.doe@example.com"
    to="jane.doe@example.com" server="smtp.example.com">
    Hi Jane, here's my first mail
</mt:mail>

<mt:mail subject="Test mail" from="john.doe@example.com" server="smtp.example.com">
    <mt:addrecipient type="to">jane.doe@example.com</mt:addrecipient>
    Hi Jane, attached is the file you requested.
    <mt:attach filename="c:/work/document.doc"/>
</mt:mail>

<mt:mail subject="Test mail" from="john.doe@example.com"
    to="jane.doe@example.com" server="smtp.example.com"
    type="multipart/alternative">
    <mt:part type="text/plain">
        Hi Jane, here's the plain text version of the mail.
    </mt:part>
    <mt:part type="text/html">
        <html>
        <head>
        <style type="text/css">
            h1 { color: red; }
            body {
                background-repeat: no-repeat;
                background-position: left top;
                margin-top: 100px;
                background-image: url(cid:jakarta-logo.gif);
            }
        </style>
        <title>HTML Version</title>
        </head>
        <body>
            <h1>Hi Jane,</h1>
            Here's the HTML version of the same mail
        </body>
        </html>
        <mt:attach url="http://jakarta.apache.org/images/jakarta-logo.gif"/>
    </mt:part>
</mt:mail>

header Availability: 1.0

JSP tag <mt:header> adds additional headers to an e-mail message. It is a child of <mt:mail> or <mt:part>.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 name  Yes   Yes  1.0
 

The name of the header

 value  No   Yes  1.0
 

The value of the header

VariablesNone
ExamplesExample usage of the <mt:header> tag. 
 


<mt:header name="Precedence" value="Bulk"/>

<mt:header name="Precedence">Bulk</mt:header>

addrecipient Availability: 1.0

JSP tag <mt:addrecipient> adds to, cc, or bcc recipients to an e-mail message. It is a child of <mt:mail>.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 type  Yes   No  1.0
 

The type of recipient, either "to", "cc", or "bcc"

 name  No   Yes  1.0
 

The real name of the recipient

 address  No   Yes  1.0
 

The e-mail address

VariablesNone
ExamplesExample usage of the <mt:addrecipient> tag. 
 


<mt:addrecipient type="to" address="john.doe@example.com"/>

<mt:addrecipient type="to" name="John Doe" address="john.doe@example.com"/>

<mt:addrecipient type="cc">john.doe@example.com</mt:addrecipient>

attach Availability: 1.0

JSP tag <mt:attach> is used to add attachments to an e-mail message. It is a child of <mt:mail> or <mt:part>. Either the url, or the file, or the message or both name and type attributes should be present. If the url attribute is present, the name and type are derived from the HTTP response. If the filename attribute is present, the name and type are also automatically derived from the filename and a MIME type table. If the message attribute is present, the type is "message/rc822" and the name is the subject of the attached message. If both name and type are present, the body content of the tag is added as an attachment.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 filename  No   Yes  1.0
 

The name of a local file to attach to the part or mail

 url  No   Yes  1.0
 

The url of a external resource to attach to the part or mail

 type  No   Yes  1.0
 

The content-type of the body content of the attachment

 name  No   Yes  1.0
 

The name of the attachment; this is the name under which the attachment can be saved

 encoding  No   Yes  1.0
 

The encoding of the attachment, default unspecified

 message  No   Yes  1.0
 

A Message object stored with a previous <mt:mail var="...">

VariablesNone
ExamplesExample usage of the <mt:attach> tag. 
 


<mt:attach filename="c:/temp/example.txt"/>

<mt:attach url="http://jakarta.apache.org/images/jakarta-logo.gif"/>

<mt:attach type="text/plain" name="First Attachment" encoding="utf-8">
    This is the content of the first attachment. It contains utf-8 cháràctërs.
</mt:attach>

<mt:mail var="attachment1" from="john.doe@example.com" subject="First Mail">
    <mt:addrecipient type="to">jane.doe@example.com</mt:addrecipient>
    First mail
    </mt:mail>
<mt:mail var="attachment2" from="jane.doe@example.com" subject="Second Mail">
    <mt:addrecipient type="to" address="john.doe@example.com"/>
    Second mail
</mt:mail>
<mt:mail from="digest@example.com" subject="Digest of two messages" type="multipart/digest">
    <mt:addrecipient type="to" name="Digest User">digest@example.com</mt:addrecipient>
    <mt:attach message="${attachment1}"/>
    <mt:attach message="${attachment2}"/>
</mt:mail>

part Availability: 1.0

JSP tag <mt:part> is used to create a multipart mail. It is used for HTML and plain text multipart mail alternatives or multipart/digest messages that contain several messages. It is a child of <mt:mail>. Allowed children are <mt:header> and <mt:attach>. Multiple <mt:parts> can be added to an <mt:mail> tag. The type attribute of <mt:mail> should then be one of the multipart/* variants, e.g. multipart/mixed, multipart/related or multipart/alternative. The attachments inside <mt:part> and its optional body content are assumed to be multipart/related. This enables the creation of HTML formatted e-mail. References to images should be be made using cid: URLs.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 type  No   Yes  1.0
 

The content-type of the body of this part

 encoding  No   Yes  1.0
 

The character set encoding of the body of this part, default unspecified

VariablesNone
ExamplesSee mt:mail 
 


send Availability: 1.0

JSP tag <mt:send> sends a previously stored message. <mt:send> does not have any child tags.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 message  Yes   Yes  1.0
 

The message to send

 background  No   Yes  1.0
 

Whether the mail should be sent in a background thread, default true. If true then no feedback (e.g. exceptions) will be shown to the user. ServletContext.log() is used instead

VariablesNone
ExamplesExample usage of the <mt:send> tag. 
 


<mt:mail var="message" subject="Test mail" from="john.doe@example.com"
    to="jane.doe@example.com" server="smtp.example.com">
    Hi Jane, here's my first mail
</mt:mail>
<mt:send message="${message}" background="true"/>

replyto Availability: 1.0

JSP tag <mt:replyto> adds a reply-to address to an e-mail message. It is a child of mt:mail.

Tag BodyJSP    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 name  No   Yes  1.0
 

The real name of the reply-to recipient

 address  No   Yes  1.0
 

The e-mail address to reply-to

VariablesNone
ExamplesExample usage of the <mt:replyto> tag. 
 


<mt:replyto address="john.doe@example.com"/>

<mt:replyto name="John Doe">john.doe@example.com</mt:replyto>

sign Availability: 1.0

JSP tag <mt:sign> is used to S/MIME sign a previously stored message. <mt:sign> does not have any child tags.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 message  Yes   Yes  1.0
 

The message to sign

 keystore  Yes   Yes  1.0
 

The name of the keystore file (e.g. keystore.p12 or keystore.pfx)

 storepass  No   Yes  1.0
 

The password to open the keystore

 storetype  No   Yes  1.0
 

The type of keystore file, e.g. "PKCS12" (default, for .p12 or .pfx keystores), or "JKS", etc.

 alias  Yes   Yes  1.0
 

The alias of the private key in the keystore to sign the message with

 var  Yes   No  1.0
 

The name of the variable to store the signed message in

 scope  No   Yes  1.0
 

The scope to store the signed message in, either "page" (default), "request", "session", or "application"

VariablesNone
ExamplesExample usage of the <mt:sign> tag. 
 


<mt:mail var="message" subject="Signed Mail" from="john.doe@example.com"
    to="jane.doe@example.com" server="smtp.example.com">
    Hi Jane, this mail has been signed.
</mt:mail>
<mt:sign message="${message}" var="signedMessage" keystore="keystore.p12"
    alias="johndoe" storepass="secret"/>
<mt:send message="${signedMessage}"/>

encrypt Availability: 1.0

JSP tag <mt:encrypt> is used to S/MIME sign and encrypt a previously stored message. <mt:encrypt> does not have any child tags.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 message  Yes   Yes  1.0
 

The message to encrypt

 keystore  Yes   Yes  1.0
 

The name of the keystore file (e.g. keystore.p12 or keystore.pfx)

 storepass  No   Yes  1.0
 

The password to open the keystore

 storetype  No   Yes  1.0
 

The type of keystore file, e.g. "PKCS12" (default, for .p12 or .pfx keystores), or "JKS", etc.

 alias  Yes   Yes  1.0
 

The alias of the private key in the keystore to encrypt the message with

 var  Yes   No  1.0
 

The name of the variable to store the encrypted message in

 scope  No   Yes  1.0
 

The scope to store the encrypted message in, either "page" (default), "request", "session", or "application"

VariablesNone
ExamplesExample usage of the <mt:encrypt> tag. 
 


<mt:mail var="message" subject="Encrypted Mail" from="john.doe@example.com"
    to="jane.doe@example.com" server="smtp.example.com">
    Hi Jane, this mail has been signed and encrypted.
</mt:mail>
<mt:encrypt message="${message}" var="encryptedMessage" keystore="keystore.p12"
    alias="johndoe" storepass="secret"/>
<mt:send message="${encryptedMessage}"/>

save Availability: 1.0

JSP tag <mt:save> is used to save a previously stored message to the file system. <mt:save> does not have any child tags.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 message  Yes   Yes  1.0
 

The message to save

 filename  Yes   Yes  1.0
 

The location to save the message

VariablesNone
ExamplesExample usage of the <mt:save> tag. 
 


<mt:mail var="message" subject="Test mail" from="john.doe@example.com"
    to="jane.doe@example.com" server="smtp.example.com">
    Hi Jane, here's my first mail
</mt:mail>
<mt:sign message="${message}" var="signedMessage" .../>
<mt:save message="${signedMessage}" filename="signed.message"/>

load Availability: 1.0

JSP tag <mt:load> is used to load a message from the file system. <mt:load> does not have any child tags.

Tag Bodyempty    
Restrictions

None

AttributesNameRequired Runtime Expression Evaluation Availability
 filename  Yes   Yes  1.0
 

The location to load the message from

 var  Yes   Yes  1.0
 

The name of the variable to store the message in

 scope  No   No  1.0
 

The scope to store the message in, either "page" (default), "request", "session", or "application"

VariablesNone
ExamplesExample usage of the <mt:load> tag. 
 


<mt:load var="message" filename="signed.message"/>
<mt:send message="${message}"/>

Examples

See the example application mailer2-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.