Post Office Protocol Version 4 detailed specification.


RFC:

An RFC is forthcoming, but for now, an easy quick but complete reference is available here. If you're interested in adding POP 4 functionality to a mail client or writing your own POP 4 server and would like to discuss anything about POP 4 please email me at pop4@pop4.org

I run O3 as my mail server for pop4.org. If you'd like an account to test with so you can do client testing or compare results for the server email me and I'll be happy to set you up an account.

Of course you can download O3 and run it yourself. Check the O3 mail system page for more information about this. Or check the sourceforge site.

Overview:

This document does specify an Internet standard.

This is a comprehensive list of details for the additions to POP 3 that comprise POP 4.

An implementation of a POP 4 server implies the implementation of a POP 3 server plus additional commands, listed below. We will refer to parts of the POP 3 spec with the assumption that you are familiar with them already. If you need a small refresher, you can click here: POP 3 RFC1939

All new POP 4 commands affect only the TRANSACTION state. There are no new authentication rules or features in POP 4 over and above what is specified in POP 3. All commands and features MUST be implemented to be said to be POP 4 compliant except where specifically specified in the command description.

POP4 banner.

Since a POP 4 server is intended to supersede a POP 3 server, it can run in place of a POP 3 server, defaulting to port 110.

To enable a client to differentiate between a POP 3 server and a POP 4 server, the exact text string "POP4 rev" MUST be in the banner string returned by the server upon connection. For example, the O3 server, returns the following banner string:

+OK O3 POP3 POP4 rev 0 Server. Build 1036 Apr 5 2003 15:29:31; <7137.1049646929@pop4.org>

The inclusion of "POP 4 rev" informs the client that this is a POP 4 compliant server. The string "POP 4 rev" MUST be followed by an integer decimal number followed by a space. The rev version is currently zero (as of 4/2003) to allow for future changes to the specification, and enable clients to distinguish the capabilities of this server on a protocol implementation level. See also CAPA.

Message identifiers.

In POP 3, all commands that require the client to specify a message ID usually refer to the message by message number listed in the LIST command. POP 4 allows for another option. Any place a message ID is required (this includes all POP 3 commands as well as POP 4 commands) the UIDL of a message can be specified if it is preceded by a hyphen "-".
Clients normally have to sync numbers to UIDLs by issuing a UIDL command and end up storing the UIDLs locally for state between sessions.
This feature allows clients to operate on messages by UIDL only.
if the UIDL command responds with:
1 834E643254D09704317C3ACE7CF831C5
then "retr 1" and "retr -834E643254D09704317C3ACE7CF831C5" have exactly the same meaning.

Server side folders.

There are six new commands related to server side folder management. Four for folder manipulation and two for handling messages with folders.

POP 4 defines support for folders on the server. One notable limitation of POP 3 is that a user's mailbox only has one folder, the 'Inbox'. Many popular mail clients support folders on the client side. This functionality allows for folders on the server side.

- Folder names are case preserving, but not case sensitive.
- Folders can be nested.
- The folder hierarchy is delimited by the forward slash character "/".
- To use the forward slash character in a folder name, it must be escaped with the back slash character "\" as familiar in UNIX.
- To use the back slash character, you also escape it with a backslash.
- Folder names can consist of any character in the ASCII 32-126 range inclusive.
- There is only one reserved folder defined by POP 4: /Inbox
- All references to folder names to the server will be fully qualified and unquoted.
- Folder names can not start or end with spaces, but can contain them. "/root1/sub 1" is valid, "/root1/ sub 1" is not valid.
- When logging in via USER/PASS or APOP, the currently selected folder must be "/Inbox".

Considerations:
Although there is only one predefined folder ("/Inbox") in POP 4, since most mail clients are likely to implement the other common folders, they should be the same name for interoperability.

To that end I suggest that:
If you implement a trash or deleted messages folder, use the name "/Trash"
If you implement a folder for sent mail, use the name "/Sent Mail"
If you implement a folder for draft messages, use the name "/Drafts"
If you implement an outbox folder, use the name "/Outbox"

