weavmail is a command-line email client designed for AI agents. Use it to read, send, reply to, and organize emails

Setup

Install once before first use:

CODEBLOCK0

Configure an account (named default):

CODEBLOCK1

INLINECODE2 and --password set both IMAP and SMTP credentials at once. The account name defaults to default and can be omitted from all subsequent commands.

Each option can be updated independently — only the options you pass are changed, everything else is preserved. For example, to update just the password:

CODEBLOCK2

INLINECODE5 is a comma-separated list of email addresses that are authorized as senders for this account (e.g. --addresses you@example.com,alias@example.com). All addresses listed here can be used as the --from address when sending mail.

To view the current configuration of an account, run account config without any options:

CODEBLOCK3

After Configuring an Account

After any account is configured, always run the following automatically:

CODEBLOCK4

Inspect the output and identify the Sent and Trash folders (names vary by provider, e.g. Sent, Sent Messages, [Gmail]/Sent Mail, Trash, Deleted Messages, [Gmail]/Trash). Then save them to the account config:

CODEBLOCK5

All three fields are optional — if any cannot be identified with confidence, skip it. They do not affect other functionality when unset.

Sync Inbox

Fetch the latest emails from INBOX and save them as local Markdown files:

CODEBLOCK6

Options:

• - --account NAMES — comma-separated account names to sync (default: all configured accounts)
• INLINECODE16 — sync a different folder (default: INBOX)
• INLINECODE18 — number of most-recent messages to fetch (default: 10)

Each email is saved to ./mails/<account>_<mailbox>/<uid>.md with YAML front matter:

CODEBLOCK7

Always sync before reading mail. After syncing, read .md files directly — the body starts after the second ---.

List Mailboxes

List all available IMAP folders for the account:

CODEBLOCK8

Use this to discover exact folder names before syncing a non-INBOX mailbox. Folder names are case-sensitive.

Move a Mail

Move an email to another folder, then automatically sync the source mailbox:

CODEBLOCK9

The source mailbox is synced after the move — the local file will be deleted automatically.

To delete a mail, move it to the Trash folder. The exact name varies by provider (e.g. Trash, Deleted Messages, [Gmail]/Trash). Use weavmail mailbox to find the correct name first.

Trash a Mail

Move one or more emails to the account's trash mailbox, then automatically sync the source mailbox:

CODEBLOCK10

Multiple MAIL_FILE arguments can be passed for batch operations. The trash mailbox is read from each mail's account --trash-mailbox configuration. An error is raised if --trash-mailbox is not configured for the account.

The source mailbox is synced after the move — the local file will be deleted automatically.

Archive a Mail

Move one or more emails to the account's archive mailbox, then automatically sync the source mailbox:

CODEBLOCK11

Multiple MAIL_FILE arguments can be passed for batch operations. The archive mailbox is read from each mail's account --archive-mailbox configuration. An error is raised if --archive-mailbox is not configured for the account.

The source mailbox is synced after the move — the local file will be deleted automatically.

Send a Mail

Write the body to a file, then send:

CODEBLOCK12

INLINECODE33, --cc, and --bcc are all repeatable for multiple recipients. --from defaults to the first configured address.

Reply to a Mail

CODEBLOCK13

In reply mode, subject, to, and from are all inferred from the original mail's front matter. The original body is quoted and appended. In-Reply-To and References headers are set automatically. Override any of them with explicit options if needed.

Notes

• - Never guess UIDs. Always sync first, then reference files from the output.
• Mailbox names are case-sensitive. Use weavmail mailbox to list exact names.
• The mailbox field in front matter stores the original unescaped name (e.g. INBOX/Sent); the directory path uses _ as a separator.
• Front matter is authoritative for metadata — always read it from the .md file.
• All commands support --help for full option details, e.g. weavmail sync --help.

Multiple Accounts

Configure additional accounts by providing a name:

CODEBLOCK14

Then pass --account to any command to target that account:

CODEBLOCK15

INLINECODE50 without --account syncs all configured accounts automatically.

For move and send --reply, the account is read from the mail file's front matter — you may pass --account as a safeguard: if it doesn't match the account in the front matter, the command will exit with an error. For trash and archive, the account is always read from each mail file's front matter (no --account option).