Pop3 - Learning Module | OneNoughtOne

Loading content...

0/228

POP3 Commands

The POP3 Command Language

POP3's elegance lies in its simplicity. The entire protocol consists of a small set of text-based commands—human-readable keywords followed by optional arguments. This minimalist design means you can interact with a POP3 server using nothing more than a Telnet client, making debugging and learning straightforward.

Unlike modern protocols with complex binary encodings or extensive negotiation, POP3 commands read like simple instructions: USER to identify yourself, PASS to authenticate, LIST to see your mail, RETR to retrieve a message. This design philosophy prioritized transparency and implementation simplicity.

What You Will Learn

By the end of this page, you will master every standard POP3 command defined in RFC 1939, understand command syntax and response formats, know which commands are valid in which states, and be able to conduct manual POP3 sessions for troubleshooting.

Command Syntax Fundamentals

All POP3 commands follow a consistent syntax pattern, making the protocol predictable and easy to parse.

Basic Syntax:

COMMAND [argument1] [argument2] CRLF

Commands are case-insensitive: USER, user, and User are equivalent
Arguments are space-separated
Each command ends with CRLF (Carriage Return + Line Feed: \r\n)
Maximum command line length: 255 characters (including CRLF)

POP3 Response Indicators
Indicator	Meaning	Format
`+OK`	Success	`+OK [informational text]`
`-ERR`	Failure	`-ERR [error description]`
`.` (alone)	End of multi-line response	Single period on its own line

Response Types:

Single-line responses: Status indicator plus optional text
```
+OK Mailbox locked and ready
-ERR Authentication failed
```
Multi-line responses: Status indicator, followed by data lines, terminated by .
```
+OK 3 messages (5000 octets)
1 1500
2 2000
3 1500
.
```

Byte-Stuffing for Multi-line Responses:

If a data line in a multi-line response begins with a period, the server prepends an additional period. The client removes this extra period when processing:

Server sends: ..This line begins with a period
Client sees: .This line begins with a period

This prevents data lines from being mistaken for the termination indicator.

Debugging Tip

When manually testing POP3, remember that your terminal might not show the CRLF. Ensure you're pressing Enter (which typically sends CRLF on most systems) after each command. If commands seem to hang, you might be missing the proper line ending.

Commands by Session State

POP3 commands are only valid in specific session states. Attempting a command in the wrong state returns an error.

State-Command Matrix:

Command Validity by Session State
Command	AUTHORIZATION	TRANSACTION	Notes
USER	✓	✗	Only before authentication
PASS	✓	✗	Must follow USER
APOP	✓	✗	Alternative to USER/PASS
STAT	✗	✓	Mailbox statistics
LIST	✗	✓	Message listing
RETR	✗	✓	Message retrieval
DELE	✗	✓	Mark for deletion
NOOP	✗	✓	Keep-alive
RSET	✗	✓	Unmark deletions
TOP	✗	✓	Partial message (optional)
UIDL	✗	✓	Unique IDs (optional)
QUIT	✓	✓	Always valid

Converting Mermaid diagram...

State Transition Rules:

AUTHORIZATION → TRANSACTION: Only upon successful authentication (USER/PASS or APOP)
AUTHORIZATION → Closed: QUIT before auth, or auth failure limit reached
TRANSACTION → UPDATE: QUIT command
UPDATE → Closed: Always (UPDATE is transient)

Error Handling:

Issuing a command in the wrong state returns an error but doesn't change state:

# Before authentication, trying to read messages
C: STAT
S: -ERR Not authenticated

# Session remains in AUTHORIZATION state

QUIT is Special

QUIT is valid in any state. In AUTHORIZATION state, it simply closes the connection. In TRANSACTION state, it triggers UPDATE (commit deletions) before closing. This ensures clean session termination regardless of state.

AUTHORIZATION State Commands

Commands in AUTHORIZATION state handle user identification and authentication.

USER Command:

Identifies the user attempting to access the mailbox.

user-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Syntax
USER username
 
# Example
C: USER alice@example.com
S: +OK User accepted, password required
 
# The +OK response does NOT mean authentication succeeded
# It only means the username is syntactically valid
# Actual authentication happens with PASS
 
# Some servers reveal whether user exists:
C: USER unknownuser
S: -ERR No such user
 
# Other servers (more secure) don't reveal:  
C: USER unknownuser
S: +OK User accepted, password required

PASS Command:

Provides the password to complete authentication. Must immediately follow USER.

