Receiving Mail with POP3

Unlike IMAP4, POP3 only receives mail. IMAP4 provides the capabilities of POP3 along with the ability to move messages back and forth between client and server, and manage mailboxes on the server. For information about IMAP4, see Chapter 4, "Receiving Mail with IMAP4."

POP3 commands use the ASCII character set. They are made up of a keyword, followed by any parameters the command has, and ending with "<CRLF>.<CRLF>." Commands are line-oriented and can return a single or multi-line response.

For detailed information about POP3, see RFC 1939: "Post Office Protocol - Version 3."

[Top]

POP3 Session States

A POP3 session progresses through three stages, or states. Within each state, only certain commands are possible.

Figure 5.1 POP3 Session States

Table 5.1 POP3 Session States and Commands

Session State Commands
Authorization
User login, password approval, quit. Commands: USER, PASS, QUIT

Transaction
Operations involving messages. Commands: STAT, LIST, RETR, DELE, NOOP, RSET, TOP, UIDL

Update
Delete any marked messages. The session enters this state after a QUIT command, deletes messages marked for deletion, then quits. Commands: QUIT

For a table of SDK-supported POP3 protocol commands that lists the state in which each can be called, see Supported POP3 Internet Protocol Commands. For detailed information about POP3 and POP3 session states, see POP3 RFCs.

Session State	Commands
Authorization	User login, password approval, quit. Commands: USER, PASS, QUIT
Transaction	Operations involving messages. Commands: STAT, LIST, RETR, DELE, NOOP, RSET, TOP, UIDL
Update	Delete any marked messages. The session enters this state after a QUIT command, deletes messages marked for deletion, then quits. Commands: QUIT

[Top]

POP3 Response Codes

When a client sends a POP3 command, a text response code is returned with descriptive text. The response can either be single- or multi-line.

Table 5.2 POP3 Response Types

Response Type Response Code and Description
Single line
+OK (Success), followed by descriptive text, for example,
"+OK message deleted" for the delete operation. Responses are mapped to appropriate callbacks.
-ERR (failure), followed by descriptive text, for example,
"-ERR no such message" for the delete operation. Mapped to error callback.

Multi-line
First line: Like single-line response:
+OK (Success), followed by descriptive text, for example,
"+OK message follows" for the retrieve operation. Responses are mapped to appropriate callbacks.
-ERR (failure), followed by descriptive text, for example,
"-ERR no such message" for the retrieve operation. Mapped to error callback.

Subsequent lines: More information about the condition.

Final line: . (dot) and <CRLF>. (Not considered part of the response.)
Note: If an error occurs on a multi-line response, a single line is returned.

For a list of functions and their associated callbacks, see POP3 Callback Mapping.

Response Type	Response Code and Description
Single line	+OK (Success), followed by descriptive text, for example, `"+OK message deleted"` for the delete operation. Responses are mapped to appropriate callbacks. -ERR (failure), followed by descriptive text, for example, `"-ERR no such message"` for the delete operation. Mapped to `error` callback.
Multi-line	First line: Like single-line response: +OK (Success), followed by descriptive text, for example, `"+OK message follows"` for the retrieve operation. Responses are mapped to appropriate callbacks. -ERR (failure), followed by descriptive text, for example, `"-ERR no such message"` for the retrieve operation. Mapped to `error` callback.
	Subsequent lines: More information about the condition.
	Final line: . (dot) and `<CRLF>`. (Not considered part of the response.) Note: If an error occurs on a multi-line response, a single line is returned.

[Top]

Steps in a POP3 Session

Generally, a messaging application follows these steps when using POP3 to receive mail. These steps are listed below with links to more detailed descriptions.

Step Section with details
Initialize the response sink.
Creating a Response Sink

Create a client.
Creating a Client

Connect to the server.
Connecting to a Server

Log in to the server.
Logging In

Get the message count.
Getting Message Count

List messages on the server.
Listing Messages

Retrieve the message headers.
Retrieving Message Headers

Retrieve messages themselves.
Retrieving a Message

End the POP3 session.
Ending the Session

Step	Section with details
Initialize the response sink.	Creating a Response Sink
Create a client.	Creating a Client
Connect to the server.	Connecting to a Server
Log in to the server.	Logging In
Get the message count.	Getting Message Count
List messages on the server.	Listing Messages
Retrieve the message headers.	Retrieving Message Headers
Retrieve messages themselves.	Retrieving a Message
End the POP3 session.	Ending the Session

[Top]

POP3 in the Messaging Access SDK

The POP3 class hierarchy is made up of the following classes.

netscape.messaging.pop3.IPOP3Sink. Interface for the POP3 response sink. See Creating a Response Sink.

netscape.messaging.pop3.POP3Client. Represents the POP3 client. See Creating a Client.

netscape.messaging.pop3.POP3Sink. Implementation of the IPOP3Sink interface. See Creating a Response Sink.

