imap-smtp-email

IMAP SMTP Email is a community skill for email management via IMAP and SMTP protocols, covering message retrieval, inbox searching, read status updates, email composition, and attachment handling for terminal-based email workflows.

What Is This?

Overview

IMAP SMTP Email provides command-line tools for managing email accounts through standard IMAP and SMTP protocols without graphical interfaces. It covers message retrieval that fetches emails from inbox and other folders with header and body content, inbox searching that filters messages by sender, subject, date ranges, and read status, read status updates that mark messages as read or unread for organization, email composition that creates and sends new messages with recipients and subject lines, and attachment handling that adds files to outgoing emails and saves attachments from incoming messages. The skill enables email management from servers, automation scripts, and terminal environments where graphical clients are unavailable, supporting multiple email providers including Gmail, Outlook, and self-hosted mail servers through standard protocol implementations.

Who Should Use This

This skill serves system administrators managing email from remote servers, developers building email automation workflows, and AI agents requiring programmatic email access capabilities. It is also well suited for DevOps engineers who need to integrate email notifications directly into deployment pipelines or monitoring systems.

Why Use It?

Problems It Solves

Server environments and headless systems lack graphical displays for running traditional email clients with visual interfaces. Building email automation with raw IMAP and SMTP libraries requires handling protocol complexity, connection management, and authentication sequences. Managing multiple email accounts across different providers demands switching between various web interfaces and authentication contexts. Extracting specific emails for processing in automated workflows needs programmatic filtering and retrieval capabilities beyond what web interfaces provide.

Core Highlights

Message fetcher retrieves emails with full content and metadata. Search engine filters inbox by sender, subject, and date criteria. Status updater marks messages as read or unread programmatically. Email sender composes and delivers messages with attachments.

How to Use It?

Basic Usage

from imap_smtp import Email

email = Email(
    imap_host="imap.gmail.com",
    smtp_host="smtp.gmail.com",
    username="user@gmail.com",
    password="app_password")

unread = email.search(
    criteria="UNSEEN")

msg = email.fetch(unread[0])

email.send(
    to="friend@example.com",
    subject="Hello",
    body="Message text")

Real-World Examples

emails = email.search(
    criteria="FROM client@co.com")

for msg_id in emails:
    message = email.fetch(msg_id)
    if has_invoice(message):
        save_attachments(
            message, "./invoices")
        email.mark_read(msg_id)

email.send(
    to="team@company.com",
    subject="Weekly Report",
    body="See attached data",
    attachments=[
        "report.pdf",
        "data.xlsx"])

Advanced Tips

Use IMAP search criteria with date ranges and sender filters to retrieve specific message subsets efficiently without downloading entire mailboxes, which significantly improves performance when working with large email archives. For example, combining a SINCE date filter with a FROM filter can reduce retrieved message counts by orders of magnitude compared to fetching all messages. Implement connection pooling when processing many emails to reduce authentication overhead and improve throughput significantly across batch operations. Handle multipart MIME messages carefully to extract plain text and HTML content correctly from complex email structures with proper encoding.

When to Use It?

Use Cases

Process incoming support emails automatically by extracting ticket information and creating tasks in project management systems. Monitor specific email addresses for alert messages and trigger notification workflows when important messages arrive. Archive emails matching specific criteria to local storage for compliance and backup purposes.

Related Topics

IMAP protocol, SMTP protocol, email automation, message parsing, server-side email, and headless email management.

Important Notes

Requirements

IMAP and SMTP server addresses and credentials for your email provider with appropriate access permissions. Network connectivity to email servers on standard IMAP and SMTP ports for protocol communication. App-specific passwords or OAuth tokens when using email providers that require enhanced security.

Usage Recommendations

Do: use app-specific passwords instead of account passwords when your email provider supports them for better security. Close IMAP connections properly after operations to avoid leaving stale sessions on the server. Test email parsing logic thoroughly since message formats vary widely across different senders and clients.

Don't: store email credentials in plain text configuration files without encryption or secure credential management. Leave IMAP connections open indefinitely since servers may terminate idle sessions. Process attachments without validating file types and scanning for malware in automated environments where senders cannot be fully trusted.

Limitations

Very large mailboxes with thousands of messages may take significant time to search and retrieve data. Some email providers impose rate limits on IMAP connections that affect bulk operations. Complex HTML emails with embedded images may not render correctly when extracted programmatically.