pass-command.txt

# Syntax
PASS password
 
# Example - Success
C: USER alice
S: +OK User accepted
C: PASS correctpassword
S: +OK Mailbox locked and ready
 
# The mailbox is now EXCLUSIVELY LOCKED to this session
# No other POP3 client can access it until QUIT
 
# Example - Failure
C: USER alice  
S: +OK User accepted
C: PASS wrongpassword
S: -ERR Authentication failed
 
# After failure, some servers allow retry:
C: USER alice
S: +OK User accepted
 
# Others lock out after N failures:
C: PASS wrongagain
S: -ERR Account locked, too many failures

Plaintext Password Transmission

USER/PASS sends the password in plaintext. Without TLS encryption, passwords are visible to any network observer. Always use POP3S (port 995) or STARTTLS to encrypt the connection before authentication.

APOP Command:

Alternative authentication that never sends the password in plaintext.

apop-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Server greeting includes unique timestamp
S: +OK POP3 server ready <1896.697170952@mail.example.com>
 
# Syntax: APOP username digest
# digest = MD5(timestamp + password)
 
# Example
# Timestamp: <1896.697170952@mail.example.com>
# Password: secret123
# Concatenated: <1896.697170952@mail.example.com>secret123
# MD5 hash: c4c9334bac560ecc979e58001b3e22fb
 
C: APOP alice c4c9334bac560ecc979e58001b3e22fb
S: +OK Mailbox locked and ready
 
# The password never appears on the wire!
# Only the MD5 hash of (timestamp + password) is sent
# Timestamp changes each session, preventing replay attacks

USER/PASS vs APOP Comparison
Aspect	USER/PASS	APOP
Password on wire	Plaintext (vulnerable)	Never (hashed)
Replay protection	None	Timestamp prevents replay
Server requirement	Universal support	Must provide timestamp
Client complexity	Trivial	Requires MD5 implementation
Modern recommendation	Only with TLS	Acceptable without TLS

Modern Best Practice

Use TLS encryption (POP3S or STARTTLS) regardless of authentication method. APOP prevents password exposure but doesn't encrypt message content. TLS protects everything.

Mailbox Information Commands

These commands query mailbox status without retrieving message content.

STAT Command:

Returns the number of messages and total size in octets (bytes).

stat-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Syntax (no arguments)
STAT
 
# Response: +OK message-count mailbox-size
 
# Example
C: STAT
S: +OK 3 25600
 
# Interpretation:
# - 3 messages in mailbox
# - 25,600 bytes total size
 
# Empty mailbox
C: STAT
S: +OK 0 0

LIST Command:

Lists messages with their individual sizes. Can list all messages or a specific one.

list-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Syntax for all messages
LIST
 
# Multi-line response with all messages
C: LIST
S: +OK 3 messages (25600 octets)
S: 1 8000
S: 2 10000
S: 3 7600
S: .
 
# Format: message-number size-in-octets
 
# Syntax for specific message
LIST message-number
 
# Single-line response
C: LIST 2
S: +OK 2 10000
 
# Non-existent message
C: LIST 99
S: -ERR No such message
 
# Deleted message (marked but not yet committed)
C: DELE 2
S: +OK Message 2 deleted
C: LIST 2
S: -ERR Message 2 has been deleted

UIDL Command:

Returns unique identifiers for messages. These IDs persist across sessions.

uidl-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Syntax for all messages
UIDL
 
# Multi-line response
C: UIDL
S: +OK
S: 1 XYZ123abc456
S: 2 ABC789def012  
S: 3 MNO345ghi678
S: .
 
# Format: message-number unique-id
 
# Syntax for specific message
UIDL message-number
 
C: UIDL 2
S: +OK 2 ABC789def012
 
# UID characteristics:
# - 1-70 printable ASCII characters
# - Unique within mailbox
# - Persistent until message deleted
# - Server-generated (format varies)
 
# Common UID formats across servers:
# - Gmail: Numeric string
# - Exchange: GUID format
# - Dovecot: Hash-based

UIDL is Optional

The UIDL command is technically optional per RFC 1939. If unsupported, the server returns -ERR UIDL not implemented. However, virtually all modern servers support it—it's essential for leave-on-server functionality.

Message Retrieval Commands

These commands retrieve message content from the mailbox.

RETR Command:

Retrieves the complete message (headers + body).

retr-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# Syntax
RETR message-number
 
# Response: +OK octets, then message content, then .
 