There are no commands for pruning and grafting the folder tree. That work is left to the client. The purpose of POP 4 is to supply the minimum functionality required. This is an example of that. Renaming folders and pruning the folder hierarchy can achieved through the use of available POP 4 folder commands...

LFLD - List folders.

LFLD <folder path>

The folder path parameter is required. Upon success, this command will yield a list of folders that are subordinate in the hierarchy to the one passed in the parameter to LFLD. The parameter you pass MUST be an existing folder, fully qualified, and can be specified case insensitively. The one exception is "/". There is, and can be no folder named "/" but to get a list of root folders in the tree and all child folders you can use the command: LFLD / The list is returned as a multiple line list, ending with a dot "." on a line by itself, as in the RETR command. Since all folder names are returned fully qualified, there will be no need to dot escape a folder name.
The CFLD has no effect on the state or selection of the current folder.

Examples:

C: lfld /
S: +OK folder list follows.
S: /Inbox
S: .
C: lfld /inbox
S: +OK folder list follows.
S: .

In the first example, we see there is only the one folder /Inbox in the user's entire mailbox.
In the second example, when we attempt to list folders that are children of /Inbox, we receive no error, but an empty list, because there are no folders subordinate to /Inbox.

C: lfld /junk
S: -ERR /junk Folder not found.


SFLD - Select a folder for use.

SFLD <folder path>

The folder path parameter is required. Upon success, this command will set the current folder to the folder name specified as the parameter to the SFLD command.
All message related commands (RETR, LIST, STAT, UIDL, MOVE...) will operate on the messages in this folder.

Note: The use of SFLD will force an implicit flush of flag changes and deleted messages to the current mailbox BEFORE THE SFLD IS ATTEMPTED.

In POP 3, the state of the mailbox is not committed to permanent storage until the QUIT command is executed. At any time before that, an RSET command will restore the initial load state of the mailbox (before any messages were read or deleted). Attempting an SFLD command (even if it is to the same folder as the current one) will yield the same effects that a QUIT command does as far as reading and deleting messages goes.
In this way, SFLD can be used to refresh the view of the current folder without quitting and logging back in.

Examples:

C: sfld /inbox
S: +OK /inbox selected.

C: sfld /
S: -ERR / Folder not found.
C: sfld /junk
S: -ERR /junk Folder not found.


CFLD - Create a folder.

CFLD <folder path>

The folder path parameter is required. Upon success, this command will create a folder with the name specified in the parameter. You can not create islands. If you specify a folder path that has many levels of folder leading up to it, all of those folders must exist before you attempt to create the child folder.
The CFLD has no effect on the state or selection of the current folder.

Examples:

C: cfld /inbox/Sub1
S: +OK Folder created.
C: cfld /inbox/Sub2
S: +OK Folder created.
C: cfld /root1
S: +OK Folder created.
C: cfld /root1/Sub1
S: +OK Folder created.
C: cfld /root1/Sub2
S: +OK Folder created.

C: lfld /
S: +OK folder list follows.
S: /Inbox
S: /inbox/Sub1
S: /inbox/Sub2
S: /root1
S: /root1/Sub1
S: /root1/Sub2
S: .

C: lfld /ROOT1
S: +OK folder list follows.
S: /root1/Sub1
S: /root1/Sub2
S: .

C: cfld /inbox/a/b
S: -ERR Invalid folder name for create folder.


DFLD - Delete a folder.

DFLD <folder path>

The folder path parameter is required. Upon success, this command will delete the folder specified in the parameter passed to the DFLD command.
- You can not delete the folder "/Inbox"
- You can not delete the currently selected folder.
- You can not delete a folder that has any messages in it.
- You can not delete a folder that has any child folders in it.

These last two restrictions keep clients from accidentally deleting large amounts of data with one command. POP 4 doesn't even remotely support anything like rm -rf *

Examples:

