imap-tools

library1.13.0pypypi✓ verified 85d ago

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.

communication

pip install imap-tools

github ↗package ↗

INSTALL

IMPORT

SIG · IMAP-TOOLS

imap-tools

communicationpythonv1.13.0

Install

1.6s avg

Import

108ms

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 v1.13.0 · 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.112s · 18MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.104s · 19MB

16MB installed

● package 16MB

Code

Verified usage

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

MailBox

✓ from imap_tools import MailBox

MailBoxStartTls

✓ from imap_tools import MailBoxStartTls

✗ from imap_tools import MailBoxTls

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.

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}")

Debug

Known issues

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

affects: >=1.12.0

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

affects: >=1.11.0

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

affects: >=1.9.0

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

affects: >=1.10.0

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

affects: >=1.7.3

Errors

Common errors & fixes

imap_tools.errors.MailboxLoginError: Response status "OK" expected, but "NO" received. Data: [b'[AUTHENTICATIONFAILED] Invalid credentials (Failure)']

This error indicates that the IMAP server rejected the login attempt due to incorrect username, password, or requiring an app-specific password (especially for services with 2-Factor Authentication enabled).

fix

Ensure the username and password are correct. If 2FA is enabled, generate and use an app-specific password. Also, verify that IMAP access is enabled in your email provider's settings and that the server address and port are correct.

IMAP Server Not Responding / Connection Refused / A secure connection to the server cannot be established

These errors typically occur when the client cannot establish a stable and secure connection to the IMAP server due to incorrect server settings (host, port, SSL/TLS), firewall blocking, network issues, or an outdated/untrusted SSL certificate.

fix

Double-check the IMAP server address and port (e.g., 993 for SSL/TLS, 143 for STARTTLS). Ensure the correct connection class is used (`MailBox` for IMAPS/SSL, `MailBoxStartTls` for STARTTLS). Temporarily disable firewalls or antivirus to rule out interference. Verify that your email provider supports the chosen encryption method and that their SSL certificate is valid.

UnicodeEncodeError: 'ascii' codec can't encode character in position X: ordinal not in range(128)

This error often happens when search criteria or folder names contain non-ASCII characters, and the default 'US-ASCII' charset is used, which cannot encode these characters.

fix

Specify the `charset='utf8'` argument in `MailBox.fetch()` or `MailBox.uids()` methods when your search criteria include non-ASCII characters. If dealing with internationalized domain names (IDNs) in email addresses, manually encode the domain portion using Punycode.

`ValueError` if port 993 is specified with `MailBoxStartTls` (v1.11.0 and later)

Starting from version 1.11.0, `MailBoxStartTls` explicitly raises a `ValueError` if port 993 (IMAPS) is provided because it is intended for standard IMAP with STARTTLS (port 143), while `MailBox` is used for IMAPS (SSL/TLS from the start) on port 993.

fix

Use `MailBox` for connections on port 993 (IMAPS/SSL/TLS from start) and `MailBoxStartTls` for connections on port 143 (standard IMAP which then upgrades to TLS).

Upgrade

Version history

1.13.0latest on PyPI · released May 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ikvk/imap_tools ↗

packagehttps://pypi.org/project/imap-tools/ ↗