{"id":5963,"library":"imap-tools","title":"IMAP Tools","description":"imap-tools is a high-level Python library designed for working with email via the IMAP protocol. It provides a user-friendly interface for common email operations such as fetching, parsing, searching, moving, and deleting messages, as well as managing folders. The library is actively maintained, with frequent minor releases, and is currently at version 1.12.0.","status":"active","version":"1.12.0","language":"en","source_language":"en","source_url":"https://github.com/ikvk/imap_tools","tags":["email","imap","mail","client","networking"],"install":[{"cmd":"pip install imap-tools","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"MailBox","correct":"from imap_tools import MailBox"},{"note":"MailBoxTls was renamed to MailBoxStartTls in v1.11.0. The new class also defaults to port 143 and does not work with port 993.","wrong":"from imap_tools import MailBoxTls","symbol":"MailBoxStartTls","correct":"from imap_tools import MailBoxStartTls"},{"note":"Used for building complex search criteria.","symbol":"AND","correct":"from imap_tools import AND"}],"quickstart":{"code":"import os\nfrom imap_tools import MailBox, AND\n\nIMAP_HOST = os.environ.get('IMAP_HOST', 'imap.mail.com')\nIMAP_USER = os.environ.get('IMAP_USER', 'test@mail.com')\nIMAP_PASS = os.environ.get('IMAP_PASS', 'your-password')\n\ntry:\n    with MailBox(IMAP_HOST).login(IMAP_USER, IMAP_PASS) as mailbox:\n        # Fetch all unseen emails from the INBOX and print their subject and sender\n        print(f\"Connected to IMAP host: {IMAP_HOST}\")\n        print(\"Fetching unseen emails...\")\n        for msg in mailbox.fetch(criteria=AND(seen=False), mark_seen=False, limit=5):\n            print(f\"From: {msg.from_}, Subject: {msg.subject}\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.12.0"},{"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).","message":"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.","severity":"breaking","affected_versions":">=1.11.0"},{"fix":"Upgrade your Python environment to version 3.8 or later.","message":"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.","severity":"breaking","affected_versions":">=1.9.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.","message":"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.","severity":"gotcha","affected_versions":">=1.10.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.7.3"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}