1

6th Semester Project Report

Indian Institute of Information Technology, Allahabad
 2

Candidates Declaration
I hereby declare that the work presented in this project entitled
“LucidMail - POP3/SMTP/IMAP4 Mail API”, submitted towards
completion of Mini Project in 6th Semester of B.Tech (I.T) at Indian
Institute of Information Technology, Allahabad is an authentic
record of my work carried out under guidance of Dr. Hema Bindu.

Saumitra Agarwal
(2001199)
May 18, 2004

Certificate

This is to certify that the work contained in the report titled

“LucidMail - POP3/SMTP/IMAP4 Mail API” by Saumitra Agarwal has
been carried out under my supervision. The student was found to
be hardworking, ardent and devoted to the project.

Dr. Hema Bindu

IIIT Allahabad
May 18, 2004
 3

Table of Contents
TABLE OF CONTENTS..................................................................................3

ABSTRACT.....................................................................................................4

ACKNOWLEDGEMENT.................................................................................5

INTRODUCTION.............................................................................................6

STUDY OF EXISTING UA SYSTEMS............................................................7

DESIGN CRITERIA.........................................................................................8

IMPLEMENTATION......................................................................................10

IMPLEMENTATION......................................................................................14

IMPLEMENTATION......................................................................................15

IMPLEMENTATION......................................................................................16

MAIL TRANSFER PROCESS......................................................................17

PLATES.........................................................................................................18

PLATES.........................................................................................................19

REFERENCES.............................................................................................20

APPENDIX....................................................................................................21

APPENDIX....................................................................................................22
 4

Abstract
LucidMail is a simple yet comprehensive Java based Mail API. It
can be used for both sending and retrieving Emails. LucidMail uses
SMTP (Simple Mail Transfer Protocol, RFC 2821) for sending
Emails. It supports POP3 (Post Office Protocol 3, RFC 1939) and
IMAP4 (Internet Message Access Protocol - Version 4rev1, RFC
3501) protocols and either can be used for retrieving Emails,
depending upon the server support.

The utility of LucidMail lies in the fact that it is purely Java based.
Therefore, it can be used on any platform for which a Java Virtual
Machine is available. As of now, it has been tested over Windows
XP and Linux (RH8, RH9).
 5

Acknowledgement

I would like to extend my gratitude to my Project Guide Dr. Hema

Bindu, who encouraged me to take this project.

I am also thankful to Sun Microsystems for creating such a

wonderful programming language as Java, which allows the
programmers to concentrate on job at hand. At the same time I
express my gratitude to the Network Protocol designers who gave
such simple and precise descriptions of the IMAP, POP3 and SMTP
Protocol suites. (RFC’s 3501, 0821, 0822, 2554, 2821, 1939).

In the end I would like to thank the IIITA administration for

providing excellent labs and infrastructure, which enabled me to
put a whole hearted effort.

Saumitra Agarwal
Tuesday, May 18, 2004
 6

Introduction
Simple Mail Transfer Protocol (SMTP)
The Internet standard protocol for transferring electronic mail
messages from one computer to another. SMTP specifies how two
mail systems interact and the format of control messages they
exchange to transfer mail. Specified by RFC 2821.

Post Office Protocol (POP)

A protocol designed to allow single user computers to retrieve
electronic mail from a POP server. The POP server might be a
computer with a permanent Internet connection whereas its clients
might only connect to it occasionally, e.g. by modem. Specified by
RFC 1939.

Internet Message Access Protocol (IMAP)

A protocol allowing a client to access and manipulate electronic
mail messages on a server. It permits manipulation of remote
message folders (mailboxes), in a way that is functionally
equivalent to local mailboxes. IMAP includes operations for
creating, deleting, and renaming mailboxes; checking for new
messages; permanently removing messages; searching; and
selective fetching of message attributes, texts, and portions
thereof. It does not specify a means of posting mail; this function
is handled by a mail transfer protocol such as SMTP.
 7

Study of existing UA Systems