C: lfld /
S: +OK folder list follows.
S: /Inbox
S: /inbox/Sub1
S: /inbox/Sub2
S: /root1
S: /root1/Sub1
S: /root1/Sub2
S: .
C: dfld /root1/sub2
S: +OK Folder deleted.
C: dfld /root1
S: -ERR Folder to delete has other folders in it.
C: dfld /root1/sub1
S: +OK Folder deleted.
C: dfld /root1
S: +OK Folder deleted.


MOVF - Move a folder into a different folder.

MOVF <source path> <target path>

The last folder specified as the "source path" is moved into the folder specified by "target path." Quotations may be used when path names contain spaces.

Example:

C: movf /Inbox/Folders/Cats /Inbox
S: +OK Okay


Folder /Inbox/Cats now exists.

RENF - Move a folder into a different folder.

RENF <folder path> <new name>

The last folder specified as the "folder path" is renamed to the specified name.

Example:

C: renf /Inbox/Folders/Cats Animals
S: +OK Okay


Folder /Inbox/Folders/Cats is now /Inbox/Folders/Animals

MOVE - Move one or more messages from current folder to specified folder.

MOVE <folder path>
<msg id>
<msg id>
<...>
<msg id>
.

The folder path parameter is required and is to be followed by a dot "." terminated list of message identifiers.
As with the SFLD command, an attempt to use the MOVE command will cause a flush to the permanent store of flag and deleted message status before messages are looked up or moved.

Upon success of this command, all messages listed to be moved will no longer exist in the current folder, but will be in the destination folder when the client next does a SFLD to that folder.
Since this command has an effect on the state of the current folder an implicit SFLD to the current folder is done after the messages have been moved.
Since there is a lot of room for error, as the server has to move many messages in one operation, if any part of the entire operation does not succeed, the operation will be considered not to be error free.
Operations that are not error free will yield an -ERR response from the server. At this point the state of the source and destination folders are unknown to the client. The client should therefore refresh from the server, at minimum, the current folder list. The destination folder's state will also be uncertain and the client should be aware of that.
If the server responds with +OK, then the client can assume all of the specified messages have been moved without error.
If the client sends duplicate message IDs or message IDs of messages that don't exist, this is an error. Although the final result can be predicted, the server should still return -ERR. In case of an error, the server should make a best attempt at fulfilling the request, as in it should not ignore the rest of the list, if it gets an error on the first message to move.

Considerations:
This command is ripe for denial of service attack, since the client is allowed to keep sending an infinite list of messages to move, even repeats. So for the sake of implementation, it is recommended that the server enforce a limit as to the number of valid messages that it has to keep track of to move, upon receiving the end of list delimiter. The hard limit can be enforced by returning an -ERR response when the limit is reached. All subsequent message id entries received (assuming the sending program is blindly sending the list, as malicious programs likely would be) will be interpreted as POP 4 commands and probably be invalid and have no detrimental effect.

Examples:

C: uidl 1
S: +OK 1 F28DC4CC34F75E2844263F68453397FE
C: uidl 2
S: +OK 2 38171BF147D67DA8EFF67E280A366E26
C: move /inbox/sub
C: 1
C: 2
C: .
S: -ERR Destination folder not found.
C: lfld /
S: +OK folder list follows.
S: /Inbox
S: /inbox/Sub1
S: /inbox/Sub2
S: .
C: move /inbox/sub1
C: 1
C: -38171BF147D67DA8EFF67E280A366E26
C: .
S: +OK Messages moved.


COPY - Copy one or more messages from current folder to specified folder.

COPY <folder path>
<msg id>
<msg id>
<...>
<msg id>
.

The folder path parameter is required and is to be followed by a dot "." terminated list of message identifiers.
This command is very similar to MOVE except that messages are duplicated and stored in the destination folder, leaving the original folder intact.
Despite this, the same rule about flushing to the permanent store flag and deleted message status applies. This lets us define the state of the message flags before the copy is made.
Because of the flush there is also the implicit SFLD to the current folder after the copy, just as with the MOVE command, since some messages may have been deleted as a result, and will no longer be accessible with an RSET.

