aioimaplib

library2.0.1pypypi✓ verified 85d ago

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.

http-networking communication

pip install aioimaplib

github ↗package ↗

INSTALL

IMPORT

SIG · AIOIMAPLIB

aioimaplib

http-networkingpythonv2.0.1

Install

1.5s avg

Import

211ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.225s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.197s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IMAP4_SSL

✓ from aioimaplib import IMAP4_SSL

IMAP4

✓ from aioimaplib import IMAP4

Use IMAP4 for plain TCP connections, IMAP4_SSL for implicit TLS (port 993), or IMAP4 with .starttls() for explicit TLS (STARTTLS on port 143).

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.

import aioimaplib import asyncio import os async def main(): IMAP_HOST = os.environ.get('IMAP_HOST', 'imap.mail.com') IMAP_USER = os.environ.get('IMAP_USER', 'your_email@mail.com') IMAP_PASS = os.environ.get('IMAP_PASS', 'your_password') if not all([IMAP_HOST, IMAP_USER, IMAP_PASS]): print("Please set IMAP_HOST, IMAP_USER, and IMAP_PASS environment variables.") return try: async with aioimaplib.IMAP4_SSL(host=IMAP_HOST) as client: await client.wait_hello_from_server() await client.login(IMAP_USER, IMAP_PASS) print(f"Logged in as {IMAP_USER}") status, mailboxes = await client.list() if status == 'OK': print("Mailboxes:") for mb in mailboxes: print(f" {mb.decode('utf-8')}") else: print(f"Failed to list mailboxes: {status}") await client.select('INBOX') status, msg_ids = await client.search('ALL') if status == 'OK' and msg_ids[0]: print(f"INBOX contains {len(msg_ids[0].split())} messages.") elif status == 'OK': print("INBOX is empty.") else: print(f"Failed to search INBOX: {status}") except aioimaplib.exceptions.IMAP4Exception as e: print(f"IMAP error: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") if __name__ == '__main__': asyncio.run(main())

Debug

Known issues

breakingVersion 2.0.0 introduced significant breaking changes to connection management. The `__aenter__` and `__aexit__` methods were removed from the client class.

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()`.

affects: >=2.0.0

breakingThe `IMAP4_SSL.start_tls()` method was renamed to `IMAP4.starttls()` in version 2.0.0.

fix

Update your code to use `await client.starttls()` when upgrading from 1.x to 2.x.

affects: >=2.0.0

breakingThe `IMAP4.idle()` method was removed in version 2.0.0. For IMAP IDLE command, more explicit control is now provided.

fix

Use `await client.idle_start()` to initiate IDLE mode and `await client.idle_done()` to terminate it.

affects: >=2.0.0

breakingThe `IMAP4.noop()` method was removed in version 2.0.0. The standard `noop` command is now available through the generic command interface.

fix

Use `await client.noop_()` instead of the removed `noop()` method.

affects: >=2.0.0

gotchaFailing 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.

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`.

affects: All

Errors

Common errors & fixes

AttributeError: __aenter__

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.

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`.

aioimaplib.exceptions.IMAP4Exception: LOGIN failed.

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).

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.

AttributeError: 'IMAP4_SSL' object has no attribute 'start_tls'

You are running aioimaplib version 2.x or later, but your code is trying to call the `start_tls()` method, which was renamed.

fix

Replace `await client.start_tls()` with `await client.starttls()` in your code. The method was renamed to follow common Python conventions.

socket.gaierror: [Errno 8] nodename nor servname provided, or not known

The hostname provided to `aioimaplib.IMAP4_SSL` or `aioimaplib.IMAP4` is either incorrect, malformed, or cannot be resolved by DNS.

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.

Upgrade

Version history

2.0.1latest on PyPI · released Jan 16, 2025

Audit

Dependencies

trustmeoptionalUsed for generating self-signed certificates for testing and potentially other TLS-related functionalities.

Agent activity

57 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bamthomas/aioimaplib ↗

packagehttps://pypi.org/project/aioimaplib/ ↗