aimail

CLI email client designed for AI agents - search, send, reply, forward, and archive emails from the command line with JSON output.

Features

• IMAP/SMTP Support: Connect to any email provider (Gmail, Outlook, etc.)
• Local Storage: Emails stored in Maildir-style format with YAML frontmatter
• Full-Text Search: Fast local search with MiniSearch
• JSON Output: Machine-readable output for AI agent integration
• Offline Drafts: Save and edit drafts locally before sending
• Secure Credentials: Passwords stored in system keychain

Requirements

• Node.js >= 20.0.0
• npm or yarn

Installation

npm install -g aimail

Or run directly:

npx aimail --help

Quick Start

1. Configure your account

aimail config init

This will prompt for:

• Email address
• IMAP/SMTP server settings
• Password (stored securely in system keychain)

2. Sync your emails

# Sync all configured folders
aimail sync

# Sync specific folder
aimail sync INBOX

# Full sync (ignore delta state)
aimail sync --full

3. List emails

# List emails in INBOX
aimail list

# List with filters
aimail list --unread --limit 10

# List from specific folder
aimail list Sent

4. Read an email

aimail read INBOX/12345

5. Search emails

# Full-text search
aimail search "project update"

# Search with filters
aimail search "meeting" --from [email protected] --since 2024-01-01

6. Send an email

aimail send \
  --to [email protected] \
  --subject "Hello" \
  --body "Email content here"

Or pipe content:

echo "Email content" | aimail send --to [email protected] --subject "Hello"

Commands

| Command | Description | |---------|-------------| | aimail config init | Interactive setup wizard | | aimail config show | Show current configuration | | aimail config set <key> <value> | Set configuration value | | aimail config get <key> | Get configuration value | | aimail sync [folder] | Sync emails from server | | aimail list [folder] | List emails in folder | | aimail read <id> | Read specific email | | aimail search <query> | Search emails | | aimail send | Send an email | | aimail draft list | List drafts | | aimail draft save | Create/update draft | | aimail draft show <id> | Show draft | | aimail draft send <id> | Send draft | | aimail draft delete <id> | Delete draft | | aimail flag <id> <action> | Modify email flags (read/unread/flag/unflag/archive/delete) | | aimail move <id> <folder> | Move email to folder | | aimail folders | List folders | | aimail folders create <path> | Create folder | | aimail folders delete <path> | Delete folder | | aimail status | Show sync status |

Global Options

| Option | Description | |--------|-------------| | -c, --config <path> | Path to config file | | -f, --format <type> | Output format: json (default), text | | --pretty | Pretty-print JSON output | | -q, --quiet | Suppress non-essential output | | -v, --verbose | Enable verbose logging |

JSON Output Format

All commands output JSON by default:

{
  "success": true,
  "data": {
    // Command-specific data
  },
  "meta": {
    "timestamp": "2024-01-15T12:00:00Z",
    "duration": 1234,
    "version": "0.1.0"
  }
}

Errors:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error description",
    "details": {}
  },
  "meta": {
    "timestamp": "2024-01-15T12:00:00Z",
    "version": "0.1.0"
  }
}

Email Storage Format

Emails are stored as markdown files with YAML frontmatter:

---
id: "INBOX/12345"
messageId: "<[email protected]>"
uid: 12345
from:
  name: "Alice Smith"
  address: "[email protected]"
to:
  - address: "[email protected]"
subject: "Hello World"
date: "2024-01-15T10:30:00Z"
flags:
  seen: true
  flagged: false
attachments:
  - filename: "document.pdf"
    contentType: "application/pdf"
    size: 102400
    path: "attachments/INBOX/12345/document.pdf"
---

Email body content here...

Directory Structure

~/.aimail/
├── config.yaml           # Configuration
├── mail/                 # Email storage
│   ├── INBOX/
│   │   ├── .folder.yaml  # Folder metadata
│   │   ├── cur/          # Read messages
│   │   └── new/          # Unread messages
│   └── Sent/
├── drafts/               # Local drafts
├── attachments/          # Downloaded attachments
└── index/                # Search index

Configuration

Configuration is stored in ~/.aimail/config.yaml:

account:
  email: [email protected]
  name: User Name

imap:
  host: imap.example.com
  port: 993
  secure: true

smtp:
  host: smtp.example.com
  port: 587
  secure: false

folders:
  INBOX:
    syncMode: full      # full, headers, or none
  Sent:
    syncMode: full
  "[Gmail]/All Mail":
    syncMode: headers

sync:
  defaultMode: headers
  batchSize: 50

output:
  format: json
  pretty: false

Common Provider Settings

Gmail

IMAP: imap.gmail.com:993 (TLS)
SMTP: smtp.gmail.com:587 (STARTTLS)

Note: For Gmail, you need to enable "Less secure app access" or use an App Password.

Outlook/Office 365

IMAP: outlook.office365.com:993 (TLS)
SMTP: smtp.office365.com:587 (STARTTLS)

Yahoo Mail

IMAP: imap.mail.yahoo.com:993 (TLS)
SMTP: smtp.mail.yahoo.com:587 (STARTTLS)

License

MIT