Considerations:
See the considerations for MOVE. Also note that if quotas are implemented on a POP 4 server implementation that the COPY command will have an effect on the users use of their quota. The server may stop copying messages at the point where the user goes over quota and from then on the operation will be considered to have errors. Thus the response from the server will be -ERR since the command did not complete error free.

Examples:

C: uidl 1
S: +OK 1 1929261D8CD53D8DCBC99387A698584A
C: uidl 2
S: +OK 2 F56B6079FB06BAC38657A7D6BE688EDB
C: copy /inbox/sub2
C: -1929261D8CD53D8DCBC99387A698584A
C: -F56B6079FB06BAC38657A7D6BE688EDB
C: .
S: +OK Messages copied.


STOR - Receives message data from the client and adds it to the current folder. The message data should be dot stuffed.

STOR

Example:

C: stor
S: +OK Send data, terminate with <CRLF>.<CRLF>
C: <message data>
S: +OK 1929261D8CD53D8DCBC99387A698584A


A successful response from the server indicates the new UIDL of the uploaded message. The client must re-select the folder in order to see the message in the message table.

Message flags.

Message flags serve the purpose of storing some binary information about individual messages. For example whether or not the message has been read, or marked for delete. In addition to those two functions available in POP 3, there is more flexibility with POP 4 to view and set message flags, there are more predefined flags. Flags can be referred to by name or number.
Thirty-two (32) flags are supported by POP 4. Seven of them are defined by POP 4, the rest are client defined. There are no recommendations for other uses for flags, but I would be glad to coordinate the effort of defining new ones for the sake of consistency throughout POP 4 implementations.

The 7 predefined flags and their numbers are as follows.
Flag 1 Visible
Flag 3 Read
Flag 4 Flagged
Flag 5 Deleted
Flag 6 Replied
Flag 7 Forwarded
Flag 8 Sent Read Receipt

Notes: Flag #1 is reserved for server internal use. It is defined here so that no clients make use of it for another purpose, but all messages can be considered visible to the client. Since the visible flag can always be assumed to be set, the server will not display this flag as being set to the client. If the server has made this message invisible, it will simply not show up to the client. Though it appears to have no obvious use, when running very large mail systems, it is sometimes useful to make messages invisible to the client such that they can be restored later.
Flag #2 is reserved for server internal use, and should not be used by any clients.
Flag #3 (read) should be set by the POP 4 server when the client does a RETR command on a message.
Flag #4 (flagged) is for client side use. If the client supports flagging messages, they can use this flag to do so.
Flag #5 (deleted) has the same functionality as the DELE command.
Flag #6 (replied) is for client side use. If the client supports denoting that a message was replied to, they can use this flag to do so.
Flag #7 (forwarded) is also for client side use. If the client supports denoting that a message was forwarded, they can use this flag to do so.
Flag #8 (sent read receipt) is also for client side use. If the client supports read receipts, it can use this flag to mark a message that requested a read receipt as having sent a receipt after the user sends one.

No flag changes are committed to permanent storage unless a command causing a flush to disk has been used. These include QUIT, SFLD, MOVE, and COPY.
The RSET command will undo any flag changes set or cleared made to the messages in the current folder, setting them to their original state as of login, or the most recent SFLD (whether the client sent it or implicitly executed by MOVE or COPY).

There are two new commands related to message flags.

SETF - Set a flag for a message.

SETF <msg id> <flag id> <on/off>

The SETF command requires all three parameters. The first parameter is the message id to operate on.
The second parameter is the flag id to set or clear. This can either be a number from 1 to 32 inclusive, or one of the case insensitive words: "read" "flagged" "deleted" "replied" "forwarded" or "receipt".
The third parameter is either the word "on" or "off", again case insensitive.

Setting a flag on will set the flag, off will clear it.
Setting flag 5 is functionally the same as DELE.
For example, "DELE 1" is the same as "SETF 1 5 on"
The server may ignore settings for flags 1 and 2 but should not return an error for doing so. Client should never attempt to use these flags, because server results will be unpredictable and are implementation dependent.