Some existing Mail User Agents (MUA) or Email Clients are

• Microsoft Windows:
o Microsoft Outlook Express
o Eudora
o Pegasus Mail

• Linux:
o Kmail
o Pine

Apart from Pine, which is a text based MUA, rest of the Email
Clients provide a Graphical User Interface. Though these clients
are quite powerful, and implement most of the POP3 and IMAP4
specifications, they are all tied to a specific platform. That is to
say, that Microsoft Outlook Express runs only on Microsoft
Windows and Kmail runs only on Linux. This creates a problem for
users (like me), who use different Operating Systems on a day to
day basis. Such users have to use/purchase different Email Clients
for different Operating Systems. LucidMail is a pure Java solution
to this problem. It can be used to develop platform independent
Email Clients in Java programming language.
 8

Design Criteria
The design of LucidMail is such that the API and the Client
application are not tied together. From a programmer’s point of
view, this means that the API can be used as a building block for
creating a completely different and more robust Email application.
LucidMail client is hence a simple Swing based Email client,
developed with the sole purpose of demonstrating the power of
LucidMail API.

LucidMail uses a set of abstract classes defining objects that

comprise a mail system. The API defines classes like Message,
Account and Transport which can be extended and subclassed to
add new functionality or support for new protocols when
necessary. LucidMail uses concrete subclasses of these abstract
classes, to support widely used Internet mail protocols and
conform to RFC specifications. Classes such as POP3Connection,
IMAPConnection, SMTPTransport and EmailAddress provide actual
Protocol specific implementations.
 9

LucidMail Client AnyOtherMail Client

LucidMail API
 10

Implementation
LucidMail layered architecture
The Abstract Layer declares classes, interfaces and abstract
methods intended to support mail handling functions that all mail
systems support. These elements are subclassed and extended to
interface with message access and message transport protocols as
necessary. This layer includes classes such as Address, Transport,
Connection, TransportListener etc.

The Implementation Layer implements the abstract layer, and

provides at least one concrete implementation for each class in the
abstract layer. The classes in this layer are EmailAddress,
SMTPTransport, POP3Connection, POP3Account,
SMTPTransportListener etc.

The third layer, The User Interface Layer/Application Layer is the

one visible to the user. This layer provides a simple and intuitive
Graphical User Interface to the user. This layer includes classes
NewMessage, LucidMailClient etc, which collect data from the user
through a GUI, construct corresponding mail objects and then call
appropriate Implementation Layer methods.
 11

Implementation

Major LucidMail API components

1. The Message Class

The Message class is an abstract class that defines a set of
attributes and content for a mail message. Attributes of the
Message class specify addressing information and define the
structure of the content, including the content type and To,
Subject, Reply-To, and other attributes necessary for message
routing via a message transport system. Message can be
subclassed to support specific message implementations (for
example, MIME messages). The content of a message is a
collection of bytes, encapsulated within a Message object. These
bytes are stored in the messageText field of the message. Simple
methods like setFrom, setReplyTo, setText, setRecipients are
provided to manipulate the Message object.

Currently only one concrete implementation of message

TextMessage is provided. TextMessage can be used to send Plain-
text messages. MIME support is yet to be written. TextMessage
also provides parsing methods, which can be used to parse a text
stream to a Message object.

2. The Address Class

The Address class represents email addresses. The Address class is
an abstract class. Subclasses provide implementation-specific
semantics.

EmailAddress is a concrete subclass which provides support for

RFC822 standard Email addresses.

3. The Session Class

A mail Session object manages the configuration options and user
authentication information used to interact with messaging
 12

systems. Session is a concrete class. Different sessions can be

created by using different instances of Session. Each Session
object has a corresponding Transport which can be retrieved using
the getTransport

Implementation

method. A session is specified by user name, password, and

remote server. Hence, a user can create a Session with IIITA-mail
and Yahoo Mail simultaneously. Both these Session’s will be
mutually exclusive, and will be created in separate threads for
efficiency.

4. The Transport Class

