Chapter 1. Introducing the JavaMail API

The JavaMail API is a fairly high-level representation of the basic components of any email system. The components are represented by abstract classes in the javax.mail package. For instance, the abstract class javax.mail.Message represents an email message. It declares abstract methods to get and set various kinds of envelope information for the message, such as the sender and addressee, the date sent, and the subject. The abstract class javax.mail.Folder represents a message container. It declares abstract methods to retrieve messages from a folder, move messages between folders, and delete messages from a folder.

These classes are all abstract because they don’t make many assumptions about how the email is stored or transferred between machines. For instance, they do not assume that messages are sent using SMTP or that they’re structured as specified in RFC 822. Concrete subclasses of these classes specialize the abstract classes to particular protocols and mail formats. If you want to work with standard Internet email, you might use javax.mail.MimeMessage instead of javax.mail.Message, javax.mail.InternetAddress instead of javax.mail.Address, and com.sun.mail.imap.IMAPStore instead of javax.mail.Store. If you were writing code for a Microsoft Exchange-based system, you’d use different concrete implementation classes but the same abstract base classes.

The JavaMail API roughly follows the abstract factory design pattern. This pattern allows you to write your code based on the abstract superclasses without worrying too much about the lower-level details. The protocols and formats used and the associated concrete implementation classes are determined mostly by one line of code early in the program that names the protocol. Changing the protocol name goes 90% of the way toward porting your program from one protocol (say, POP) to another (say, IMAP).

Service providers implement particular protocols. A service provider is a group of concrete subclasses of the abstract JavaMail API classes that specialize the general API to a particular protocol and mail format. These subclasses are probably (though not necessarily) organized into one package. Some of these (IMAP, SMTP) are provided with the reference implementation in the undocumented com.sun.mail package. Others (NNTP, Exchange) are available from third parties. And some (POP) are available from both Oracle and third parties. The purpose of the abstract JavaMail API is to shield you from low-level details like this. You don’t write code to access an IMAP server or a POP server; you write code that speaks to the JavaMail API. Then the JavaMail API uses the service provider to speak to the server using its native protocol. This is middleware for email. All you need to do to add a new protocol is install the service provider’s JAR file. Simple, carefully designed programs that use only the core features of the JavaMail API may be able to use the new provider without even being recompiled. Of course, programs that make use of special features of individual protocols may need to be rewritten.

Since mail arrives from the network at unpredictable times, the JavaMail API relies on an event-based callback mechanism to handle incoming mail. This is exactly the same pattern (even using some of the same classes) found in the Swing and JavaBeans. The javax.mail.event package defines about half a dozen different kinds of mail events, as well as the associated listener interfaces and adapter classes for these events.

While many people still fondly recall the early days of ASCII email and even ASCII pictures, modern email messages contain a bewildering array of multilingual text and multimedia data encoded in formats such as Base64, quoted-printable, BinHex, and uuencode. To handle this, the JavaMail API uses the JavaBeans Activation Framework (JAF) to describe and display this content.

This book covers Version 1.5 of the JavaMail API. The JavaMail API is a standard extension to Java, not part of the core JDK or JRE class library, even in Java 8. (It is a standard part of Java Enterprise Edition (JEE)). Consequently, you’ll need to download it separately from Oracle and install it on your system. It’s freely available from Java. It comes as a JAR archive named javax.mail.jar. This file contains the actual .class files that implement the JavaMail API. To compile or run the examples in this book, you’ll need to add this file to your class path, either by adding its path to the CLASSPATH environment variable or by placing javax.mail.jar in your jre/lib/ext directory.

If you’re using Java 5, you will also need to install the JavaBeans Activation Framework. (It’s bundled with the JDK starting in Java 6.) You can download it from Oracle’s website. This download contains the activation.jar archive, which you’ll also need to place in your class path.

Finally, you may want to add some additional providers. Oracle’s implementation includes POP3, SMTP, Gmail, and IMAP providers. However, third parties have written providers for other protocols such as Hotmail, NNTP, Exchange, and more. Table 1-1 lists some of these.

Table 1-1. Mail providers
Product (company)URLProtocolsLicense

JavaMail (Oracle)


GPL with Classpath Exception

J-Integra Exchange: (Intrinsyc Software)

Microsoft Exchange (DCOM)


exJello: (Eric Glass)

Microsoft Exchange (WebDAV)

MIT License

ICE MH JavaMail Provider (ICE Engineering, Inc.)


Public domain

POPpers (Y. Miyadate)



JDAVMail (Luc Claes)

Hotmail (WebDAV)


GNU JavaMail (FSF)

POP3, NNTP, SMTP, IMAP, mbox, maildir

GPL with library exception

mbox Store (Oracle)


Get JavaMail API now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.