Examples:

C: setf 1 replied on
S: +OK Flag 4 set.
C: setf 1 replied off
S: +OK Flag 4 cleared.


GETF - Get flags for a message.

GETF <msg id>

The GETF command requires one parameter, the message id to operate on.
The command will return a dot "." terminated list of flags set for the specified message. The flags that are set, if any, will be listed one per line by number. The POP 4 server can OPTIONALLY respond by appending a space and the flag name after the number. Only the number is REQUIRED, the name is not. It would exist only for human readability and should not be expected by the client.

The GETF command has an alternate behavior. If the argument received is the word CONDENSED, then each row returned represents a single message with all set flags combined using the binary OR operator.


Examples:

C: setf 1 4 on
S: +OK Flag 4 set.
C: getf 1
S: +OK Flag list follows.
S: 3 read
S: 4 flagged
S: .
C: getf condensed
S: +OK Flag list follows:
S: 1 12
S: 2 4
S: 3 0
S: 4 36
S: .

Quota information.

One new command has been added to enable the server to supply quota information if applicable.

QUOT - List user's quota information.

QUOT

The QUOT command is optional. It is not required for POP 4 compliance.
If the server maintains a quota for a user it can respond to this command with a dot "." terminated list of quota information.
The first line in the response from the server will be the amount of storage used in the users mailbox, in bytes (octets). The second line in the response will be the total allowed allocation for the user in bytes.
If the server implements the QUOT command, then it must supply at minimum those two responses. If the server has more quota or account information to supply to the client, it may add to the list, providing it returns data in a key value pair, one per line, separated by a colon, after the first two required fields.
If the server does not support the QUOT command, it should return an -ERR response.

Examples:

C: quot
S: +OK Quota information follows.
S: 13100570
S: 104857600
S: Users full name: Stu Mark
S: .

Persistent connections.

POP 3 sessions are not intended to persist for any great length of time, and clients can be expected to be hung up on. Since POP 4 allows for more server activity, it's possible the client will want to remain connected for longer periods of time. For heavy usage servers this is not a desirable situation from a server perspective, but for smaller installations, it can yield quicker response from the server since the client would not have to repeatedly log in.

One new command has been added to enable persistent server connections.

PERS - Disable inactivity timeout.

PERS

The PERS command is NOT REQUIRED for POP 4 compliance. Using the PERS command will disable the inactivity timeout for this session. The client can then expect the connection to remain valid barring any network problems.
If the server does not support the PERS command, it should return an -ERR response.

Considerations: The client can force this functionality with sporadic NOOP commands, so this is somewhat superfluous, but it makes the full time use of the server a little cleaner.

Partial message retrieval.

I saved this one for last, because it's a doozy.
One of the limitations of POP 3 is that in terms of messages it is granular to the message level. You can retrieve a message all at once or not at all. A great benefit to clients would be the ability to retrieve only the readable parts of a message as they were needed.
In the case of a low-bandwidth situation, the most evident use of this functionality would be to not download attachments just to read the textual part of the message.
The design goal of a web-based email client would also benefit greatly from this, in the ability to just download a text/html alternative part instead of both text/plain and text/html.

So the subject of MIME comes up. It's a big meal, and somebody's got to eat it. In the case of POP 4, it is handled on the server. This presents the biggest shift in processing, from client to server.
Basically, all of the other additions, folders and flags are relatively trivial (depending on how your mail is stored, I suppose) but after a lot of thought, I decided that it was still the better way to go to have the server do the bare minimum MIME processing, while still giving a lot of functionality to the client.

One new command has been added and two have been modified to support partial message retrieval.

LPRT - List message parts.

LPRT <msg id>

The LPRT command requires one parameter, the message id to list the parts of.
The command will return a dot "." terminated list of hierarchical part numbers followed by, folded if necessary, the Content-type and Content-Disposition header fields for that part.
This gets really complicated really quickly, so lets start with an example.

