The JavaMail API
An Introduction

David Wallace Croft
Senior Intelligent Systems Engineer
Special Projects Division, Information Technology
Analytic Services, Inc. (ANSER)


The Caveats

The JavaMail API is currently in flux. Recent additions and changes have been made as recently as less than 3 weeks ago.

Discrepancies exist between the specification, javadocs, and implementation classes. You may have to regenerate the javadocs or use the javap utility.

The provided implementations in the beta from Sun currently only support SMTP (with MIME) and IMAP. NNTP and POP3 are not provided at this time to the best of my knowledge.

Many of the classes in the javax.mail.* hierarchy are redundant to classes that will become a standard part of the Java 1.2 core API. There will then be package name shifts and, most likely, incompatible changes.

Some of the functionality relies upon another emerging API, the JavaBeans Activation Framework. These classes are currently included with the beta JavaMail implementation for your convenience.

The Beauty

The JavaMail API allows you to instantly add the ability to manipulate e-mail and newsgroup messages to your Java applications with negligible programming effort.

The API allows for complete and correct (debugged) underlying implementations for all of the detailed multiple standards that govern these operations. Specifically, this includes Internet standards embodied in the numerous RFCs (Requests For Comments) and the interfaces to various proprietary mailing systems.

The API allows for hands-off extensibility. As new MIME-types and standards emerge, your applications will not break as this is abstracted away by the layering of the API over the implementation.

You no longer have to write your own classes for these functions and ship them with your application to the customer.

You no longer have to learn yet another unique third-party or in-house class library for dealing with e-mail or newsgroups.

Having recently written my own Java classes for e-mail and newsgroup manipulation, I can appreciate these points.

The JavaMail API represents a standardized, extensible platform for communicating, presenting, and manipulating all current and future Multimedia Internet Mail Extension (MIME) types.

The Applications

The Potential

Intelligent Mail and News Agents

E-mail "Push"

Archive Management


The Classes

A brief description of the key classes is presented. Relative to the number of new classes in the JavaMail API, this is a small sampling.


An abstract class encompassing the commonalities of all messages such as a sender and recipients.

Non-standard message meta-information (headers) can be added using name-value pairs.

Messages are lightweight: they are "filled on demand" whenever the access methods (getter and setter) are called.


Your standard Internet message with support for inserting an unlimited number of multiple MIME body part attachments.

Ready to use.


An abstract class which allows you to manipulate hierarchial stores of varying implementations using a layered approach.

Flags for common "folder" status information such as newsgroup subscription options and new message count.

Folders can contain Messages and sub-Folders.

Folders can be created, deleted, expunged, etc., etc.

Event listeners can detect changes such as the arrival of new mail.


An abstract class representing an object database of Messages.

Includes methods to open and close connections to the Store.

Store event listeners can be added and removed.


A final class which defines a connection to a Store.

Includes authentication options.


An abstract class with information and functionality for the protocol used by a Session connection to a Store.

Examples: SMTP, IMAP, NNTP, POP3, etc.

Extensible with the installation of new classes.

Allows for fallback to default protocol implementations.

Events inform listeners of failures and successes such as disconnections.

The Search Package

Allows for boolean criteria search on major fields such as message subject, addresses, dates, body text, etc.

Search field classes extend the SearchTerm class and are used with common AND, OR, and NOT classes through interface methods.

Specific implementations can provide for a variety of optimized search and match algorithms.

Store and Search may have other applications outside of manipulating messages. Example: running queries against a search engine.

The JavaBeans Activation Framework

The JavaBeans Activation Framework (JAF) is an emerging standard for runtime extensibility.

It allows a client to determine at runtime how a content type can be manipulated by the user (edit, view, print, etc.).

Associates with each MIME type a customized JavaBean that uses the JAF DataHandler class.

As new MIME types for video, audio, images, and 3D worlds emerge, the user will be able to use his old mail browser to view and interact with them by the simple installation of a new Bean.

The available Beans are currently limited: text and images. A likely near-term future candidate is a Bean for text/html. Other implementations will be provided by third-party vendors or will need to be created by the developer.

The Security

