The commands used to retrive mail from a POP3 server by an email client are a series of text commands with single line responses from the mail server. The commands and examples used here are defined by RFC 1939 – Post Office Protocol – Version 3.
The most commonly used commands in a POP3 connection are as follows:
USER <username> PASS <password> STAT LIST RETR DELE RSET TOP QUIT
where <username> and <password> are your mailbox’s username and password. These are passed as plain text to the mail server and are not encrypted in any way.
All responses from the server will start with one of the following:
+OK -ERR
There is usually more information displayed after this status value (+OK means your command was successful and -ERR that it failed) to indicate why there was an error, or what the result of the command was if it suceeded.
POP3 Commands Example – Logging In
To open up a connection to a POP3 server, open up a command line or console on your Windows or UNIX system and enter the following command:
telnet <servername> 110
where <servername> is the name or ip address of the POP3 mail server you want to connect to. Once a connection has been established you will see a server response similar to the following:
+OK POP3 mail.domain.net v2003.83 server ready
This indicates the server is ready and waiting for your username and password. You cannot do anything with the server until you have sent these details. Do this like so:
USER myusername +OK User name accepted, password please PASS mysecretpassword +OK Mailbox open, 3 messages
After successfully logging in you can see the server responds by telling you it was successful (+OK) and that there are 3 messages in the inbox. With a POP3 mailbox there is only one mailbox and all the messages go into it when delivered to the server. Note that any of the following commands can be issued at any time and in any order.
Using STAT to show number of messages
The STAT command displays the number of messages currently in the mailbox and the size in bytes as shown in the following example:
STAT +OK 3 5467
The number of messages may already be displayed when you first login but this behaviour will vary depending which mail server software is being used. The STAT command reliably supplies this information.
LIST displays a summary of message
As well as STAT, you can use LIST to get a summary of messages where each message number is shown with the size in bytes next to it. This is shown in the example below:
LIST +OK Mailbox scan listing follows 1 1823 2 1825 3 1819 .
As with all POP3 commands the status response takes a single line. As this particular command returns data lines after the initial status line a period followed by a carriage return and line feed is used to indicate the end of data. This is useful if you are writing software to download data from a mail server as you need to know when to stop reading from the stream.
Retrieving messages with RETR
Use the RETR command followed by a message number to retrieve a particular message, where the first message number is 1. Note that you cannot retrieve a message that you have already deleted (deleting a message is covered further down the page).
RETR 1 +OK 1823 octets --- all message headers and message --- .
Again the server responds with +OK to indicate success and shows how large the message is in bytes on the first line. The following lines contain the entire raw email message with full headers and message body. The last line of the message with be a full stop on a single line followed by a carriage return and line feed to indicate the end of the message.
Deleting a message with DELE
A message can be retreived multiple times and if you log off and log back in again the messages will still be there until the are deleted. Use the DELE command to delete a message. This works in the same way as the RETR command:
DELE 1 +OK Message deleted
Note that if your connection to the server is broken at all then the messages will not actually be deleted. You need to cleanly disconnect from the mail server for this to happen.
Resetting the session with RSET
You can reset the session to its initial state using the RSET command. This will undelete all messages deleted using DELE.
RSET +OK Reset state
Retrieving part of the message with TOP
Not all mail servers support the POP3 TOP command but if they do it is useful for only retrieving part of the message. It works like RETR but you also specify the number of lines of the message body you would like returned. All the headers will always be returned.
Example 1 – Return headers only:
TOP 1 0 +OK Top of message follows --- all message headers --- .
Example 2 – Return headers and first 10 lines of body:
TOP 1 10 +OK Top of message follows --- all message headers --- --- first 10 lines of body --- .
Note that there will always be an empty line between the message headers and the message body. This is also the case when using the RETR command.
Use QUIT to end the POP3 conversation
Once you have completed your POP3 converstion simply log off by using the POP3 QUIT command like so:
QUIT +OK Sayonara