README

IMAP email management toolkit for Coqui — read, search, send, reply, and organize emails directly from the terminal.

Features

• Read & browse — list folders, paginate messages, read full emails
• Search — find emails by subject, sender, recipient, date range
• Send & reply — compose new emails and replies with proper threading headers
• Organize — move messages between folders, flag/unflag, delete
• Folder management — create, rename, and delete IMAP folders
• Inbox summaries — background-task-friendly digest of recent activity
• Credential management — integrates with Coqui's credential guard system
• Safety gating — destructive operations require user confirmation

Installation

composer require coquibot/coqui-toolkit-imap

Coqui auto-discovers the toolkit on next boot — no configuration code needed.

Credential Setup

The toolkit requires three credentials to connect. Coqui will prompt you automatically when you first use an IMAP tool.

Required Credentials

Optional Credentials

Provider Setup

Gmail

1. Enable 2-Step Verification at myaccount.google.com/security
2. Generate an App Password at myaccount.google.com/apppasswords
3. Set credentials:

IMAP_HOST=imap.gmail.com
IMAP_USERNAME=you@gmail.com
IMAP_PASSWORD=<app-password>

Gmail uses the same credentials for SMTP — no separate SMTP config needed.

Microsoft 365 / Outlook

IMAP_HOST=outlook.office365.com
IMAP_USERNAME=you@outlook.com
IMAP_PASSWORD=<your-password>
SMTP_HOST=smtp.office365.com

Note: Microsoft may require OAuth2 for some accounts. App passwords work for accounts with basic auth enabled.

Generic IMAP Server

IMAP_HOST=mail.example.com
IMAP_USERNAME=user@example.com
IMAP_PASSWORD=secret
SMTP_HOST=smtp.example.com

Tools Reference

Gated tools require user confirmation before execution (unless --auto-approve is enabled).

Example Workflows

Check unread emails

"Check my inbox for unread emails"

The agent will:

1. List folders to find the inbox
2. Fetch unread messages
3. Present a summary of new emails

Search and organize

"Find all emails from newsletters@example.com and move them to a Newsletters folder"

The agent will:

1. Search for matching emails
2. Create the Newsletters folder if needed
3. Move matched messages (with your confirmation)

Send a reply

"Reply to the last email from Alice saying I'll be there at 3pm"

The agent will:

1. Search for Alice's email
2. Read it for context
3. Compose and send a reply with proper threading headers

Daily digest

"Give me a summary of emails from the last 3 days"

The agent will use imap_summary with a date filter to generate a digest showing unread counts, top senders, and recent messages.

Dependencies

Development

Run tests

composer install
./vendor/bin/pest

Project structure

src/
├── ImapToolkit.php              # Entry point (ToolkitInterface)
├── Runtime/
│   ├── ImapClientFactory.php    # Lazy IMAP connection management
│   ├── MessageFormatter.php     # LLM-friendly email formatting
│   └── SmtpTransportFactory.php # SMTP transport with IMAP fallback
└── Tool/
    ├── ImapDeleteTool.php
    ├── ImapFlagTool.php
    ├── ImapFolderManageTool.php
    ├── ImapListFoldersTool.php
    ├── ImapListMessagesTool.php
    ├── ImapMoveTool.php
    ├── ImapReadMessageTool.php
    ├── ImapReplyTool.php
    ├── ImapSearchTool.php
    ├── ImapSendTool.php
    └── ImapSummaryTool.php
tests/
└── Unit/
    └── ImapToolkitTest.php

License

MIT