Access to mail and newsgroup servers can be controlled by a username and password authentication process. Once the user is verified, all user applications in the same virtual machine can automatically become recognized at the option of the developer.

A future version of the JavaMail API will provide support for digitally signed and encrypted messages.

Security features will rely heavily upon Java 1.2 security features.

Example Code

The JavaMail API comes with the source code for numerous examples.

Here is another example, fairly simple, for you that has been sucessfully compiled and tested.

import java.util.Properties;
import javax.mail.*;
import javax.mail.internet.*;

* <P>
* Relies upon the JavaMail API.
* <P>
* @author
*   <A HREF="">David W. Croft</A>
* @version
*   1998-01-20

public final class  SMTPMail {

public static final String  TEST_HOST    = "";
public static final String  TEST_FROM    = "";
public static final String  TEST_TO      = "";
public static final String  TEST_SUBJECT = "SMTPMail Test";
public static final String  TEST_MESSAGE = "This is a test.";


* Command line arguments:  host, from, to, subject, message.
* Will use TEST constants if arguments are not provided.
public static final void  main ( String [ ]  args )
  throws AddressException, MessagingException
  String  host    = ( args.length < 1 ? TEST_HOST    : args [ 0 ] );
  String  from    = ( args.length < 2 ? TEST_FROM    : args [ 1 ] );
  String  to      = ( args.length < 3 ? TEST_TO      : args [ 2 ] );
  String  subject = ( args.length < 4 ? TEST_SUBJECT : args [ 3 ] );
  String  message = ( args.length < 5 ? TEST_MESSAGE : args [ 4 ] );

  send ( host, from, to, subject, message );

public static void  send (
  String  mail_server_host,
  String  email_from,
  String  email_to,
  String  subject,
  String  message )
  throws AddressException, MessagingException
  send (
    ( Authenticator ) null,
    new InternetAddress [ ] { new InternetAddress ( email_from ) },
    new InternetAddress [ ] { new InternetAddress ( email_to   ) },
    ( InternetAddress [ ] ) null,
    ( InternetAddress [ ] ) null,
    message );
public static void  send (
  String               mail_server_host,
  Authenticator        authenticator,
  InternetAddress [ ]  addresses_from,
  InternetAddress [ ]  addresses_to,
  InternetAddress [ ]  addresses_cc,
  InternetAddress [ ]  addresses_bcc,
  String               subject,
  String               message )
  throws MessagingException
  Properties  properties = new Properties ( );
  properties.put ( "", mail_server_host );
  MimeMessage  msg = new MimeMessage (
    Session.getInstance ( properties, authenticator ) );

  msg.addFrom ( addresses_from );
  msg.setRecipients ( Message.RecipientType.TO , addresses_to  );
  msg.setRecipients ( Message.RecipientType.CC , addresses_cc  );
  msg.setRecipients ( Message.RecipientType.BCC, addresses_bcc );
  msg.setSubject ( subject );
  msg.setText ( message );

  Transport.send ( msg );

private  SMTPMail ( ) { }


This is an example of what is received. Depending on the mail reader client used, the user may not see all of this.

Received: from nexos ( [])
        by (8.8.7/8.8.5) with SMTP id CAA11302
        for ; Tue, 20 Jan 1998 02:47:24 -0500 (EST)
Received: from by nexos (SMI-8.6/SMI-SVR4)
        id CAA08015; Tue, 20 Jan 1998 02:49:15 -0500
Date: Tue, 20 Jan 1998 02:49:15 -0500
Message-Id: <199801200749.CAA08015@nexos>
Subject: SMTPMail Test
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
X-UIDL: 2f7efb090bea9661a7358ce162bffe15
X-Mozilla-Status: 8001

This is a test.

An extended example of how to attach an HTML web page to an e-mail message is also available.


The home for the specification (86 pages of clear, concise, must-read material), a downloadable implementation, and the API javadoc.

JavaBeans Activation Framework
JAF (project name Glasgow) is currently in development.
A compiled and tested class which can send e-mail messages with web page attachments.

David Wallace Croft,
© 1998 Analytic Services, Inc. (ANSER)
Posted 1998-01-20.