imap-reader 1.0.2

Simple Python library for reading verification emails via IMAP — OTP extraction, link parsing, auto IMAP detection.

imap_reader

Simple, clean Python library for reading verified emails via IMAP — with OTP extraction, verification link parsing, and auto IMAP detection.

Zero external dependencies — uses Python standard library only (imaplib, email, re, threading).

---

##Installation

pip install imap_reader

or

pip install git+https://github.com/nabilunnuha/imap_reader.git

---

Quick Start

from imap_reader import ImapClient

with ImapClient(
        email_address="[e-mail]",
        password_email="your_app_password",
    ) as client:

    for msg in client.get_messages("UNSEEN"):
        print(msg.subject)
        print(msg.otp_codes) # ['123456']
        print(msg.verification_links) # ['https://example.com/verify?token=...']

---

Features

• IMAP auto-detect — automatically detects the IMAP host of an email domain
• OTP extraction — extracts a 5–6-digit code from the email body
• Verification link extraction — finds and prioritizes verification/confirmation links
• HTML email parser — converts HTML emails to plain text for extraction
• Login timeout — raises an error if the connection timeout is exceeded (30–60 seconds)
• Context manager — use the with statement to automatically close the connection
• Delete messages — delete emails based on criteria (ALL, SEEN, UNSEEN)
• Type hints — fully typed, IDE-friendly, and autocomplete-friendly

---

Usage

Basic — Read unseen emails

from imap_reader import ImapClient

with ImapClient("[e-mail]", "app_password") as client:
    for msg in client.get_messages("UNSEEN"):
        print(f"From : {msg.sender}")
        print(f"Subject : {msg.subject}")
        print(f"OTP : {msg.otp_codes}")
        print(f"Links : {msg.verification_links}")

Retrieve only 1 recent email

with ImapClient("[e-mail]", "app_password") as client:
    msg = client.get_latest_message("UNSEEN")
    if msg:
        print(msg.otp_codes)

Custom timeout (30–60 seconds recommended)

with ImapClient(
        email_address="[e-mail]",
        password_email="app_password",
        timeout=60, # seconds
    ) as client:
    msg = client.get_latest_message()

Read from specified folder

with ImapClient("[e-mail]", "app_password") as client:
    for msg in client.get_messages("ALL", folder="SPAM"):
        print(msg.subject)

Delete email

with ImapClient("[e-mail]", "app_password") as client:
    # Delete all read emails
    count = client.delete_messages("SEEN")
    print(f"{count} deleted emails")

    # Delete all emails in INBOX
    count = client.delete_messages("ALL", folder="INBOX")

    # Delete unread emails in SPAM
    count = client.delete_messages("UNSEEN", folder="SPAM")

Add custom IMAP provider

from imap_reader import ImapClient
from imap_reader.models import DEFAULT_IMAP_LIST, ImapItemModel

DEFAULT_IMAP_LIST.append(
    ImapItemModel(domain="mycompany.com", imap_host="imap.mycompany.com")
)

with ImapClient("[e-mail]", "password") as client:
    for msg in client.get_messages():
        print(msg)

Error handling

from imap_reader import ImapClient
from imap_reader.exceptions import (
    AuthenticationError,
    ConnectionTimeoutError,
    ImapNotFoundError,
)

try:
    with ImapClient("[e-mail]", "wrong_password", use_default_imap=False, timeout=10) as client:
        msg = client.get_latest_message()
except AuthenticationError:
    print("Email or password is incorrect.")
except ConnectionTimeoutError:
    print("Connection to IMAP server timed out.")
except ImapNotFoundError:
    print("Email domain not recognized, add manually to imap_list.")

---

API Reference

ImapClient(email_address, password_email, imap_list=None, use_default_imap=True, timeout=30)

Parameters	Type	Default	Description
email_address	str	—	Complete email address
password_email	str	—	IMAP Password or App Password
imap_list	list	DEFAULT_IMAP_LIST	List of IMAP providers
use_default_imap	bool	True	IMAP Password or App Password
timeout	int	30	Login timeout in seconds

Methods

Method	Returns	Description
get_messages(criteria, folder, limit, mark_seen)	Generator[EmailMessage]	Fetch and yield messages
get_latest_message(criteria, folder)	EmailMessage | None	Fetch 1 most recent message