{"id":3516,"library":"imapclient","title":"IMAPClient","description":"IMAPClient is an easy-to-use, Pythonic, and complete IMAP client library. It provides a higher-level API over Python's built-in `imaplib` module, simplifying interaction with IMAP servers. The library is actively maintained, with its current version being 3.1.0, and receives regular updates.","status":"active","version":"3.1.0","language":"python","source_language":"en","source_url":"https://github.com/mjs/imapclient/","tags":["email","imap","client","mail"],"install":[{"cmd":"pip install imapclient","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"IMAPClient","correct":"from imapclient import IMAPClient"}],"quickstart":{"code":"import os\nfrom imapclient import IMAPClient\n\n# Environment variables for credentials\nIMAP_HOST = os.environ.get('IMAP_HOST', 'imap.example.com')\nIMAP_USERNAME = os.environ.get('IMAP_USERNAME', 'your_username')\nIMAP_PASSWORD = os.environ.get('IMAP_PASSWORD', 'your_password')\n\ntry:\n    # Connect to the IMAP server using a context manager for automatic logout\n    with IMAPClient(IMAP_HOST, ssl=True) as client:\n        client.login(IMAP_USERNAME, IMAP_PASSWORD)\n        print(f\"Successfully logged in to {IMAP_HOST} as {IMAP_USERNAME}\")\n\n        # Select the INBOX folder\n        select_info = client.select_folder('INBOX')\n        print(f\"Selected INBOX: {select_info[b'EXISTS']} messages\")\n\n        # Search for all messages\n        messages = client.search(['ALL'])\n        print(f\"Found {len(messages)} messages.\")\n\n        if messages:\n            # Fetch subjects of the first 5 messages (or fewer if not enough)\n            fetch_uids = messages[:5]\n            response = client.fetch(fetch_uids, ['BODY.PEEK[HEADER.FIELDS (SUBJECT)]'])\n\n            print(\"\\n--- Subjects of first messages ---\")\n            for uid, data in response.items():\n                subject_bytes = data[b'BODY[HEADER.FIELDS (SUBJECT)]']\n                try:\n                    # Decode subject, handling potential encoding issues\n                    subject = subject_bytes.decode('utf-8', errors='ignore').strip()\n                    print(f\"UID {uid}: {subject}\")\n                except UnicodeDecodeError:\n                    print(f\"UID {uid}: Subject decoding failed\")\n        else:\n            print(\"No messages in INBOX.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart connects to an IMAP server, logs in using credentials from environment variables, selects the 'INBOX' folder, and fetches the subjects of the first few messages. It demonstrates basic connection, authentication, folder selection, and message fetching. Ensure `IMAP_HOST`, `IMAP_USERNAME`, and `IMAP_PASSWORD` environment variables are set."},"warnings":[{"fix":"Upgrade to Python 3.8+ and `imapclient >= 3.0.0`. If Python 2 is required, use `imapclient < 3.0.0`.","message":"Version 3.0.0 removed official support for Python 2.x. Applications targeting Python 2 must remain on `imapclient < 3.0.0`.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Ensure your project runs on Python 3.8 or newer.","message":"Version 3.0.0 also removed support for Python 3.4, 3.5, and 3.6. The current officially supported Python versions are 3.8 through 3.13.","severity":"breaking","affected_versions":"<3.0.0"},{"fix":"Upgrade `imapclient` to version 3.1.0 or newer to ensure full compatibility with Python 3.14+.","message":"Users running Python 3.14+ might experience compatibility issues with `IMAP4_TLS` if using `imapclient` versions older than 3.1.0.","severity":"gotcha","affected_versions":"<3.1.0 (when used with Python 3.14+)"},{"fix":"If connecting to a server with a self-signed certificate (not recommended for production without proper CA setup), you may need to configure the `ssl_context` to disable hostname checking or verification. For example:\n```python\nimport ssl\ncontext = ssl.create_default_context()\ncontext.check_hostname = False\ncontext.verify_mode = ssl.CERT_NONE\nclient = IMAPClient(host, ssl_context=context)\n```","message":"Since version 1.0, IMAPClient enables strict TLS certificate verification by default. Connections to servers with self-signed or invalid certificates may fail.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'3.1.0':45 'activ':38 'api':21 'built':26 'built-in':25 'client':13,52 'complet':11 'current':42 'easi':6 'easy-to-us':5 'email':50 'higher':19 'higher-level':18 'imap':12,33,51 'imapcli':1,2 'imaplib':28 'interact':31 'level':20 'librari':14,36 'mail':53 'maintain':39 'modul':29 'provid':16 'python':9,23 'receiv':47 'regular':48 'server':34 'simplifi':30 'updat':49 'use':8 'version':43","created_at":"2026-04-11T17:32:57.686294+00:00","updated_at":"2026-04-17T14:54:04.785907+00:00","problems":[{"fix":"Install the package using pip: `pip install imapclient`","cause":"The `imapclient` package is not installed in the Python environment you are using.","error":"ModuleNotFoundError: No module named 'imapclient'"},{"fix":"Double-check credentials, ensure IMAP is enabled for the account, and if 2FA is active, generate and use an app-specific password or configure OAuth for authentication.","cause":"The IMAP server rejected the login attempt, usually due to incorrect username/password, disabled IMAP access, or requiring an app-specific password/OAuth for accounts with 2-Factor Authentication (2FA) enabled.","error":"imapclient.exceptions.LoginError: b'LOGIN failed.'"},{"fix":"On macOS, run `/Applications/Python \\<version\\>/Install Certificates.command`. Alternatively, use the `certifi` package or provide a custom `ssl_context` to `IMAPClient` to handle certificates. For testing, you can pass `ssl_context=ssl._create_unverified_context()` (not recommended for production).","cause":"The Python environment cannot verify the SSL certificate presented by the IMAP server, often due to missing or outdated root certificates on the system (common on macOS) or self-signed certificates.","error":"ssl.SSLError: CERTIFICATE_VERIFY_FAILED"},{"fix":"This is a compatibility issue with Python 3.14 that requires an update to `imapclient`. Check for a newer version of `imapclient` or use a supported Python version (e.g., Python 3.13 or earlier) if an update is not yet available.","cause":"This error occurs with Python 3.14 due to a change in the standard library's `imaplib.IMAP4.file` attribute, which became a read-only property, breaking `imapclient`'s internal handling.","error":"AttributeError: property 'file' of 'IMAP4_TLS' object has no setter"},{"fix":"When fetching the raw email, use `email.message_from_bytes()` from Python's `email` module to robustly parse the message, which automatically handles different encodings. For example: `email.message_from_bytes(message_data[b'RFC822'], policy=policy.default)`","cause":"This error happens when `imapclient` attempts to decode email content as UTF-8, but the email actually contains bytes encoded in a different character set.","error":"UnicodeDecodeError: 'utf-8' codec can't decode byte 0x... in position ...: invalid start byte"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"3.1.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/mjs/imapclient","docs":null,"changelog":null,"pypi":"https://pypi.org/project/imapclient/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}