Jakarta Project: mailer2 tag library

Version: 1.0

Overview
Requirements
Configuration
Tag Summary
Tag Reference
Examples
Javadocs
Revision History

Overview

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

Send simple plain text e-mails
Attach local (file) or external (url) attachments to a message
Create HTML formatted messages
Create multipart/alternative HTML and plain text messages
Save messages in a scope for later use
Send messages in a background thread for better response times, or directly to get better feedback
Use JSTL 1.1 EL throughout
PLAIN or LOGIN SMTP authentication
Configure server, port, username and password with context-params in the application's web.xml
Load previosly stored messages, or save messages to disk
S/MIME sign or sign and encrypt messages using a Legion of the Bouncy Castle implementation of the S/MIME protocol

Requirements

This tag library requires the following:

JDK 1.4 or higher
mail.jar and activation.jar from a J2EE 1.4 distribution
bcprov-jdkX-Y.jar and bcmail-jdkX-Y.jar from http://www.bouncycastle.org where X is the JVM version and Y is the current BC version, e.g. bcprov-jdk14-124.jar and bcmail-jdk14-124.jar
JSP 2.0 container, like Tomcat 5.x or Resin 3.x

Configuration

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

Copy the tag library descriptor file to the /WEB-INF subdirectory of your web application.
Copy the tag library JAR file to the /WEB-INF/lib subdirectory of your web application.

Add a <taglib> element to your web application deployment descriptor in /WEB-INF/web.xml like this:

<taglib>
  <taglib-uri>http://jakarta.apache.org/taglibs/mailer2</taglib-uri>
  <taglib-location>/WEB-INF/taglibs-mailer2.tld</taglib-location>
</taglib>

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

mail	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.
header	JSP tag <mt:header> adds additional headers to an e-mail message. It is a child of <mt:mail> or <mt:part>.
addrecipient	JSP tag <mt:addrecipient> adds to, cc, or bcc recipients to an e-mail message. It is a child of <mt:mail>.
attach	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.
part	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.
send	JSP tag <mt:send> sends a previously stored message. <mt:send> does not have any child tags.
replyto	JSP 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

sign	JSP tag <mt:sign> is used to S/MIME sign a previously stored message. <mt:sign> does not have any child tags.
encrypt	JSP 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

save	JSP tag <mt:save> is used to save a previously stored message to the file system. <mt:save> does not have any child tags.
load	JSP 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 Body	JSP
Restrictions	None
Attributes	Name	Required	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
Variables	None
Examples	Example 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 Body	JSP
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	name	Yes	Yes	1.0
	The name of the header
	value	No	Yes	1.0
	The value of the header
Variables	None
Examples	Example 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 Body	JSP
Restrictions	None
Attributes	Name	Required	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
Variables	None
Examples	Example 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 Body	JSP
Restrictions	None
Attributes	Name	Required	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="...">
Variables	None
Examples	Example 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 Body	JSP
Restrictions	None
Attributes	Name	Required	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
Variables	None
Examples	See mt:mail

send				Availability: 1.0
JSP tag <mt:send> sends a previously stored message. <mt:send> does not have any child tags.
Tag Body	empty
Restrictions	None
Attributes	Name	Required	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
Variables	None
Examples	Example 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 Body	JSP
Restrictions	None
Attributes	Name	Required	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
Variables	None
Examples	Example 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 Body	empty
Restrictions	None
Attributes	Name	Required	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"
Variables	None
Examples	Example 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 Body	empty
Restrictions	None
Attributes	Name	Required	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"
Variables	None
Examples	Example 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 Body	empty
Restrictions	None
Attributes	Name	Required	Runtime Expression Evaluation	Availability
	message	Yes	Yes	1.0
	The message to save
	filename	Yes	Yes	1.0
	The location to save the message
Variables	None
Examples	Example 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 Body	empty
Restrictions	None
Attributes	Name	Required	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"
Variables	None
Examples	Example 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.