DataMotion provides customers with access to and Direct accounts via POP3 protocol for retrieving messages. This protocol can be utilized to access DataMotion and Direct mailboxes from any POP3 client, such as Microsoft Outlook, Mozilla Thunderbird, Eudora OSE, etc. To provide their users with better experience, some DataMotion customers choose to build their own POP3 clients. This article provides guidance to using POP3 commands to retrieve messages from DataMotion or Direct accounts with optimal performance and bandwidth utilization. The purpose of this article is to provide guidance. It should not be treated as a comprehensive and definitive reference.
For configuring SMTP and POP3 access to DataMotion and Direct, see https://kb.datamotion.com/?ht_kb=pop3-smtp-settings-securemail and https://kb.datamotion.com/?ht_kb=what-are-the-pop3smtp-settings-for-direct.
POP3 protocol commands
POP3 protocol (RFC 1939) is intended for managing incoming email. POP3 protocol commands are listed in the table below.
| Command | Description | Example |
| USER [username] | 1st login command | USER Stan +OK Please enter a password |
| PASS [password] | 2nd login command | PASS SeCrEt +OK valid logon |
| QUIT | Logs out and saves any changes | QUIT +OK Bye-bye. |
| STAT | Returns total number of messages and total size | STAT +OK 2 320 |
| LIST | Lists all messages: Returns indexed list of messages, along with size | LIST +OK 2 messages (320 octets) 1 120 2 200 … LIST 2 +OK 2 200 |
| RETR [message index] | Retrieves the whole message | RETR 1 +OK 120 octets follow. *** |
| DELE [message index] | Deletes the specified message | DELE 2 +OK message deleted |
| TOP [message index] [num lines to return] | Returns the headers and top X lines of a message by message index (from LIST). Can be used to display the 1st few lines of a message. Headers are always returned. | TOP 2 1 +OK < MIME-Version: 1.0X-Mailer: MailBee.NET 6.5.2.236To: user@company.comFrom: …., etc.>*** |
| UIDL [message index] | Returns a unique ID for a message index (from LIST). This ID is used by POP3 clients to identify previously downloaded messages. A client would connect, pull a LIST of messages, then pull a UIDL for each message index listed. If the UIDL had been downloaded prior, message can be skipped. If UIDL has not yet been downloaded, use the RETR command to download this new message. | UIDL 1
+OK 1 6866N |
| NOOP | The POP3 server does nothing, it merely replies with a positive response. | NOOP +OK |
| RSET | Undelete the message if any marked for deletion | RSET +OK maildrop has 2 messages (320 octets) |
POP3 is based on a notion of a session (a.k.a. transaction) that starts after login and ends after logout (QUIT command). All message indexes are valid for the duration of a session. Any changes in the mailbox content (e.g. messages deleted or received during the session) are reflected after the current session ends and next session starts. For example, if LIST command returned 3 messages and 2 of them were deleted, LIST command will continue returning the same 3 messages until QUIT. Next session will have one message returned by LIST command.
Please note that POP3 does not have a notion of folders and no way of accessing them.
Illustrations of POP3 command sequences
This section illustrates some typical application flows using POP 3 commands.
Establish a session
First, the application establishes a session by calling USER [username] and PASS [password] commands.
List messages so they can be displayed
- The application retrieves the list of messages in Inbox by calling LIST, which returns the indexes of all messages along with their sizes.
- To display messages, the application calls TOP [message index] [num lines to return] for each message, which returns the header, metadata and 1st line of each message.
- The application displays the result of the TOP command for the mailbox user.
Create a list of UIDs to keep track of which messages have been retrieved
- The application calls UIDL [message index] for each message, which returns the UID of each message.
- The application stores UIDs in a table in application memory. The UIDs for each message persists for the lifetime of the message.
Retrieve messages
To retrieve a message, POP3 application issues a RETR command with a given index number, which returns full message payload with attachments. This can be done on user request or as part of an automated flow.
For best performance and bandwidth utilization, POP3 application logic should be built to retrieve the same message once. This can be accomplished by storing message UIDs in a table (referenced above) and marking message with respective UIDs as Retrieved. This will help ensure that retrieval history persists between sessions (message indexes may change if new messages arrive or existing ones are deleted).
Delete messages
To delete a message, POP3 application issues a DELE command with a given index number. All deletions take effect after terminating the session. Deletions made during a session can be reversed by issuing RSET command within the same session.
Terminate the session
To terminate the session, POP3 application issues a QUIT command. All changes made during the session (new messages arrived in Inbox, existing messages retrieved or deleted by the application) will take effect in the next session. That is why it is important to persist the message UIDs in a table that remains in application memory between sessions.