netscape.messaging.pop3.POP3Exception. Exception thrown when an POP3 API error condition is detected by the Messaging Access SDK. Extends IOException.

netscape.messaging.pop3.POP3ServerException. Exception thrown from the error callback on the response sink when the server sends an error. Extends IOException and POP3Exception.

[Top]

POP3 Callback Mapping

Callbacks are associated with many POP3 methods. For general information about the response sink and callbacks, see SDK Sink Classes for Java.

The IPOP3Sink interface contains callbacks for each client call. The client's processResponses method invokes the interface method that corresponds to the client call. Methods with multi-line responses map to more than one callback. The first type of callback indicates the start of a notification. The second type passes back multi-line data. The third type of callback provides a notification that the operation is complete.

If a server error occurs, the error callback is invoked.

Table 5.3 shows which POP3 methods are mapped to callbacks in the IPOP3Sink interface. Table 5.4 shows methods that do not map to callbacks.

Table 5.3 Methods with Callbacks

POP3Client Methods Possible Callbacks on IPOP3Sink
connect
connect, error

delete
dele, error

list
listStart, list, listComplete, error

noop
noop, error

pass
pass, error

quit
quit, error

reset
reset, error

retrieve
retrieveStart, retrieve,
retrieveComplete, error

sendCommand
sendCommandStart, sendCommand, sendCommandComplete, error

stat
stat, error

top
topStart, top, topComplete, error

uidList
uidListStart, uidList,
uidListComplete, error

user
user, error

xAuthList
xAuthListStart, xAuthList,
xAuthListComplete, error

xSender
xSender, error

Table 5.4 Methods without Callbacks

`POP3Client` Methods	Possible Callbacks on `IPOP3Sink`
connect	connect, error
delete	dele, error
list	listStart, list, listComplete, error
noop	noop, error
pass	pass, error
quit	quit, error
reset	reset, error
retrieve	retrieveStart, retrieve, retrieveComplete, error
sendCommand	sendCommandStart, sendCommand, sendCommandComplete, error
stat	stat, error
top	topStart, top, topComplete, error
uidList	uidListStart, uidList, uidListComplete, error
user	user, error
xAuthList	xAuthListStart, xAuthList, xAuthListComplete, error
xSender	xSender, error

Methods Without Callbacks
disconnect

processResponses

setChunkSize

setResponseSink

setTimeout

[Top] [POP3 Callback Mapping]

Methods Without Callbacks
disconnect
processResponses
setChunkSize
setResponseSink
setTimeout

Creating a Response Sink

The first step in starting a POP3 session is to create the POP3 response sink, which is defined in the IPOP3Sink interface. The response sink contains the callback methods for the POP3 client. For general information about the response sink, see SDK Sink Classes for Java.

The IPOP3Sink interface contains callbacks for each client call. You must implement this interface in order to use the POP3 client object. The constructor for the POP3Client class takes an IPOP3Sink object as a parameter.

To implement your own response sink class, you can extend the IPOP3Sink interface, using this syntax:

public class newIPOP3Sink extends Object 
   implements IPOP3Sink

As a convenience, the Messaging SDK provides the POP3Sink class, which implements the IPOP3Sink interface. POP3Sink implements all the interfaces in IPOP3Sink. By default, the implementation does nothing, except for the error callback, which throws an exception. You can save a step by extending this class, using this syntax:

public class newPOP3Sink extends IPOP3Sink{
   }

The following section of code creates a response sink.

POP3Sink l_pop3Sink;

l_pop3Sink = new POP3Sink();

After you create the response sink, the next step is Creating a Client.

[Top]

Creating a Client

The POP3 client uses a POP3Client object to communicate with the server. To create the POP3Client object and set the response sink for the client's use, call the POP3Client.POP3Client class constructor, which takes an existing response sink. Use this syntax:

public POP3Client(IPOP3Sink in_sink)

The client class must implement all of the methods in the IPOP3Sink interface.

The following section of code creates a client.

/* Create sink first as described in Creating a Response Sink */

POP3Client l_client;

l_client = new POP3Client( l_pop3Sink );

After you initialize the client, the next step is Connecting to a Server.

[Top]

Connecting to a Server

Before receiving mail, the client must connect with the server through a service port. To connect to the server, call either of two POP3Client connect methods, depending on whether or not you want to specify the connection port. The SDK methods perform some error-checking.

To connect to the server using the default port for the POP3 protocol (port 110), use this form of connect and supply the identifier of the server:

public synchronized void connect(String in_server) 
                                 throws IOException

To specify the server port to use for the server connection, use this form of connect:

public synchronized void connect(String in_server,
                     int in_port) throws IOException

NOTE: For the callback mapping for these methods, see POP3 Callback Mapping. §

The following section of code connects the client to the server.

/* After Creating a Response Sink and Creating a Client */

l_client.connect( "pop3server.com" );