C: RETR 1
S: +OK 1500 octets
S: Received: from mail.example.com (mail.example.com [192.0.2.1])
S:         by recipient.example.org with SMTP
S:         for <user@example.org>; Sat, 15 Jan 2026 10:30:00 -0500
S: From: Alice <alice@example.com>
S: To: Bob <bob@example.org>
S: Subject: Meeting Tomorrow
S: Date: Sat, 15 Jan 2026 10:25:00 -0500
S: Message-ID: <unique-id-12345@example.com>
S: MIME-Version: 1.0
S: Content-Type: text/plain; charset="UTF-8"
S: 
S: Hi Bob,
S: 
S: Just confirming our meeting tomorrow at 2pm.
S: 
S: Best regards,
S: Alice
S: .
 
# Non-existent message
C: RETR 99
S: -ERR No such message
 
# Deleted message
C: RETR 2
S: -ERR Message 2 has been deleted

TOP Command:

Retrieves headers plus the first N lines of the message body. Optional but widely supported.

top-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# Syntax
TOP message-number lines
 
# Example: Get headers plus 5 body lines
C: TOP 1 5
S: +OK
S: From: alice@example.com
S: To: bob@example.org
S: Subject: Long Document Attached
S: Date: Sat, 15 Jan 2026 10:30:00 -0500
S: Content-Type: multipart/mixed; boundary="----=_Part_1234"
S: 
S: ------=_Part_1234
S: Content-Type: text/plain
S: 
S: Hi Bob,
S: 
S: Please find the document attached.
S: .
 
# Headers only (0 body lines)
C: TOP 1 0
S: +OK
S: From: alice@example.com
S: To: bob@example.org
S: Subject: Long Document Attached
S: Date: Sat, 15 Jan 2026 10:30:00 -0500
S: Content-Type: multipart/mixed; boundary="----=_Part_1234"
S: 
S: .
 
# Note: The blank line separating headers from body is included

RETR vs TOP Comparison
Aspect	RETR	TOP
Content retrieved	Complete message	Headers + N body lines
Bandwidth usage	Full message size	Minimal
Use case	Downloading mail	Previewing/filtering
Attachments	Complete retrieval	Usually truncated
RFC status	Required	Optional

Efficient Previewing

Use TOP n 0 to efficiently retrieve only headers for spam filtering or preview display. This is especially valuable on slow connections or when dealing with large attachments you may not want to download.

Message Management Commands

These commands manage message state in the mailbox.

DELE Command:

Marks a message for deletion. The deletion is committed only when the session ends via QUIT.

dele-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Syntax
DELE message-number
 
# Mark message for deletion
C: DELE 1
S: +OK Message 1 deleted
 
# Message is now excluded from LIST, RETR, etc.
C: LIST 1
S: -ERR Message 1 has been deleted
 
# But deletion isn't permanent yet!
# Only committed on QUIT
 
# Attempting to delete already-deleted message
C: DELE 1
S: -ERR Message 1 has been deleted
 
# Non-existent message
C: DELE 99
S: -ERR No such message

RSET Command:

Resets the session, unmarking all messages marked for deletion.

rset-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Syntax (no arguments)
RSET
 
# Scenario: Multiple deletions, then reset
C: STAT
S: +OK 5 10000
 
C: DELE 1
S: +OK Message 1 deleted
C: DELE 2
S: +OK Message 2 deleted
C: DELE 3
S: +OK Message 3 deleted
 
# Changed mind, want to undo
C: RSET
S: +OK 5 messages (10000 octets)
 
# All messages are unmarked
C: STAT
S: +OK 5 10000
 
# Messages are accessible again
C: LIST 1
S: +OK 1 2000

NOOP Command:

No operation. Used as a keep-alive to prevent server timeout.

noop-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# Syntax (no arguments)
NOOP
 
C: NOOP
S: +OK
 
# Use case: Prevent timeout during long processing
 
# Typical scenario:
# - Server auto-timeout: 10 minutes
# - Client is processing a large message locally
# - Client sends NOOP every 5 minutes to keep session alive
 
# NOOP has no side effects
# Does not reset any timers related to message marking
# Does not modify mailbox state in any way

Keep-Alive Strategy

Email clients typically send NOOP periodically during long sessions. The interval should be less than the server's idle timeout. Most servers have a 10-15 minute timeout, so NOOP every 5-8 minutes is a reasonable strategy.

Session Control Commands

