`poplib`

The Python poplib module provides a client implementation of the Post Office Protocol version 3 (POP3), as defined in RFC 1939. It lets you connect to a POP3 server, authenticate with a user account, and download or delete messages from a mailbox.

Note: To run the examples below, you’ll need access to a POP3 server, either a self-hosted mail server or an email provider that still supports POP3, along with valid credentials and at least one message in the mailbox. The hostname pop.example.com is a placeholder, so replace it with your real server’s address.

Here’s a quick example of how you’d use poplib to connect to a mail server and check how many messages are waiting:

import poplib

mailbox = poplib.POP3_SSL("pop.example.com")
mailbox.user("username")
mailbox.pass_("password")

count, size = mailbox.stat()
print(f"{count} messages, {size} bytes")

mailbox.quit()

Key Features

Connects to POP3 servers with or without SSL
Authenticates using plain credentials or the more secure APOP command
Lists messages and reports mailbox size with stat() and list()
Retrieves full messages or only their headers and top lines
Flags messages for deletion and commits changes on quit
Upgrades an unencrypted connection to TLS with stls()

Frequently Used Classes and Functions

Object	Type	Description
`poplib.POP3`	Class	Implements a plain POP3 client connection on port 110
`poplib.POP3_SSL`	Class	Extends `POP3` to use SSL or TLS on port 995
`poplib.POP3.user()`	Method	Sends the user name to the server
`poplib.POP3.pass_()`	Method	Sends the password and locks the mailbox until `quit()`
`poplib.POP3.stat()`	Method	Returns the message count and total mailbox size
`poplib.POP3.list()`	Method	Returns a list of messages with their sizes in octets
`poplib.POP3.retr()`	Method	Retrieves a full message by its index
`poplib.POP3.dele()`	Method	Marks a message for deletion on quit
`poplib.POP3.quit()`	Method	Commits pending deletions and closes the connection
`poplib.error_proto`	Exception	Raised when the server returns a protocol error

Examples

Connecting to a POP3 server over SSL and authenticating:

import poplib

mailbox = poplib.POP3_SSL("pop.example.com")
mailbox.user("username")
mailbox.pass_("password")

Listing the messages waiting in the mailbox:

response, messages, octets = mailbox.list()
print(response)
print(messages)

Retrieving the first message as a list of raw lines:

response, lines, octets = mailbox.retr(1)
print(lines[0])

Flagging a message for deletion and committing the change:

mailbox.dele(1)
mailbox.quit()

Common Use Cases

The most common tasks for poplib include:

Downloading messages from a mailbox to a local client
Archiving an account’s contents before switching providers
Writing scripts that monitor an inbox for new messages
Removing old messages from servers with limited storage
Interacting with legacy systems that only expose POP3

Real-World Example

Here’s how you can connect to a POP3 server, download every message in the inbox, and parse the subject line of each one using the email module:

import email
import poplib
from email.header import decode_header

mailbox = poplib.POP3_SSL("pop.example.com")
mailbox.user("username")
mailbox.pass_("password")

count, size = mailbox.stat()
for index in range(1, count + 1):
    response, lines, octets = mailbox.retr(index)
    raw_message = b"\r\n".join(lines)
    message = email.message_from_bytes(raw_message)
    subject, encoding = decode_header(message["Subject"])[0]
    if isinstance(subject, bytes):
        subject = subject.decode(encoding or "utf-8")
    print(f"{index}: {subject}")

mailbox.quit()

In this example, poplib handles the POP3 session while the email module parses each raw message into a structured object so that you can read individual headers like the subject line. The Python documentation notes that POP3 is obsolescent and points to imaplib as an alternative for modern mail server interactions.

Tutorial

Sending Emails With Python

In this tutorial, you'll learn how to send emails using Python. Find out how to send plain-text and HTML messages, add files as attachments, and send personalized emails to multiple people.

intermediate web-dev

For additional information on related topics, take a look at the following resources: