Reading mail with POP3

Reading mail via POP3 (or IMAP) is its own protocol implemented separately from the SMTP server I have been working on thus far. The POP3 service runs on TCP port 110, has three states (AUTHORIZATION, TRANSACTION, and UPDATE), and commands allowed within each state.

Before even beginning to look into the specifics of POP3, I refactored a large portion of the SMTP server to make key aspects (TCP server, reading lines until CRLF, etc) re-usable and finally broke my monolithic C file into relevant topic files. I also decided to implement the POP3 server into the same codebase, using poll.h to listen to both :25 and :110.

The actual POP3 protocol is very simple:

1. Start in AUTHORIZATION state and use APOP (md5 encryption with challenge) or USER/PASS to authenticate
2. In TRANSACTION state, client issues the following commands: STAT (reply with number of messages and total size), LIST (multi-line response with message 1-indexed and size on each line) RETR [msg] (retrieve [msg]), DELE [msg] (mark [msg] for deletion), NOOP (keep connection open, no action), RSET (un-mark messages for deletion), and QUIT (move to UPDATE state)
3. in UPDATE state, action deletions then end the connection

In addition, the setup and flow is very similar to SMTP once the TCP server is set up. The commands and states are different, but the concept is surprisingly similar.

For reference, he is the header file for pop3.c:

#ifndef POP3_H
#define POP3_H

#include <stdlib.h>
#include <stdbool.h>

#include "tcp.h"  // abstracted TCP server
#include "user.h" // user auth and mailbox

struct POP3Session {
    bool immediate_successful_user;          // needed for sequential USER then PASS commands for aut
    int mode;                                // This is referred to as "state" by RFC 1939; 0 => AUTHORIZATION, 1 => TRANSACTION, 2 => UPDATE
    int num_marked_for_deletion;             // tracks size for marked_for_deletion
    char mailbox_user[ADDRESS_SIZE];         // identifier for user
    struct MailboxSnapshot mailbox;          // contains a list of MailboxMessage, which in turn contains a path and size
    bool marked_for_deletion[MAX_LIST_SIZE]; // marked mail in MailboxSnapshot for deletion, to be executed on UPDATE
    struct ConnectionBuffer conn_buffer;     // buffer that TCP server reads into
};

void *handle_pop3_client(void *arg);

#endif

The main difficulty with implementing POP3 in practice is the requirement of an integrated, robust user account/mailbox system, since POP3 is effectively just a standardized way to transmit authentication and fetch requests.

Thus, user.h introduces local user authentication (currently it's a simple [username]:[password] line in a local file) as well as CRUD operations for mail that allows POP3 to utilize stored mail in the maildir format:

bool read_message_file(const char *path, char *buf, size_t buf_size, size_t *out_size);
bool send_message_file(int client_fd, const char *path);
bool delete_message_file(const char *path);

Now, we can use telnet to step through POP3 and read the mail that alice@pokey.onl sent to bob@pokey.onl in Receiving email (online):

Trying 96.126.120.46...
Connected to mail.pokey.onl.
Escape character is '^]'.
+OK POP3 server ready
USER bob
+OK bob is a real hoopy frood
PASS password
+OK bob's mailbox has 1 messages (54 octets)
LIST
+OK 1 messages (54 octets)
1 54
.
STAT
+OK 1 54
RETR 1
+OK 54 octets
Hello Bob, this is a test message over the internet!
.
QUIT
+OK mail.pokey.onl POP3 server signing off
Connection closed by foreign host.

I also wanted to try the POP3 server using an existing POP3 client rather than manually running telnet. After a bit of research, I picked mpop. It's website delightfully states "mpop is a POP3 client: it retrieves mail from POP3 mailboxes" which is exactly what I want it to do.

I installed mpop using my package manager then defined a config file in ~/.mpoprc:

defaults
tls off   # no TLS
auth user # use USER/PASS for auth

account bobatpokey  # name for this account
host mail.pokey.onl # POP3 server host
port 110
user bob             
password password
delivery maildir ~/Maildir # where to save using maildir format
keep on                    # do not delete from server

account default : bobatpokey

mpop will actually refuse to run if the config file is too permissive. This is fixed with a simple change of file permissions: chmod 600 ~/.mpoprc.

Now, simply running mpop syncs bob@pokey.onl's mailbox to ~/Maildir locally:

bob at mail.pokey.onl:
new: 1 message in 54 bytes, total: 1 message in 54 bytes
retrieving message 1 of 1 (54 bytes): 100%

Of course, this is sending the username and password as plain text over the network which is not recommended; however, we can now download mail received by the mail server for authenticated accounts. That is, we can: accept SMTP as server -> save as Maildir on VPS -> client requests mail using POP3 -> mail synced to device.

Finally, this is our updated progress summary:

After implementing security features, we could even use a simple cron job (such as */5 * * * * mpop) to sync mail in the background.

Last updated April 7, 2026