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

``bash
npm install -g aimail
`

Or run directly:

`bash
npx aimail --help
`

Quick Start

$3

`bash
aimail config init
`

This will prompt for:
- Email address
- IMAP/SMTP server settings
- Password (stored securely in system keychain)

$3

`bash


Sync all configured folders

aimail sync

Sync specific folder

aimail sync INBOX

Full sync (ignore delta state)

aimail sync --full
`

$3

`bash


List emails in INBOX

aimail list

List with filters

aimail list --unread --limit 10

List from specific folder

aimail list Sent
`

$3

`bash
aimail read INBOX/12345
`

$3

`bash


Full-text search

aimail search "project update"

Search with filters

aimail search "meeting" --from alice@example.com --since 2024-01-01
`

$3

`bash
aimail send \
--to recipient@example.com \
--subject "Hello" \
--body "Email content here"
`

Or pipe content:

`bash
echo "Email content" | aimail send --to recipient@example.com --subject "Hello"
`

Commands

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

Global Options

| Option | Description |
|--------|-------------|
| -c, --config | Path to config file |
| -f, --format | 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:

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

Errors:

`json
{
"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:

`markdown
---
id: "INBOX/12345"
messageId: ""
uid: 12345
from:
name: "Alice Smith"
address: "alice@example.com"
to:
- address: "bob@example.com"
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:

`yaml
account:
email: user@example.com
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

$3

`
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.

$3

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

$3

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

License

MIT