Python script to read a POP3 mailbox and save all subject lines

Below is a ready‑to‑run script that:

1. Connects securely to a POP3 server (SSL on port 995).
2. Logs in using credentials entered at runtime (so they aren’t stored in the file).
3. Iterates over every message, parses it with the standard email library, and decodes the subject handling any RFC‑2047 encoding.
4. Writes each subject to email_subjects.txt (UTF‑8).

#!/usr/bin/env python3
"""
POP3 Subject Extractor
----------------------
Connects to a POP3 server, retrieves every message, extracts the
Subject header (properly decoded), and saves all subjects to a text file.
"""

import poplib
import getpass
from email import policy
from email.parser import BytesParser
from email.header import decode_header

# -------------------- Configuration --------------------
POP_SERVER = "pop.gmail.com"      # Change to your provider's POP server
POP_PORT   = 995                  # Standard POP3‑SSL port
OUTPUT_FILE = "email_subjects.txt"
# -----------------------------------------------------

def decode_subject(raw_subject):
    """Return a clean, Unicode string for the Subject header."""
    if raw_subject is None:
        return "[No Subject]"
    # decode_header may return several parts (e.g., mixed encodings)
    parts = decode_header(raw_subject)
    decoded = ""
    for part, enc in parts:
        if isinstance(part, bytes):
            decoded += part.decode(enc or "utf-8", errors="replace")
        else:
            decoded += part
    return decoded.strip()

def fetch_subjects(server, user, password):
    """Log in to POP3‑SSL, fetch and decode every Subject line."""
    subjects = []
    # Connect securely
    pop_conn = poplib.POP3_SSL(server, POP_PORT, timeout=15)
    pop_conn.user(user)
    pop_conn.pass_(password)

    # Number of messages
    resp, listings, octets = pop_conn.list()
    total = len(listings)
    print(f"Found {total} messages in the mailbox.\n")

    for i in range(1, total + 1):
        # Retrieve raw message bytes
        resp, lines, octets = pop_conn.retr(i)
        raw_message = b"\n".join(lines)

        # Parse the message
        msg = BytesParser(policy=policy.default).parsebytes(raw_message)

        # Decode subject
        subject = decode_subject(msg["Subject"])
        subjects.append(subject)

        print(f"{i}/{total}: {subject}")

    pop_conn.quit()
    return subjects

def save_to_file(subjects, filename):
    """Write the list of subjects to a UTF‑8 text file."""
    with open(filename, "w", encoding="utf-8") as f:
        for idx, subj in enumerate(subjects, start=1):
            f.write(f"{idx}. {subj}\n")
    print(f"\nAll subjects saved to {filename}")

def main():
    print("=== POP3 Email Subject Extractor ===")
    server = input(f"POP server [{POP_SERVER}]: ").strip() or POP_SERVER
    email_addr = input("Email address: ").strip()
    pwd = getpass.getpass("Password (or app‑specific password): ")

    subjects = fetch_subjects(server, email_addr, pwd)
    if subjects:
        save_to_file(subjects, OUTPUT_FILE)
    else:
        print("No subjects retrieved.")

if __name__ == "__main__":
    main()

How it works

Customisation tips

• Change output filename: modify OUTPUT_FILE or pass a different name to save_to_file().
• Filter subjects: add an if statement in the loop to keep only subjects that contain a keyword.
• Skip SSL: replace POP3_SSL with poplib.POP3 if you need a non‑TLS connection (not recommended)².
• Credential handling: store EMAIL and PASSWORD in environment variables (os.getenv) for automated runs.

Security notes

• Use app‑specific passwords for Gmail/Outlook when two‑factor authentication is enabled (see Gmail’s App Passwords page).
• Never commit passwords to version control.
• SSL/TLS is essential; POP3 without encryption exposes credentials in cleartext.

Troubleshooting

• Authentication errors – Verify POP3 is enabled in your email account settings and that you’re using the correct server/port.
• Empty subjects – Some messages legitimately have no Subject header; the script records “[No Subject]”.
• Unicode errors – The errors="replace" argument ensures any unknown bytes are safely replaced.

With this script you can quickly audit the subjects in any POP3 mailbox and keep a tidy log for further processing or archiving. Happy scripting!