ymailink Email CLI#

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

BackendReadSendAuthIMAPimapclient—password (raw/cmd/keyring)SMTP—aiosmtplibpassword (raw/cmd/keyring)Outlook (Graph API)httpx + msalhttpx + msalOAuth2 (device flow)Gmail (Google API)google-api-python-clientgoogle-api-python-clientOAuth2 (local server)Exchangeexchangelibexchangelibpassword (auto/NTLM/basic)

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:

bash

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

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

bash

# 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:

bash

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

bash

# 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#

SubcommandActionaccount listList configured accountsaccount doctorDiagnose account connectionaccount configureRun interactive wizard (prints config to stdout — copy-paste to ~/.config/ymailink/config.toml)

folder — Manage folders#

SubcommandActionfolder listList all folders (shows count + unread — IMAP omits these)folder add <name>Create folderfolder delete <name>Delete folderfolder expunge <name>Permanently remove deleted messages (IMAP only; Outlook/Gmail/Exchange are no-ops)folder purge <name>Delete ALL messages in folder (batched 500 at a time)

mail — Manage messages#

SubcommandActionmail list [-f FOLDER] [-p PAGE] [-s SIZE] [-q QUERY]List messages (default INBOX, page 1, size 20). Search syntax depends on backend.mail thread <id> [-f FOLDER]View a single message by ID (fetches one message, not a full thread)mail read <id> [-f FOLDER]Read message body (marks as SEEN)mail write [--headers K:V ...]Interactive compose via $EDITOR (or vi if unset)mail send [raw]Send raw message from file or stdinmail reply <id> [-f FOLDER] [--all]Reply to message (reply-all with --all)mail forward <id> [-f FOLDER]Forward messagemail copy <ids...> -t TARGET [-f FOLDER]Copy messages to target foldermail move <ids...> -t TARGET [-f FOLDER]Move messages to target foldermail delete <ids...> [-f FOLDER]Delete messages (IMAP: hard delete via EXPUNGE; Gmail: moves to trash)

flag — Manage message flags#

SubcommandActionflag add <ids...> -g FLAGS... [-f FOLDER]Add flagsflag set <ids...> -g FLAGS... [-f FOLDER]Replace all flagsflag remove <ids...> -g FLAGS... [-f FOLDER]Remove flags

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

attachment — Download attachments#

SubcommandActionattachment download <id> [-f FOLDER] [-d DIR]Download attachments. Directory: --dir → account config → global config → ~/Downloads

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#

SubcommandActiontemplate writeGenerate blank compose template → stdouttemplate reply <id> [-f FOLDER] [--all]Generate reply template → stdouttemplate forward <id> [-f FOLDER]Generate forward template → stdouttemplate save [raw]Save template as draft (reads from file or stdin)template send [raw]Send template from file or stdin

ai — AI-powered email operations#

SubcommandActionai short-summary <id> [-f FOLDER]One-line email summaryai summary <id> [-f FOLDER]Detailed email summaryai rapid-reply <id> [-f FOLDER]Quick reply suggestions (3)

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#

FlagDescription-c, --configConfig file path (repeatable for deep merge)-o, --outputOutput format: plain (default) or json``-a, --accountAccount name (defaults to configured default account)-q, --quietSuppress non-error log output (does not suppress command output)--debugEnable debug logging-V, --versionShow version ( ymailink 0.1.0)

Configuration Setup#

Interactive wizard#

bash

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#

bash

# 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#

bash

# 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#

bash

# 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#

bash

# Reply (opens editor)
ymailink mail reply 42

# Reply to all
ymailink mail reply 42 --all

# Forward
ymailink mail forward 42

Organize messages#

bash

# 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#

bash

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

AI-powered email operations#

bash

# 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#

bash

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

Multiple Accounts#

bash

# 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:

text

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

Message body here.

Default Behavior#

Running ymailink with no arguments is equivalent to:

bash

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#

bash

# 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#

bash

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