QUIT Command:

Ends the POP3 session. Behavior depends on current state.

quit-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Syntax (no arguments)
QUIT
 
# QUIT from AUTHORIZATION state (before authentication)
C: USER alice
S: +OK User accepted
C: QUIT
S: +OK POP3 server signing off
# Connection closed, no mailbox modifications
 
# QUIT from TRANSACTION state (after authentication)
C: DELE 1
S: +OK Message 1 deleted
C: DELE 2
S: +OK Message 2 deleted
C: QUIT
S: +OK POP3 server signing off (2 messages deleted)
 
# QUIT triggers UPDATE state:
# 1. Deletions are committed (permanent)
# 2. Mailbox statistics updated
# 3. Exclusive lock released
# 4. Connection closed
 
# Response indicates what happened
S: +OK POP3 server signing off (2 messages deleted, 3 remaining)

UPDATE State Processing:

When QUIT is issued in TRANSACTION state, the server enters UPDATE state and:

Commits deletions: All DELE-marked messages are permanently removed
Updates metadata: Message counts, UIDs, indices are updated
Releases lock: Exclusive mailbox lock is released
Closes connection: TCP connection is terminated

If any step fails, the server may:

Roll back all deletions
Leave the mailbox in original state
Report error but still close connection

QUIT Behavior by State
Starting State	Action	Mailbox Effect
AUTHORIZATION	Close connection	None (no access)
TRANSACTION (no DELE)	Close connection	None (no deletions)
TRANSACTION (with DELE)	UPDATE then close	Marked messages deleted

Always QUIT Properly

Dropping the connection without QUIT leaves the mailbox locked until server timeout. Other clients will receive 'mailbox locked' errors. Always issue QUIT to cleanly release the lock, even if no deletions were made.

Optional Extension Commands

Beyond RFC 1939's core commands, several extensions add functionality.

CAPA Command (RFC 2449):

Returns a list of capabilities the server supports.

capa-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Syntax (no arguments)
CAPA
 
# Example response
C: CAPA
S: +OK Capability list follows
S: TOP
S: UIDL
S: USER
S: SASL PLAIN LOGIN CRAM-MD5
S: STLS
S: PIPELINING
S: EXPIRE 30
S: RESP-CODES
S: .
 
# Important capabilities:
# TOP - Server supports TOP command
# UIDL - Server supports UIDL command
# STLS - Server supports STARTTLS
# SASL - Supported SASL mechanisms
# PIPELINING - Can send multiple commands without waiting
# EXPIRE n - Messages auto-expire after n days

STLS Command (RFC 2595):

Upgrades the connection to TLS encryption.

stls-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# Connect to port 110 (unencrypted)
# Check capabilities first
C: CAPA
S: +OK Capability list follows
S: STLS
S: ...
S: .
 
# Initiate TLS upgrade
C: STLS
S: +OK Begin TLS negotiation
 
# TLS handshake happens here (at transport layer)
# All subsequent communication is encrypted
 
# After TLS established, re-check capabilities
C: CAPA
S: +OK Capability list follows
S: TOP
S: UIDL
S: USER
S: SASL PLAIN
S: .
# Note: STLS disappears (already upgraded)

AUTH Command (RFC 1734, 5034):

Supports SASL authentication mechanisms beyond USER/PASS.

auth-command.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Syntax
AUTH mechanism [initial-response]
 
# Example: PLAIN authentication
# PLAIN format: base64(\0username\0password)
C: AUTH PLAIN dXNlcm5hbWUAcGFzc3dvcmQ=
S: +OK Logged in
 
# Example: LOGIN authentication (multi-step)
C: AUTH LOGIN
S: + VXNlcm5hbWU6
C: dXNlcm5hbWU=
S: + UGFzc3dvcmQ6
C: cGFzc3dvcmQ=
S: +OK Logged in
 
# Example: CRAM-MD5 (challenge-response)
C: AUTH CRAM-MD5
S: + PDE4OTYuNjk3MTcwOTUyQHBvc3RvZmZpY2UucmVzdG9uLm1jaS5uZXQ+
C: <base64-encoded-response>
S: +OK Logged in

Common SASL Mechanisms
Mechanism	Security	Notes
PLAIN	Requires TLS	Base64 encoded, plaintext password
LOGIN	Requires TLS	Similar to PLAIN, two-step
CRAM-MD5	Medium	Challenge-response, no plaintext password
SCRAM-SHA-256	High	Modern, strong, recommended
XOAUTH2	High	OAuth 2.0 tokens (Gmail, etc.)

