{"id":7910,"library":"aioimaplib","title":"aioimaplib - Async IMAP Client","description":"aioimaplib is a Python asyncio IMAP4rev1 client library, providing asynchronous access to IMAP servers. It allows developers to interact with email servers, fetch messages, manage mailboxes, and more, using modern async/await syntax. The library is currently at version 2.0.1 and generally follows a release cadence tied to bug fixes and feature enhancements as needed.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/bamthomas/aioimaplib","tags":["async","imap","email","networking","client"],"install":[{"cmd":"pip install aioimaplib","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for generating self-signed certificates for testing and potentially other TLS-related functionalities.","package":"trustme","optional":true}],"imports":[{"symbol":"IMAP4_SSL","correct":"from aioimaplib import IMAP4_SSL"},{"note":"Use IMAP4 for plain TCP connections, IMAP4_SSL for implicit TLS (port 993), or IMAP4 with .starttls() for explicit TLS (STARTTLS on port 143).","symbol":"IMAP4","correct":"from aioimaplib import IMAP4"}],"quickstart":{"code":"import aioimaplib\nimport asyncio\nimport os\n\nasync def main():\n    IMAP_HOST = os.environ.get('IMAP_HOST', 'imap.mail.com')\n    IMAP_USER = os.environ.get('IMAP_USER', 'your_email@mail.com')\n    IMAP_PASS = os.environ.get('IMAP_PASS', 'your_password')\n\n    if not all([IMAP_HOST, IMAP_USER, IMAP_PASS]):\n        print(\"Please set IMAP_HOST, IMAP_USER, and IMAP_PASS environment variables.\")\n        return\n\n    try:\n        async with aioimaplib.IMAP4_SSL(host=IMAP_HOST) as client:\n            await client.wait_hello_from_server()\n            await client.login(IMAP_USER, IMAP_PASS)\n            print(f\"Logged in as {IMAP_USER}\")\n\n            status, mailboxes = await client.list()\n            if status == 'OK':\n                print(\"Mailboxes:\")\n                for mb in mailboxes:\n                    print(f\"  {mb.decode('utf-8')}\")\n            else:\n                print(f\"Failed to list mailboxes: {status}\")\n\n            await client.select('INBOX')\n            status, msg_ids = await client.search('ALL')\n            if status == 'OK' and msg_ids[0]:\n                print(f\"INBOX contains {len(msg_ids[0].split())} messages.\")\n            elif status == 'OK':\n                print(\"INBOX is empty.\")\n            else:\n                print(f\"Failed to search INBOX: {status}\")\n\n    except aioimaplib.exceptions.IMAP4Exception as e:\n        print(f\"IMAP error: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred: {e}\")\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"This quickstart demonstrates how to connect to an IMAP server using TLS (IMAP4_SSL), log in, list available mailboxes, and count messages in the 'INBOX'. It uses `async with` for connection management and fetches credentials from environment variables."},"warnings":[{"fix":"Migrate to the `async with client:` context manager (which uses `connect()` and `disconnect()` internally) or explicitly call `await client.connect()` and `await client.disconnect()`.","message":"Version 2.0.0 introduced significant breaking changes to connection management. The `__aenter__` and `__aexit__` methods were removed from the client class.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update your code to use `await client.starttls()` when upgrading from 1.x to 2.x.","message":"The `IMAP4_SSL.start_tls()` method was renamed to `IMAP4.starttls()` in version 2.0.0.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `await client.idle_start()` to initiate IDLE mode and `await client.idle_done()` to terminate it.","message":"The `IMAP4.idle()` method was removed in version 2.0.0. For IMAP IDLE command, more explicit control is now provided.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use `await client.noop_()` instead of the removed `noop()` method.","message":"The `IMAP4.noop()` method was removed in version 2.0.0. The standard `noop` command is now available through the generic command interface.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always include `await client.wait_hello_from_server()` after creating the client instance or after `await client.connect()` to ensure the server is ready before sending commands like `login`.","message":"Failing to call `await client.wait_hello_from_server()` after connection but before login can lead to issues if the server's initial greeting is delayed.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure you are using `async with aioimaplib.IMAP4_SSL(...) as client:` or explicitly calling `await client.connect()` and `await client.disconnect()`. The `__aenter__` and `__aexit__` methods were removed from the class directly and are now handled internally by the `async with` statement through `connect/disconnect`.","cause":"Attempting to use the `async with` context manager with aioimaplib client instances in versions 2.x and later, but using an old syntax or misconfiguring the client. This typically means you are using `aioimaplib` v2+ but with code written for v1.","error":"AttributeError: __aenter__"},{"fix":"Double-check your username and password. If 2-Factor Authentication (2FA) is enabled on your email account, ensure you are using an app-specific password generated for `aioimaplib` or a similar client. Verify server logs if possible.","cause":"Incorrect username or password provided to the `login` command, or the IMAP server is rejecting the credentials (e.g., due to 2FA requiring an app-specific password, or incorrect server configuration).","error":"aioimaplib.exceptions.IMAP4Exception: LOGIN failed."},{"fix":"Replace `await client.start_tls()` with `await client.starttls()` in your code. The method was renamed to follow common Python conventions.","cause":"You are running aioimaplib version 2.x or later, but your code is trying to call the `start_tls()` method, which was renamed.","error":"AttributeError: 'IMAP4_SSL' object has no attribute 'start_tls'"},{"fix":"Verify that the `host` parameter (e.g., `imap.mail.com`) is correct and spelled accurately. Check your network connection and DNS settings. Ensure the hostname is not an empty string.","cause":"The hostname provided to `aioimaplib.IMAP4_SSL` or `aioimaplib.IMAP4` is either incorrect, malformed, or cannot be resolved by DNS.","error":"socket.gaierror: [Errno 8] nodename nor servname provided, or not known"}]}