l_client.processResponses();

After connecting to the server, the next step is Logging In.

To disconnect the client from the server and close the socket connection, use this POP3Client class method:

public synchronized void disconnect() throws IOException

You could use this method as part of a Cancel operation while retrieving a message. Remember that you do not call processResponses after disconnect.

[Top]

Logging In

Once the client is connected to the server, the user can log in. Login identifies the client to the server. Logging in requires the identifier of the POP3 client, as well as the user's ID and plain text password.

First, call POP3Client.user and give the name of the user's maildrop or mailbox:

public synchronized void user(String in_user) throws IOException

This method sends the USER POP3 protocol command.

To submit the user password, call the POP3Client.pass method:

public synchronized void pass(String in_password) 
                              throws IOException

This method sends the PASS POP3 protocol command.

While these commands execute, the session is in Authorization state. Successful completion moves the session to the Transaction state. For a list of states and commands that can be executed in each state, see POP3 Session States.

A successful login moves the POP3 session from the Authorization state to the Transaction state, where the user can perform a number of operations.

NOTE: For the callback mapping for these methods, see POP3 Callback Mapping. §

The following section of code shows a login sequence for a user.

/* User id sequence */

l_client.user( "pop3user" );

l_client.processResponses();

/* Password sequence */

l_client.pass( "pop3password" );

l_client.processResponses();

After you log in, you can perform any Transaction state operations. The next step is Retrieving a Message.

[Top]

Getting Message Count

In the POP3 Transaction state, the client can find out how many messages are present by requesting the status of the mail drop or mailbox. The POP3Client.status method gets the mailbox status for a given client by issuing the STAT protocol command.

The POP3Client.status method gets mailbox status for a given mailbox:

public synchronized String status(String in_mailbox,
                     String in_statusData) throws IOException

The status returned includes the number of messages present and the octet size of the mail drop.

NOTE: For this method's callback mapping, see POP3 Callback Mapping. §

The following section of code requests the status of the mail drop.

l_client.stat();

l_client.processResponses();

[Top]

Listing Messages

To list messages while in the POP3 Transaction state, call either of two POP3Client.list methods, depending on whether you want to list all of the messages in a mailbox or a specific message.

To go through all the messages in the mailbox and generate a list of messages, use the list method that takes no parameters:

public synchronized void list() throws IOException

This method sends the LIST POP3 protocol command.

To list only the message specified by the message number, use this list method:

public synchronized void list(int in_messageNumber) 
                              throws IOException

Supply the message number as a parameter. This method sends the LIST [arg] POP3 protocol command.

NOTE: For the callback mapping for these methods, see POP3 Callback Mapping. §

The following section of code retrieves the email address of the sender along with authenticated messages.

l_client.list();

l_client.processResponses();

[Top]

Retrieving Message Headers

In the Transaction state, the user can preview mailbox contents or part of a long message before deciding to download it by listing the headers plus some of the lines of the body. The user (or the mail application) determines the number of message lines to retrieve.

To identify the message, supply the number of the message and the number of body lines to retrieve. Use the POP3Client.top method, which issues the TOP protocol command:

public synchronized void top(int in_messageNumber,
                            int in_lines) throws IOException

To retrieve all headers for a given mailbox, combine POP3Client.top with a call to POP3Client.stat. First, call stat to find the number of messages in the mailbox. When you get the number, for example, 10, call top once, passing each message number in turn, until you get to the total (in this case, 10). For the in_lines parameter, use a value of 0 so that no body lines are returned.

NOTE: For this method's callback mapping, see POP3 Callback Mapping. §

The following section of code lists the header of the message specified by its message number. It retrieves no body lines.

l_client.top( 1, 0 );

l_client.processResponses();

After you retrieve message headers, you can go on to Retrieving a Message if you like.

[Top]

Retrieving a Message

Retrieving a message is one of the most common activities that users want to perform during the POP3 Transaction state.

The POP3Client.pop3_retrieve method takes the identifier of the POP3 client that is retrieving the mail and the message number, and retrieves the contents of the message:

public synchronized void retrieve(int in_messageNumber) 
                                  throws IOException

The message is returned in the form of data chunks, which are sent to the application through callbacks. The pop3_retrieve method issues a RETR command. It fails if the message with the specified number does not exist.

NOTE: For this method's callback mapping, see POP3 Callback Mapping. §

The following section of code retrieves the contents of a message.

l_client.retrieve( 1 );

l_client.processResponses();

[Top]

Ending the Session

When it is time to end the session, the client should call POP3Client.quit to notify the server:

public synchronized void quit() throws IOException

This method sends the QUIT POP3 protocol command. The server closes the TCP connection and sends back a response. It is preferable to end a session with quit instead of just closing the connection.

If the session is in the Authentication state when this method is called, the server simply closes the connection. If the session is in the Transaction state, the server goes into the Update state and expunges any messages marked for deletion, and then quits.