Fundamentals of the JavaMail API
Presented by developerWorks, your source for great tutorials
ibm.com/developerWorks
Table of Contents
If you're viewing this document online, you can click any of the topics below to link directly to that section.
1. Tutorial tips 2
2. Introducing the JavaMail API 3
3. Reviewing related protocols 4
4. Installing JavaMail 6
5. Reviewing the core classes 8
6. Using the JavaMail API 13
7. Searching with SearchTerm 21
8. Exercises 22
9. Wrapup 32
Fundamentals of the JavaMail API Page 1
Section 1. Tutorial tips
Should I take this tutorial?
Looking to incorporate mail facilities into your platform-independent Java solutions? Look no
further than the JavaMail API, which offers a protocol-independent model for working with
IMAP, POP, SMTP, MIME, and all those other Internet-related messaging protocols. With
the help of the JavaBeans Activation Framework (JAF), your applications can now be
mail-enabled through the JavaMail API.
Concepts
After completing this module you will understand the:
* Basics of the Internet mail protocols SMTP, POP3, IMAP, and MIME
* Architecture of the JavaMail framework
* Connections between the JavaMail API and the JavaBeans Activation Framework
Objectives
By the end of this module you will be able to:
* Send and read mail using the JavaMail API
* Deal with sending and receiving attachments
* Work with HTML messages
* Use search terms to search for messages
Prerequisites
Instructions on how to download and install the JavaMail API are contained in the course. In
addition, you will need a development environment such as the JDK 1.1.6+ or the Java 2
Platform, Standard Edition (J2SE) 1.2.x or 1.3.x.
A general familiarity with object-oriented programming concepts and the Java programming
language is necessary. The Java language essentials tutorial can help.
copyright 1996-2000 Magelang Institute dba jGuru
Contact
jGuru has been dedicated to promoting the growth of the Java technology community
through evangelism, education, and software since 1995. You can find out more about
their activities, including their huge collection of FAQs at jGuru.com . To send feedback
to jGuru about this course, send mail to producer@jguru.com .
Course author: Formerly with jGuru.com , John Zukowski does strategic Java
consulting for JZ Ventures, Inc. His latest book is titled Java Collections from Apress .
Presented by developerWorks, your source for great tutorials
ibm.com/developerWorks
Fundamentals of the JavaMail API Page 2
Section 2. Introducing the JavaMail API
What is the JavaMail API?
The JavaMail API is an optional package (standard extension) for reading, composing, and
sending electronic messages. You use the package to create Mail User Agent (MUA) type
programs, similar to Eudora, pine, and Microsoft Outlook. The API's main purpose is not for
transporting, delivering, and forwarding messages; this is the purview of applications such as
sendmail and other Mail Transfer Agent (MTA) type programs. MUA-type programs let users
read and write e-mail, whereas MUAs rely on MTAs to handle the actual delivery.
The JavaMail API is designed to provide protocol-independent access for sending and
receiving messages by dividing the API into two parts:
* The first part of the API is the focus of this course -- basically, how to send and receive
messages independent of the provider/protocol.
* The second part speaks the protocol-specific languages, like SMTP, POP, IMAP, and
NNTP. With the JavaMail API, in order to communicate with a server, you need a
provider for a protocol. The creation of protocol-specific providers is not covered in this
course because Sun provides a sufficient set for free.
Presented by developerWorks, your source for great tutorials
ibm.com/developerWorks
Fundamentals of the JavaMail API Page 3
Section 3. Reviewing related protocols
Introduction
Before looking into the JavaMail API specifics, let's step back and take a look at the protocols
used with the API. There are basically four that you'll come to know and love:
* SMTP
* POP
* IMAP
* MIME
You will also run across NNTP and some others. Understanding the basics of all the
protocols will help you understand how to use the JavaMail API. While the API is designed to
be protocol agnostic, you can't overcome the limitations of the underlying protocols. If a
capability isn't supported by a chosen protocol, the JavaMail API doesn't magically add the
capability on top of it. (As you'll soon see, this can be a problem when working with POP.)
SMTP
The Simple Mail Transfer Protocol (SMTP) is defined by RFC 821 . It defines the mechanism
for delivery of e-mail. In the context of the JavaMail API, your JavaMail-based program will
communicate with your company or Internet Service Provider's (ISP's) SMTP server. That
SMTP server will relay the message on to the SMTP server of the recipient(s) to eventually
be acquired by the user(s) through POP or IMAP. This does not require your SMTP server to
be an open relay, as authentication is supported, but it is your responsibility to ensure the
SMTP server is configured properly. There is nothing in the JavaMail API for tasks like
configuring a server to relay messages or to add and remove e-mail accounts.
POP
POP stands for Post Office Protocol. Currently in version 3, also known as POP3, RFC 1939
defines this protocol. POP is the mechanism most people on the Internet use to get their
mail. It defines support for a single mailbox for each user. That is all it does, and that is also
the source of a lot of confusion. Much of what people are familiar with when using POP, like
the ability to see how many new mail messages they have, are not supported by POP at all.
These capabilities are built into programs like Eudora or Microsoft Outlook, which remember
things like the last mail received and calculate how many are new for you. So, when using
the JavaMail API, if you want this type of information, you have to calculate it yourself.
IMAP
IMAP is a more advanced protocol for receiving messages. Defined in RFC 2060 , IMAP
stands for Internet Message Access Protocol, and is currently in version 4, also known as
IMAP4. When using IMAP, your mail server must support the protocol. You can't just change
your program to use IMAP instead of POP and expect everything in IMAP to be supported.
Assuming your mail server supports IMAP, your JavaMail-based program can take
Presented by developerWorks, your source for great tutorials
ibm.com/developerWorks
Fundamentals of the JavaMail API Page 4
advantage of users having multiple folders on the server and these folders can be shared by
multiple users.
Due to the more advanced capabilities, you might think IMAP would be used by everyone. It
isn't. It places a much heavier burden on the mail server, requiring the server to receive the
new messages, deliver them to users when requested, and maintain them in multiple folders
for each user. While this does centralize backups, as users' long-term mail folders get larger
and larger, everyone suffers when disk space is exhausted. With POP, saved messages get
offloaded from the mail server.
MIME
MIME stands for Multipurpose Internet Mail Extensions. It is not a mail transfer protocol.
Instead, it defines the content of what is transferred: the format of the messages,
attachments, and so on. There are many different documents that take effect here: RFC 822
, RFC 2045 , RFC 2046 , and RFC 2047 . As a user of the JavaMail API, you usually don't
need to worry about these formats. However, these formats do exist and are used by your
programs.
NNTP and others
Because of the split of the JavaMail API between provider and everything else, you can
easily add support for additional protocols. Sun maintains a list of third-party providers that
take advantage of protocols for which Sun does not provide out-of-the-box support. You'll
find support for NNTP (Network News Transport Protocol) [newsgroups], S/MIME (Secure
Multipurpose Internet Mail Extensions), and more.
Presented by developerWorks, your source for great tutorials
ibm.com/developerWorks
Fundamentals of the JavaMail API Page 5