The Transport abstract class defines the message submission and
transport protocol. Subclasses of the Transport class implement
SMTP and other transport protocols. A Transport object is closely
linked with a Session object, and a Transport instance should be
obtained by using getTransport method of Session. Transport
provides methods to connect to the specific MTA, and semantics of
sending mail according to the particular protocol instance.

Transport also supports adding transport listener which can be

used to ‘listen’ to the actual Transport process. All such listeners
must be a subclass of TransportListener.

SMTPTransport is an implementation of Transport for SMTP

Protocol (RFC 821, RFC 2821). A SMTPTransportListener can be
used to ‘listen’ to the actual transport process. Plate 3 shows a
specific transport session output, captured using a
SMTPTransportListener and outputting it to the console.

5. The Connection Class

Connection is an abstract class, it is used for actual reading and
writing to the Socket input and output stream. A specific
implementation provides the actual reading and writing methods.
 13

A concrete subclass of Connection is the POP3Connection class.

POP3Connection provides reading and writing methods for
communication with a POP3 server.

6. The Account Class

Messages are contained in Folders. New messages are usually
delivered to folders by a transport protocol or a delivery agent.
Clients

Implementation

retrieve messages from folders using an access protocol. Account

represents a handle to a message store on a mail server. It can be
used to check, retrieve or delete messages from the message
store.
Implementation

Account is an abstract class, so specific implementation need to be

created for different message stores (i.e. POP3, IMAP4 etc.)

POP3Account is an implementation of Account class. It provides all

methods to read and delete messages from a POP3 server.
IMAP4Account is the corresponding implementation for IMAP4
protocol.
 14

Implementation

Conformation to RFC standards

SMTP
The SMTPTransport class is a Transport implementation that
conforms to RFC 0821, and RFC 2821. The supported commands
are

• DATA
• EHLO
• HELO
• HELP
• MAIL
• NOOP
• QUIT
• RCPT
• RSET

The timeout period for each command is as defined by RFC 2821.

For example, timeout for DATA command is constant
SMTPTransport.DATA_TIMEOUT which is equal to 2 minutes.

The headers conform to RFC 822 standard. They can be set by

using setXxx method of the SMTPTransport class. The currently
supported header fields are

• From
• To
• Cc
• Bcc
• Reply-To
• Date
• Subject

Rest of the headers (like Received), are set by the Mail Transfer
Agent.
 15

Implementation

POP3
The POP3Account class is a POP3 store implementation and it
conforms to RFC 1939. The supported commands are:

• AUTHERIZATION State
o QUIT
• TRANSACTION State
o STAT
o LIST
o RETR
o DELE
o RSET
• UPDATE State
o QUIT
• Optional Commands
o USER
o PASS
o APOP

Both Plain-text and secure authentication using CRAM-MD5 are

supported. CRAM-MD5 authentication is a simple
Challenge/Response mechanism and is described in RFC 2195. The
MD5 Algorithm conforms to its RFC 1321 specification.
 16

Implementation

IMAP4
The IMAP4Account class is a IMAP4 store implementation and it
conforms to RFC 3501. The supported commands are:

• Not Authenticated State

o LOGIN
• Authenticated State
o SELECT
o CREATE
o DELETE
o RENAME
o LOGOUT
• Selected State
o CLOSE
o FETCH

This class uses an instance of IMAP4Connection class to read from

and write to the Socket stream.
 17

Mail Transfer Process

User User

UA UA
(RottenMail Client) (LucidMail Client)

POP3 IMAP IMAP POP3

SMTP MTA
MTA (mail.iiita.ac.in)
(mx1.mail.yahoo.com)

SMTP SMTP

SMTP
MTA MTA
(mx1.mail.yahoo.com) (mx1.mail.yahoo.com)
 18

Plates
Screenshot 1: LucidMail Client (Windows XP
Look)
The active window is the one for sending mails. Background shows
the INBOX.
 19

Plates
Screenshot 2: New Message window (Java
look)
Clicking the Send button sends the message
 20

