IMAP Tools

Warnings

• breaking In v1.12.0, MailMessage.headers changed from a standard dictionary to a 'LazyHeaders' dict-like mapping. While often backward compatible, direct access to all headers might now trigger lazy loading, potentially affecting performance or requiring slight code adjustments if specific dict behaviors (e.g., direct `dict()` conversion) are relied upon.
  Fix: Most common dictionary operations will work. If converting to a full dictionary immediately, use `dict(msg.headers)`. For optimal performance, access specific headers directly (e.g., `msg.headers['Subject']`) to benefit from lazy loading.
• breaking In v1.11.0, `MailBoxTls` was renamed to `MailBoxStartTls`. Additionally, `MailBoxStartTls` now defaults to port 143 (standard IMAP) and explicitly raises a `ValueError` if port 993 (IMAPS) is specified, as 993 is intended for `MailBox` (IMAP-SSL/TLS) connections.
  Fix: Replace `MailBoxTls` with `MailBoxStartTls`. Ensure you are using the correct class for your connection type: `MailBox` for IMAPS (port 993, SSL/TLS from start), `MailBoxStartTls` for IMAP with STARTTLS (port 143, upgrade to TLS).
• breaking Starting with v1.9.0, support for Python versions 3.3, 3.4, 3.5, 3.6, and 3.7 was dropped. The library now requires Python 3.8 or newer.
  Fix: Upgrade your Python environment to version 3.8 or later.
• gotcha When performing bulk operations like `copy`, `move`, `flag`, or `delete` on a large number of messages, the IMAP command generated by the server might become too large, leading to server errors. The behavior and result types of `BaseMailBox.move` also changed in v1.10.0.
  Fix: Utilize the `chunks` argument (e.g., `mailbox.move(msgs, 'folder', chunks=500)`) to specify the number of UIDs to process in a single IMAP command, splitting large operations into smaller, manageable batches. For fetching, use the `limit` argument to restrict the number of messages retrieved at once.
• gotcha Version 1.7.3 included a fix for `CVE-2023-27043` related to malformed addresses in `email.parseaddr()`. This might subtly alter how malformed email addresses are processed or rejected, potentially causing changes in behavior for applications handling emails with non-standard address formats.
  Fix: Review existing code that processes `MailMessage.from_`, `MailMessage.to`, etc., especially if dealing with potentially malformed emails, to ensure compatibility with stricter parsing. Ensure robust error handling for address parsing.

Install

• pip install imap-tools Install stable version

Imports

• MailBox

  from imap_tools import MailBox

• MailBoxStartTls

  from imap_tools import MailBoxStartTls

  MailBoxTls was renamed to MailBoxStartTls in v1.11.0. The new class also defaults to port 143 and does not work with port 993.
• AND

  from imap_tools import AND

  Used for building complex search criteria.

Quickstart

Connects to an IMAP server using environment variables for credentials, fetches the subjects and senders of the first 5 unseen emails in the INBOX, and prints them. It demonstrates the use of `MailBox` as a context manager and basic `fetch` with search criteria.

import os
from imap_tools import MailBox, AND

IMAP_HOST = os.environ.get('IMAP_HOST', 'imap.mail.com')
IMAP_USER = os.environ.get('IMAP_USER', 'test@mail.com')
IMAP_PASS = os.environ.get('IMAP_PASS', 'your-password')

try:
    with MailBox(IMAP_HOST).login(IMAP_USER, IMAP_PASS) as mailbox:
        # Fetch all unseen emails from the INBOX and print their subject and sender
        print(f"Connected to IMAP host: {IMAP_HOST}")
        print("Fetching unseen emails...")
        for msg in mailbox.fetch(criteria=AND(seen=False), mark_seen=False, limit=5):
            print(f"From: {msg.from_}, Subject: {msg.subject}")
except Exception as e:
    print(f"An error occurred: {e}")