C: lprt 5
S: +OK part list follows.
S: 1 multipart/mixed; boundary="Boundary_(ID_Q2iiT3pwiD0ScVcrbWl8nQ)"
S: 1.1 audio/x-wav; name=voice.200303211240.wav; Content-Disposition=attachment; filename=voice.200303211240.wav
S: 1.2 TEXT/PLAIN
S: .

The output starts with the +OK response if the message was found and able to be mime parsed. The second line will be information about the main part, the whole message. It is labeled with the number 1. It is followed by a space and the contents of the "Content-type" header field if any. A semicolon ";" is appended and then the contents of the "Content-Disposition" header field if any.
There is no content disposition field for the main part of the message so it is not added to the entry for part "1".
The next line (line 3) is for the first part of the mime parts in the main message. It is labeled "1.1" to denote that it is a subordinate section.
It does have content type and content disposition headers.
The line is too long to fit on one line (output is limited to 78 characters per line) it is folded as an RFC-822 message header would be. The line is broken up before the 78 character limit, and the next line is indented. When unfolding, any lines that start with whitespace are appended to the line before it.
The second subsection (line 5) of the response is about the second part in the multipart section of the main message and is therefore labeled "1.2". It is of type text/plain.

A similar example: In this message the main message part is of type multipart/alternative and there are two alternatives. The first subpart, which is nested in the main part, is text/plain labeled "1.1", the second part is text/html, labeled "1.2"

C: lprt 257
S: +OK part list follows.
S: 1 multipart/alternative; boundary="Boundary_(ID_aAec6S+TlQC6+IvemKbMTg)"
S: 1.1 text/plain; charset=iso-8859-1
S: 1.2 text/html; charset=iso-8859-1
S: .


A simple non-mime message will just have one part and possibly no content information headers, so the output would be this:
C: lprt 15
S: +OK part list follows.
S: 1
S: .

So basically, the entire message is referred to by the first digit. For every level of nesting into the message you go, you add another dot level.
The two MIME types that cause this nesting are "multipart" and "message" types. If a message is forwarded as an attachment, it is represented by another layer of nesting, because its content-type would be "message/rfc822".


Here is a complicated example, if you can parse this, you've got it.

C: lprt 258
S: +OK part list follows.
S: 1 multipart/mixed; boundary="Boundary_(ID_aNr6mOqk0iRiuxDtnLBe1Q)"
S: 1.1 multipart/alternative; boundary="Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)"
S: 1.1.1 text/plain; charset=iso-8859-1
S: 1.1.2 text/html; charset=iso-8859-1
S: 1.2 message/rfc822; name=alternamtive.eml
S: 1.2.1 multipart/alternative; boundary="Boundary_(ID_xgtcEN22+aCGz1kbE+CVYQ)"
S: 1.2.1.1 text/plain; charset=iso-8859-1
S: 1.2.1.2 text/html; charset=iso-8859-1
S: 1.3 text/plain; name=attach.txt; Content-Disposition=attachment; filename=attach.txt
S: .

In this message, we took the multipart/alternative message from before and added it as an attachment (forwarded as attachment), to another multipart/alternative message. Then we added a simple text file as an attachment.

Part "1" notes that this message is multipart/mixed.
If you look at "1.1" "1.2" and "1.3" you can see the three parts of the main multipart/mixed. If you look at the "1.1.1" and "1.1.2" you see the alternative parts of the main message. "1.2" is that message/rfc822 that we attached. The difference between "1.2" and "1.2.1" is that "1.2" includes all the data about the part, which includes the "1.2" part header, whereas "1.2.1" is JUST the rfc/822 message in its entirety. It is multipart alternative, and the two parts are "1.2.1.1" and "1.2.1.2"
The "1.3" is the simple attachment to the main part.

For reference, here is the message that created the above LPRT output.

Date: Sun, 06 Apr 2003 19:49:19 -0400
From: pop4 <pop4@pop4.org>
Subject: More complicated message
To: Stu <pop4@pop4.org>
Message-id: <0c2001c2fc97$248a9b80$0300000a@drum>
MIME-version: 1.0
Content-type: multipart/mixed;
boundary="Boundary_(ID_aNr6mOqk0iRiuxDtnLBe1Q)"