References
1. J. Klensin - “Simple Mail Transfer Protocol”, RFC 2821
2. Jonathan B. Postel – “Simple Mail Transfer Protocol”, RFC
821
3. David H. Crocker - “Standard For The Format Of Arpa
Internet Text Messages”, RFC 822
4. J. Myers – “SMTP Service Extension for Authentication”, RFC
2554
5. J. Myers, M. Rose - “Post Office Protocol - Version 3”, RFC
1939
6. J. Klensin, R. Catoe, P. Krumviede - “IMAP/POP AUTHorize
Extension for Simple Challenge/Response”, RFC 2195
7. R. Rivest - “The MD5 Message-Digest Algorithm”, RFC 1321
8. M. Horowitz , S. Lunt - “FTP Security Extensions”, RFC 2228
9. http://java.sun.com/reference/api/index.html
 21

Appendix
Sample SMTP Session
S: 220 mail.iiita.ac.in ESMTP
C: EHLO CF335
S: 250-mail.iiita.ac.in
S: 250-AUTH LOGIN PLAIN
S: 250-AUTH=LOGIN PLAIN
S: 250-STARTTLS
S: 250-PIPELINING
S: 250 8BITMIME
C: MAIL FROM: <Saumitra <saumitra@gmail.com>>
S: 250 ok
C: RCPT TO: <saumitra@iiita.ac.in>
S: 250 ok
C: RCPT TO: <montoo@iiita.ac.in>
S: 250 ok
C: DATA
S: 354 go ahead
C: From:Saumitra <saumitra@gmail.com>
C: To:saumitra@iiita.ac.in
C: Bcc:montoo@iiita.ac.in
C: Date:19 May 2004 00:53:27 +0100
C: Subject:Test Mail
C:
C: Hi,
C: the first test mail. Lets see it the Bcc header is transferred
or not.
C: regards,
C: Saumitra
C: .
S: 250 ok 1084907737 qp 2081
C: QUIT
S: 221 mail.iiita.ac.in
 22

Appendix

Sample POP3 Session

S: +OK Hello there.
C: USER sagarwal_01@iiita.ac.in
S: +OK Password required.
C: PASS saumitra
S: +OK logged in.
C: STAT
S: +OK 70 4078499
C: LIST 69
S: +OK 69 1016
C: RETR 69
S: +OK 1016 octets follow.
S: Return-Path: <"Saumitra <saumitra"@gmail.com>
S: Delivered-To: iiita_ac_in-sagarwal_01@iiita.ac.in
S: Received: (qmail 1589 invoked by uid 7797); 18 May 2004 19:05:13
-0000
S: Delivered-To: iiita_ac_in-saumitra@iiita.ac.in
S: Received: (qmail 1576 invoked by uid 7798); 18 May 2004 19:05:13
-0000
S: Received: from Saumitra <saumitra@gmail.com by ccr29 by uid 7791
with qm
canner-1.21
S: (clamdscan: 0.70. spamassassin: 2.44.
Clear:RC:0(172.16.3.232):SA:0(0.
):.
S: Processed in 1.16787 secs); 18 May 2004 19:05:13 -0000
S: X-Spam-Status: No, hits=0.8 required=5.0
S: Received: from unknown (HELO CF335) (172.16.3.232)
S: by ccr29.local with SMTP; 18 May 2004 19:05:12 -0000
S: From:Saumitra <saumitra@gmail.com>
S: To:saumitra@iiita.ac.in
S: Bcc:montoo@iiita.ac.in
S: Date:19 May 2004 00:43:03 +0100
S: Subject:Test Mail
S: X-Qmail-Scanner-Message-ID: <10849071126611566@ccr29>
S:
S: hi,
S: this is a test mail to demonstrate LucidMail API and Lucid Mail
Client.
S: How does it look. Does'nt it look fine!!!
S: regards,
S: Saumitra
S: (Montoo)
S: .
C: QUIT
S: +OK Bye-bye.