`imaplib`

The imaplib module provides tools for interacting with mail servers using the Internet Message Access Protocol (IMAP). This module allows you to connect to an IMAP server, authenticate, and perform operations such as fetching and deleting emails.

Here’s a quick toy example of how you’d use imaplib to log in to your email server:

>>> import imaplib
>>> mail = imaplib.IMAP4_SSL("imap.example.com")
>>> mail.login("username", "password")
('OK', [b'Authenticated'])
>>> mail.logout()
('BYE', [b'LOGOUT Requested'])

Key Features

Connects to IMAP servers with or without SSL
Authenticates with a username and password
Lists mailboxes on the server
Fetches email messages and their parts
Searches mailboxes using various criteria
Copies, flags, and permanently removes messages with copy(), store(), and expunge()
Waits for real-time mailbox updates with the IDLE command (Python 3.14+)

Frequently Used Classes and Functions

Object	Type	Description
`imaplib.IMAP4`	Class	Provides basic IMAP functionality
`imaplib.IMAP4_SSL`	Class	Extends `IMAP4` to use SSL for secure connections
`imaplib.IMAP4.login()`	Method	Authenticates with the server
`imaplib.IMAP4.select()`	Method	Selects a mailbox for operations
`imaplib.IMAP4.search()`	Method	Searches the mailbox for specific messages
`imaplib.IMAP4.fetch()`	Method	Retrieves specific messages from the server
`imaplib.IMAP4.logout()`	Method	Logs out and closes the connection
`imaplib.IMAP4.idle()`	Method	Waits for real-time mailbox updates using the IDLE command

Examples

Connecting to an IMAP server and logging in:

>>> import imaplib
>>> mail = imaplib.IMAP4_SSL("imap.example.com")
>>> mail.login("username", "password")
('OK', [b'Authenticated'])

Selecting a mailbox and searching for all emails:

>>> mail.select("inbox")
('OK', [b'42'])
>>> result, data = mail.search(None, "ALL")
>>> mail_ids = data[0].split()

Fetching an email by ID:

>>> result, data = mail.fetch(mail_ids[0], "(RFC822)")
>>> raw_email = data[0][1]
>>> mail.logout()
('BYE', [b'LOGOUT Requested'])

Common Use Cases

Connecting to an IMAP server to access emails
Searching for emails with specific criteria
Fetching and reading email content
Deleting or moving emails within mailboxes

Real-World Example

Here’s how you can connect to an IMAP server, search for unread emails, and fetch their subject lines:

import imaplib, email

mail = imaplib.IMAP4_SSL("imap.example.com")
mail.login("username", "password")
mail.select("inbox")

result, data = mail.search(None, "UNSEEN")
for num in data[0].split():
    result, msg_data = mail.fetch(num, "(RFC822)")
    msg = email.message_from_bytes(msg_data[0][1])
    print(msg["subject"])

mail.logout()