# ikvk/imap_tools architecture

> Architecture diagram of the GitHub repository ikvk/imap_tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ikvk/imap_tools
- Repository: https://github.com/ikvk/imap_tools

## Overview

##### Project type and purpose
- This is an open-source Python library (“imap_tools”) that provides a high-level API over the standard imaplib module for interacting with IMAP mail servers.
- Its purpose is to simplify mailbox operations (search, fetch, folders, flags, IDLE) and message parsing (headers, text/html bodies, attachments) without external dependencies.

##### File structure
- Top-level:
- setup.py, MANIFEST.in, LICENSE – packaging/metadata
- README.rst – project overview
- docs/ – design notes, RFC references, release notes
- examples/ – sample usage scripts
- tests/ – unit tests and test fixtures (raw .eml files and expected parsed data)
- Core code in imap_tools/:
- mailbox.py, idle.py, folder.py – high-level clients and sub-managers
- query.py – IMAP search criteria builder (AND, OR, NOT, UidRange)
- message.py – MailMessage, MailAttachment, parsing logic
- imap_utf7.py – mailbox name encoding
- utils.py – helpers (encoding, parsing)
- consts.py – constants (flags, sort criteria)
- errors.py – custom exception types

##### README for additional insights
- Main API: MailBox, MailBoxTls, MailBoxUnencrypted classes with context-manager and methods: fetch, uids, numbers, copy/move/delete/flag/append, folder operations, idle operations.
- Describes method parameters, query builder usage, data model (MailMessage attributes).
- Highlights no external dependencies, Python 3.8+, tested against IMAP4.1 & RFC-2822.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User layer
    UA["User Application"]:::external

    %% API Layer
    subgraph "Public API Layer"
        API["MailBox / MailBoxTls / MailBoxUnencrypted"]:::api
    end

    %% Sub-managers
    subgraph "Sub-managers"
        FM["Folder Manager"]:::manager
        IM["Idle Manager"]:::manager
    end

    %% Query Builder
    subgraph "Query Builder"
        QB["Query Builder"]:::builder
    end

    %% Protocol & Encoding Adapters
    subgraph "Protocol & Encoding Adapters"
        PA["Protocol Adapter\n(imaplib wrapper)"]:::adapter
        UTF7["IMAP UTF-7 Encoding Adapter"]:::adapter
    end

    %% Parsing
    subgraph "Message Parsing"
        MP["Message Parser\n(MailMessage & Attachments)"]:::parser
        PH["Parsing Helpers\n(utils)"]:::parser
    end

    %% Utilities & Errors
    subgraph "Utilities"
        EH["Error Handling"]:::util
        CONST["Constants"]:::util
        TS["Type Stubs Indicator"]:::util
    end

    %% External Libraries and Systems
    STDlibIMAP["imaplib\n(stdlib)"]:::external
    STDlibEmail["email.message\n(stdlib)"]:::external
    IMAPSrv["IMAP Mail Server"]:::external

    %% File structure references
    UA -->|uses| API
    API -->|calls| FM
    API -->|calls| IM
    API -->|uses| QB
    API -->|wraps| PA
    API -->|raises| EH

    FM -->|uses| PA
    IM -->|uses| PA

    QB -->|builds SEARCH cmd| PA
    PA -->|IMAP SEARCH / FETCH / IDLE| IMAPSrv
    IMAPSrv -->|responses| PA

    PA -->|raw bytes| MP
    MP -->|parses| PH
    MP -->|uses| STDlibEmail

    API -->|encodes folder names| UTF7
    API -->|refers| CONST
    API -->|includes| TS

    PA -->|uses| STDlibIMAP

    %% Click Events
    click API "https://github.com/ikvk/imap_tools/blob/master/imap_tools/mailbox.py"
    click FM "https://github.com/ikvk/imap_tools/blob/master/imap_tools/folder.py"
    click IM "https://github.com/ikvk/imap_tools/blob/master/imap_tools/idle.py"
    click QB "https://github.com/ikvk/imap_tools/blob/master/imap_tools/query.py"
    click MP "https://github.com/ikvk/imap_tools/blob/master/imap_tools/message.py"
    click PH "https://github.com/ikvk/imap_tools/blob/master/imap_tools/utils.py"
    click UTF7 "https://github.com/ikvk/imap_tools/blob/master/imap_tools/imap_utf7.py"
    click EH "https://github.com/ikvk/imap_tools/blob/master/imap_tools/errors.py"
    click CONST "https://github.com/ikvk/imap_tools/blob/master/imap_tools/consts.py"
    click TS "https://github.com/ikvk/imap_tools/blob/master/imap_tools/py.typed"
    click UA "https://github.com/ikvk/imap_tools/tree/master/examples/"
    click STDlibIMAP "https://github.com/ikvk/imap_tools/tree/master/stdlib/imaplib"
    click STDlibEmail "https://github.com/ikvk/imap_tools/tree/master/stdlib/email/message"
    click IMAPSrv "https://github.com/ikvk/imap_tools/tree/master/external/imap_server"
    click Docs "https://github.com/ikvk/imap_tools/tree/master/docs/"
    click Packaging "https://github.com/ikvk/imap_tools/blob/master/setup.py"
    click TC1 "https://github.com/ikvk/imap_tools/blob/master/tests/test_connection.py"
    click TC2 "https://github.com/ikvk/imap_tools/blob/master/tests/test_folders.py"
    click TC3 "https://github.com/ikvk/imap_tools/blob/master/tests/test_idle.py"
    click TC4 "https://github.com/ikvk/imap_tools/blob/master/tests/test_imap_utf7.py"
    click TC5 "https://github.com/ikvk/imap_tools/blob/master/tests/test_mailbox.py"
    click TC6 "https://github.com/ikvk/imap_tools/blob/master/tests/test_query.py"
    click TC7 "https://github.com/ikvk/imap_tools/blob/master/tests/test_message.py"
    click TC8 "https://github.com/ikvk/imap_tools/blob/master/tests/test_utils.py"
    click TM "https://github.com/ikvk/imap_tools/tree/master/tests/messages/"
    click TMD "https://github.com/ikvk/imap_tools/tree/master/tests/messages_data/"

    %% Layout tweaks
    UA --> API
    STDlibIMAP --- PA
    STDlibEmail --- MP

    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef manager fill:#90EE90,stroke:#333,stroke-width:1px
    classDef builder fill:#FFA500,stroke:#333,stroke-width:1px
    classDef parser fill:#FFC0CB,stroke:#333,stroke-width:1px
    classDef adapter fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:none,stroke:#999,stroke-dasharray: 5 5,stroke-width:1px,color:#999
    class UA,STDlibIMAP,STDlibEmail,IMAPSrv external
```