This is a multi-part message in MIME format.

--Boundary_(ID_aNr6mOqk0iRiuxDtnLBe1Q)
Content-type: multipart/alternative;
    boundary="Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)"


--Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)
Content-type: text/plain; charset=iso-8859-1
Content-transfer-encoding: 7BIT

This is the main message, it is multipart/alt and has one forwarded message
(that is multipart/alt) as an attachment and a small text file attachment.


--Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)
Content-type: text/html; charset=iso-8859-1
Content-transfer-encoding: 7BIT

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<META content="MSHTML 6.00.2600.0" name=GENERATOR>
<STYLE></STYLE>
</HEAD><FONT face=Arial><FONT size=2>
<BODY>
<DIV>This is the main message, it is multipart/alt and has one forwarded
message
(that is multipart/alt) as an attachment and a small text file
attachment.</DIV>
<DIV> </DIV></BODY></HTML></FONT></FONT>

--Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)--

--Boundary_(ID_aNr6mOqk0iRiuxDtnLBe1Q)
Content-type: message/rfc822; name=alternamtive.eml

Date: Sun, 06 Apr 2003 19:19:17 -0400
From: pop4 <pop4@pop4.org>
Subject: alternamtive
To: Stu <pop4@pop4.org>
Message-id: <0c1101c2fc92$f4e1f8f0$0300000a@drum>
MIME-version: 1.0
Content-type: multipart/alternative;
     boundary="Boundary_(ID_xgtcEN22+aCGz1kbE+CVYQ)"

This is a multi-part message in MIME format.

--Boundary_(ID_xgtcEN22+aCGz1kbE+CVYQ)
Content-type: text/plain; charset=iso-8859-1
Content-transfer-encoding: 7BIT

Multipart alternative

--Boundary_(ID_xgtcEN22+aCGz1kbE+CVYQ)
Content-type: text/html; charset=iso-8859-1
Content-transfer-encoding: 7BIT

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
<META content="MSHTML 6.00.2600.0" name=GENERATOR>
<STYLE></STYLE>
</HEAD><FONT face=Arial><FONT size=2>
<BODY>
<DIV><U><EM><STRONG>Multipart
alternative</STRONG></EM></U></DIV></BODY></HTML></FONT></FONT>

--Boundary_(ID_xgtcEN22+aCGz1kbE+CVYQ)--

--Boundary_(ID_aNr6mOqk0iRiuxDtnLBe1Q)
Content-type: text/plain; name=attach.txt
Content-transfer-encoding: 7BIT
Content-disposition: attachment; filename=attach.txt

"test attachment"

--Boundary_(ID_aNr6mOqk0iRiuxDtnLBe1Q)--
.

Another example of LPRT used in a real POP4 session:

LPRT 108
+OK Part list follows:
1 multipart/mixed; boundary="0000000000007f79b505d175b8c3"
1.1 multipart/alternative; boundary="0000000000007f79b305d175b8c1"
1.1.1 text/plain; charset=UTF-8; Encoding=base64
1.1.2 text/html; charset=UTF-8; Encoding=base64
1.2 application/pdf; Content-Disposition=attachment; Content-ID=; name="Amazon Case ID#47562783452.pdf"; Encoding=base64
.

RETR - Retrieve a message, or message part.

RETR <msg id> [part]

The RETR command requires one or two parameters. If the second parameter is omitted, then the RETR command functions exactly as described in the POP 3 RFC. If the second parameter is entered, then the RETR command will only output the part specified by the part parameter.
The parameter must match identically to one of the items output in the LPRT command for that message. If you specify a part that doesn't exist, the server will return -ERR. If you specify "1" for the message part the server response will be identical to the output of the RETR command without the part parameter, because part "1" denotes the entire message.

Note: If the part parameter is specified, the server should not set the read flag for the message, for it is likely that the entire message was not retrieved. Only the RETR command without the part parameter should set the read flag for this message.

Examples:

C: retr 258 1.2.1.1
S: +OK Message part follows.
S: Content-type: text/plain; charset=iso-8859-1
S: Content-transfer-encoding: 7BIT
S:
S: Multipart alternative
S:
S: .


C: retr 258 1.1
S: +OK Message part follows.
S: Content-type: multipart/alternative;
S:    boundary="Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)"
S:
S:
S: --Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)
S: Content-type: text/plain; charset=iso-8859-1
S: Content-transfer-encoding: 7BIT
S:
S: This is the main message, it is multipart/alt and has one forwarded message
S: (that is multipart/alt) as an attachment and a small text file attachment.
S:
S:
S: --Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)
S: Content-type: text/html; charset=iso-8859-1
S: Content-transfer-encoding: 7BIT
S:
S: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
S: <HTML><HEAD>
S: <META http-equiv=Content-Type content="text/html; charset=iso-8859-1">
S: <META content="MSHTML 6.00.2600.0" name=GENERATOR>
S: <STYLE></STYLE>
S: </HEAD><FONT face=Arial><FONT size=2>
S: <BODY>
S: <DIV>This is the main message, it is multipart/alt and has one forwarded
S: message
S: (that is multipart/alt) as an attachment and a small text file
S: attachment.</DIV>
S: <DIV> </DIV></BODY></HTML></FONT></FONT>
S:
S: --Boundary_(ID_xPX3wYlCe0hrmuHgnfNGmQ)
S:
S: .


TOP - Retrieve headers for a message, or message part.

TOP <msg id> <lines> [part]

The TOP command requires two or three parameters. If the third parameter is omitted, then the TOP command functions exactly as described in the POP 3 RFC. If the third parameter is entered, then the TOP command will only output the headers of the part specified by the part parameter.
The same rules apply to TOP as for RETR. The parameter must match identically to one of the items output in the LPRT command for that message. TOP will display the headers for that part, a blank line, and the number of lines specified in the lines parameter from the content of that part.

Examples:

C: top 258 1 1.2.1.2
S: +OK Message part follows.
S: Content-type: text/html; charset=iso-8859-1
S: Content-transfer-encoding: 7BIT
S:
S: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
S: .

Message Paging.

These two commands are optional, as they are primarily intended for webmail implementations.

SORT <meta field> [sort direction]

POP4 servers supporting this command should at minimum support sorting with the following meta fields:
The optional sort direction can be ASC or DESC. If it is not specified, then ascending sorting is used. Using the SORT command causes the message table to be dropped and rebuilt. After sorting, message numbers will be different for messages.

PAGE <page start> <page end>

Pages are set using message numbers. Paging works by specifying the first message number to return and the last message number to return. LIST, UIDL, XTND XLST, and GETF CONDENSED commands only return messages within that range.

PAGE CLEAR

The PAGE CLEAR command removes paging from the message table.

Examples:

C: SORT Date DESC
S: +OK Table sorted
C: PAGE 5 10
S: +OK Page set
C: LIST
S: +OK 5 messages (6775 octets)
S: 5 1100
S: 6 1100
S: 7 1200
S: 8 1150
S: 9 1100
S: 100 1125
S: .

Other POP 4 Considerations.

CAPA

Since some of the POP 4 commands listed above are optional, they can be listed in the list of capabilities output from the CAPA command, if the server supports it.
The word "PERSISTENT" should be added to the CAPA response list if the POP 4 server supports the PERS command.
The word "QUOTA" should be added to the CAPA response list if the POP 4 server supports the QUOT command.

Event driven new-mail notification.
This is NOT part of POP 4. I was considering it, but it goes beyond the original design goal of enabling a web-based mail client to function with a decent number of features.
To add this functionality would require a different paradigm of server design which is specifically what POP 4 tries to avoid. It simply adds commands to the POP 3 set that can be very useful to mail clients without making it too complex.

Contact information:
Requests for information, or if you would like to discuss any part of POP 4, please feel free to email me at pop4@pop4.org
Please also check sourceforge for project information related to POP 4.