ymailink Email CLI

ymailink is a Python CLI email client (v0.1.0) for managing emails from the terminal. It supports four backends:

Installation

Before using any ymailink commands, always verify ymailink is installed first. Run which ymailink or ymailink --version. If not installed, guide the user to run:

pip install git+https://github.com/lizhisec/ymailink.git

To install with optional dependencies (for specific backends or AI features):

# Install with all optional dependencies
pip install "git+https://github.com/lizhisec/ymailink.git#egg=ymailink[all]"

# Or install specific extras
pip install "git+https://github.com/lizhisec/ymailink.git#egg=ymailink[outlook,gmail,keyring,exchange,ai]"

If GitHub is inaccessible, use Gitee mirror as the git source:

pip install git+https://gitee.com/w3hsec/ymailink.git

# With optional dependencies
pip install "git+https://gitee.com/w3hsec/ymailink.git#egg=ymailink[all]"

Prerequisites

1. Python 3.11+ installed.
2. ymailink installed (see Installation section above).
3. A configuration file at ~/.config/ymailink/config.toml (or custom path via -c).
4. IMAP/SMTP credentials, OAuth2 app registration, or Exchange server details.
5. For AI features (ymailink ai ...): an API key configured under [ai] in config (see references/configuration.md).

Quick Reference — All Commands

Seven command groups, 27 subcommands:

account — Manage accounts

folder — Manage folders

mail — Manage messages

flag — Manage message flags

Valid flags: seen, answered, flagged, deleted, draft (case-insensitive)

attachment — Download attachments

Note: Only IMAP backends provide attachment binary data. Outlook/Gmail/Exchange backends report metadata (name, size) but cannot download the actual file bytes yet.

template — Programmatic message composition

ai — AI-powered email operations

Note: AI features require [ai] section in config (see references/configuration.md) and the ai extra: pip install ymailink[ai]. All three commands fetch the target email, send it to the AI API (https://ai.ymailink.com), and print the result.

Global Flags

Configuration Setup

Interactive wizard

ymailink account configure

This prompts for account details and prints the resulting TOML config to stdout. It does not write the file — you need to copy-paste the output to ~/.config/ymailink/config.toml.

See references/configuration.md for manual config setup with all backend types (IMAP/SMTP, Outlook, Gmail, Gmail-via-IMAP, Exchange), password auth methods (raw/cmd/keyring), OAuth2 token management, folder aliases, signatures, download directories, and proxy support.

Common Workflows

List and read emails

# List INBOX
ymailink mail list

# Search
ymailink mail list --query "from:john@example.com subject:meeting"

# Paginate
ymailink mail list --page 2 --page-size 10

# Switch folder
ymailink mail list --folder "Sent"

# Read a message
ymailink mail read 42

# JSON output for scripting
ymailink --output json mail list

Compose and send

# Interactive compose (opens $EDITOR)
ymailink mail write
ymailink mail write --headers "To:user@example.com" --headers "Subject:Hello"

# Send raw message from file
ymailink mail send message.txt

# Pipe to send
cat message.txt | ymailink mail send

Programmatic template workflow

# Generate a blank template, edit, send
ymailink template write > msg.txt
vim msg.txt
ymailink template send msg.txt

# Or pipe directly
ymailink template write | cat - msg_body.txt | ymailink template send

Reply and forward

# Reply (opens editor)
ymailink mail reply 42

# Reply to all
ymailink mail reply 42 --all

# Forward
ymailink mail forward 42

Organize messages

# Move message(s) to folder
ymailink mail move 42 --target "Archive"
ymailink mail move 42 43 44 --target "Archive" --folder INBOX

# Copy message(s)
ymailink mail copy 55 56 --target "Important"

# Delete message(s)
ymailink mail delete 42
ymailink mail delete 42 43 44 --folder INBOX

# Flag messages
ymailink flag add 42 --flags seen --flags flagged
ymailink flag set 42 --flags answered
ymailink flag remove 42 --flags flagged

Manage folders

ymailink folder list
ymailink folder add "Archive"
ymailink folder delete "Old Folder"
ymailink folder expunge "Trash"
ymailink folder purge "Junk"

AI-powered email operations

# One-line summary of an email
ymailink ai short-summary 42

# Detailed summary
ymailink ai summary 42

# Quick reply suggestions (3 options)
ymailink ai rapid-reply 42

# Specify a different folder
ymailink ai short-summary 42 --folder INBOX
ymailink ai summary 42 --folder "Sent"
ymailink ai rapid-reply 42 --folder "Archive"

Download attachments

ymailink attachment download 42
ymailink attachment download 42 --folder INBOX --dir ~/Downloads

Multiple Accounts

# List configured accounts
ymailink account list

# Switch accounts
ymailink --account work mail list
ymailink --account personal mail list

Message Composition

ymailink uses standard RFC 822 format. See references/message-composition.md for the full reference covering: headers, address formats, plain text bodies, reply/forward quoting, interactive compose, file/stdin send, and template workflows.

A minimal message looks like:

From: You <you@example.com>
To: recipient@example.com
Subject: Hello

Message body here.

Default Behavior

Running ymailink with no arguments is equivalent to:

ymailink mail list --folder INBOX --page 1 --page-size 20

Tips & Nuances

• Message IDs are folder-scoped (IMAP UIDs). Re-list after changing folders.
• Plural aliases work for all command groups: accounts, folders, flags, attachments, templates. (Not mail.)
• mail write uses $EDITOR or $VISUAL, falling back to vi. The temp file uses the .eml suffix. If no changes are detected, the message is not sent.
• mail reply / mail forward also detect unchanged content and abort sending.
• mail read --html flag exists in the CLI but currently has no effect — the text body is always shown.
• Gmail delete moves to trash (not a hard delete). Use the Gmail web interface or API to permanently delete.
• IMAP delete is hard: sets \Deleted + EXPUNGE, permanently removing messages.
• Folder counts (count, unread) are only populated by Outlook, Gmail, and Exchange backends — IMAP does not fetch them.
• Store passwords securely using pass, system keyring (pip install ymailink[keyring]), or a command that outputs the password. Plaintext passwords in config are for testing only.
• AI features require pip install ymailink[ai] and an [ai] section in config with an api-key. The default AI endpoint is https://ai.ymailink.com.
• OAuth2 tokens are cached in ~/.config/ymailink/tokens/{provider}_{account}.json (chmod 0600). Delete the file to force re-authorization.
• Proxy support for Outlook and Gmail backends: set HTTPS_PROXY or https_proxy environment variable.
• Account not found errors produce unhandled exceptions. Verify account names with ymailink account list.
• Config file not found returns an empty config (no error). Commands will fail with "No accounts configured" rather than a file-not-found error.
• --quiet only suppresses log() output (dimmed stderr). It does not suppress command output (table/JSON on stdout) or error messages.

References

• references/configuration.md — Full config setup: IMAP/SMTP/Outlook/Gmail/Exchange auth, AI config, password methods, OAuth2, folder aliases, signatures, proxy
• references/message-composition.md — RFC 822 format, headers, address formats, reply/forward quoting, compose workflows

Debugging

# Enable debug logging
ymailink --debug mail list

# Diagnose connection issues
ymailink account doctor

# Suppress non-error output
ymailink --quiet mail list

# Check version
ymailink --version

Help

ymailink --help
ymailink mail list --help
ymailink flag add --help