Post

Post

Use the post CLI for email tasks and postd for the background daemon.

Read First

• Read SETUP.md for first-time install, keychain credentials, daemon setup, and scoped API keys.
• Read references/common-tasks.md for concrete workflows and reply recipes.

Core Rules

• Treat UIDs as mailbox-scoped, not globally unique. If a message is not in INBOX, pass --reply-mailbox when replying.
• Prefer --json when the result will be parsed or reused in a later step.
• Prefer scoped API keys for agents. Use --token for one-off commands or set POST_API_KEY only in that agent’s environment.
• Use post draft --replying-to for threaded replies. This auto-derives from, to, and subject, and sets In-Reply-To / References.
• Omit --body to create a Mail-style reply draft with quoted original content ready for inline editing.
• Use --reply-all only when you really want all original recipients copied.

Fast Command Map

Inspect accounts and folders

post servers
post folders --server 
post status --server  --mailbox INBOX

Find mail

post list --server  --mailbox INBOX --limit 20
post search --server  --from "someone@example.com" --since 2026-03-01
post fetch  --server  --mailbox INBOX
post fetch  --server  --mailbox INBOX --json

Draft and reply

# New draft
post draft --server  --from me@example.com --to you@example.com \
  --subject "Hello" --body reply.md

# Threaded reply with body
post draft --server  --replying-to  --body reply.md

# Threaded reply, reply-all
post draft --server  --replying-to  --reply-all --body reply.md

# Threaded reply for inline editing in Mail.app
post draft --server  --replying-to 

# Reply to a message outside INBOX
post draft --server  --replying-to  --reply-mailbox Archive --body reply.md

Attachments and exports

post attachment  --server  --mailbox INBOX --output /tmp/mail
post pdf  --server  --mailbox INBOX --output /tmp/
post eml  --server  --mailbox INBOX --output /tmp/

Organize mail

post move  Archive --server  --mailbox INBOX
post archive  --server  --mailbox INBOX
post trash  --server  --mailbox INBOX
post junk  --server  --mailbox INBOX

Reply Workflow Guidance

For real replies, prefer one of these two modes:

1. Compose in Markdown first

   • Fetch the original message
   • Write a .md file with your reply
   • Use post draft --replying-to --body reply.md

2. Create a native Mail-style draft

   • Use post draft --replying-to
   • Open and finish it in Mail.app

For multi-question emails, fetch the message first, identify each question, and write an interleaved Markdown reply using blockquotes. See references/common-tasks.md for a full example.

Security / Agent Isolation

Use per-agent API keys instead of sharing a full-access environment:

post api-key create --servers work
post api-key create --servers personal

Then either:

post servers --token 

or set only that agent’s environment:

export POST_API_KEY=

Details and setup examples live in SETUP.md.