Java Glossary : JavaMail

Java definitions: 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

You are here : home : Java Glossary : J words : JavaMail.

Sun's generic Java API for mail. Sun has a SMTP, POP3 and IMAP4 implementation you can download version 1.3.1 (The download is in two parts: JavaMail 1.3.1 API and JAF 1.0.2 JavaBeans Activation Framework extension javax.activation .) To install JAF, open the download with WINZIP and extract all files with folder names to the root directory of some drive. Ditto for JavaMail. Then make sure jaf-1.0.2\activation.jar and javamail-1.3.1\mail.jar are explicitly mentioned in your classpath, (not just in a classpath directory!). Alternatively, add the jars to the ext directory.

Look on your local hard disk in the JavaMail downloaded docs c:\javamail-1.3.1\docs\javadocs\index.html or online. Look on your local hard disk in the JAF downloaded docs c:\jaf-1.0.2\docs\javadocs\index.html or online. JavaMail and JAF docs are not part of the JDK, but the source comes with J2EE. Third Party vendors now support the API with higher performance implementations. JavaMail does not support the Windows proprietary MAPI protocol.

The Sun Tutorial is the best way to get started, since it explains how all the classes fit together. The API docs give a lot of detail, but nothing on how it all fits together. Another way to understand it is to look at the demo examples, particularly msgsend.java to send and msgshow.java to receive. The term store refers to all your messages stored on the server's hard disk. The term folder refers to the mail messages stored on the mail server in the SMTP INBOX. Folder.getMessages just gets message headers. MimeMessege.getContent gets the message body.

Coding Tips

The names of protocols are case sensitive and must be specified in lower case e.g. "pop3", "smtp" and "imap".

If you get a Message, you can't close the Folder or Session until you are completely finished grabbing fields for the Message. Once the Session is gone, you can't get any additional information about the Message. This is not that unusual, but it means you can't write a method to return a Message object unless either:

All the Message's interesting fields have already been probed and cached.
You keep the Session and Folder open. Until the caller is finished with the Message object.

Similarly you need to hold Folder and Session open in order to be able to later delete the Message from the server.

Most JavaMail applications involve reading a message and modifying it in some way and sending it on. Most mail servers will not permit you to modify the incoming message. You must create a new one and copy the parts over. There are three techniques you can use to copy.

Part.getContent Part.setContent
Part.getDataHandler Part.setDataHandler
Multipart.getBodyPart Multipart.addBodyPart

The third method has the disadvantage you can't modify the part after you copy. It has the advantages it has almost no overhead; you are just copying a pointer, and it should work with any MIME type, even ones for which there is no DataHandler.

You probably want to use transport.sendMessage ( message, recipients ), not Transport. send( message );

Often code like this fails:

message.setFlag( Flags.Flag.SEEN, true );
message.setFlag( Flags.Flag.DELETED, true );

I have not yet tracked down why. I supect it may be that the Session, Folder or MimeMessage times out if you wait too long.

JavaMail In Applets

JavaMail is not part of the standard distribution. You can't then very well use it in Applets, since the browser would need to download the entire 307K Javamail jar and 57K JAF jar every time the Applet ran. Better to use Java Web Start where the jars will be downloaded only once.

Awkward Characters

How to you talk JavaMail into using RFC 2047 encoding to permit non-ASCII characters in the FROM: TO: and SUBJECT: fields. Message.setSubject does not let you specify an encoding. Neither is there a Message.setHeaderEncoding method. I guess you have to encode/decode it yourself using javax.mail.internet.MimeUtility.

JavaMail is does not provide a mailserver. You might use something like James rather that using your ISP's mailserver.

email ¤ mailserver ¤ POP3 ¤ sendmail ¤ SMTP

home	Canadian Mind Products
	mindprod.com IP:[24.87.56.253]
	Your IP:[80.134.30.163]
	You are visitor number 4119.
	Please send errors, omissions and suggestions
	to improve this page to Roedy Green.
	You can get a fresh copy of this page from:	or possibly from your local J: drive mirror:
	http://mindprod.com/jgloss/javamail.html	J:\mindprod\jgloss\javamail.html