OAuth in POP3

Major providers (Google, Microsoft) support OAuth via SASL XOAUTH2. This allows authentication using OAuth tokens instead of passwords, enabling POP3 access for accounts with multi-factor authentication.

Complete Session Example

Let's trace a complete, realistic POP3 session from connection to disconnection.

complete-pop3-session.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
# === CONNECTION ===
# Establish TCP connection to port 110
# Server sends greeting, enters AUTHORIZATION state
S: +OK POP3 server ready <9812.1234567890@mail.example.com>
 
# Check what the server supports
C: CAPA
S: +OK Capability list follows
S: TOP
S: UIDL
S: USER
S: STLS
S: SASL PLAIN LOGIN
S: .
 
# === UPGRADE TO TLS ===
C: STLS
S: +OK Begin TLS negotiation
# [TLS handshake completes - connection now encrypted]
 
# === AUTHENTICATION ===
C: USER alice@example.com
S: +OK User accepted
 
C: PASS supersecretpassword
S: +OK Mailbox locked and ready
# Now in TRANSACTION state
 
# === MAILBOX INQUIRY ===
C: STAT
S: +OK 4 32768
 
C: LIST
S: +OK 4 messages (32768 octets)
S: 1 8192
S: 2 4096
S: 3 16384
S: 4 4096
S: .
 
# Check for new messages (using saved UIDs from last session)
C: UIDL
S: +OK
S: 1 AAA111
S: 2 BBB222
S: 3 CCC333  
S: 4 DDD444
S: .
# Client notes: AAA111 and BBB222 were downloaded before
# CCC333 and DDD444 are new
 
# === PREVIEW NEW MESSAGES ===
C: TOP 3 0
S: +OK
S: From: newsletter@company.com
S: Subject: Weekly Newsletter - January 15
S: Date: Sat, 15 Jan 2026 08:00:00 -0500
S: Content-Type: multipart/alternative
S: 
S: .
 
C: TOP 4 0
S: +OK
S: From: friend@example.org
S: Subject: Dinner plans?
S: Date: Sat, 15 Jan 2026 09:30:00 -0500
S: Content-Type: text/plain
S: 
S: .
 
# === DOWNLOAD NEW MESSAGES ===
C: RETR 3
S: +OK 16384 octets
S: [complete message content...]
S: .
 
C: RETR 4
S: +OK 4096 octets
S: [complete message content...]
S: .
 
# === CLEANUP (using download-and-delete model) ===
# Mark all messages for deletion
C: DELE 1
S: +OK Message 1 deleted
C: DELE 2
S: +OK Message 2 deleted
C: DELE 3
S: +OK Message 3 deleted
C: DELE 4
S: +OK Message 4 deleted
 
# === END SESSION ===
C: QUIT
S: +OK POP3 server signing off (4 messages deleted)
# Connection closed
# All deletions committed in UPDATE state

Manual Testing

You can replicate this session manually using openssl s_client -connect mail.server.com:995 for POP3S. This is invaluable for debugging client configuration issues or understanding server behavior.

Summary: POP3 Commands

POP3's command set is intentionally minimal, making the protocol easy to implement and debug. Let's consolidate the key points:

Key Takeaways

•Text-based protocol — All commands are human-readable ASCII, with +OK/-ERR responses for simple parsing.
•State-dependent commands — Commands are valid only in specific states (AUTHORIZATION vs TRANSACTION).
•USER/PASS for authentication — Simple but sends password in plaintext; always use TLS.
•APOP for secure auth — MD5-based challenge-response avoids plaintext passwords.
•STAT/LIST/UIDL for inquiry — Discover mailbox contents without downloading messages.
•RETR/TOP for retrieval — RETR downloads complete messages; TOP provides headers + preview.
•DELE/RSET for management — Mark messages for deletion; RSET to undo before QUIT.
•QUIT is critical — Commits deletions and releases locks; always end sessions with QUIT.
•Extensions add capability — CAPA, STLS, AUTH extend base functionality.

What's Next:

With the complete command set understood, we'll examine POP3 authentication mechanisms in depth—covering USER/PASS, APOP, SASL mechanisms, and modern OAuth integration.

Page Complete

You now have a complete reference for POP3 commands. You understand the syntax, responses, state requirements, and practical usage of every standard command. Next, we'll dive deep into authentication mechanisms.