Draft Management

The mailos drafts command (also available as mailos draft) manages drafts stored globally on the current machine in ~/.email/drafts.

Overview

Create, manage metadata, tag, inspect, and send drafts from any working directory. Each draft is one self-contained Markdown file with YAML frontmatter and a stable ID that can be passed to mailos drafts metadata, mailos drafts show, or mailos send --draft-id. MailOS reloads that file when changing metadata or sending so the user's latest edits are used. JSON draft files are not supported.

mailos drafts metadata changes frontmatter fields only: recipients, subject, attachments, and tags. It cannot change the message body. To revise wording, tone, or other body content while retaining full control over the existing copy, edit the authoritative Markdown file directly. Both mailos drafts and mailos drafts list return each draft's absolute file path.

Draft discovery also records the current file in content-addressed history under ~/.email/drafts/history/<id>/<revision>.md. CLI updates, archive operations, manual drafts edit sessions, retained sends, and deletion after sending all snapshot the prior version. Use history, diff, and restore to inspect or recover those versions. MailOS verifies that every history file's content matches the SHA-256 revision in its filename before listing, comparing, or restoring it; corrupted history is rejected without changing the current draft.

For automation, use mailos drafts list --json to obtain each draft's path and SHA-256 revision, or mailos drafts path <id> when only the absolute path is needed. Frontmatter updates require the current revision so they cannot silently overwrite a newer file change.

Frontmatter is parsed as strict YAML. Block and inline lists, quoted values, comments, and empty lists are supported; unknown fields or malformed YAML stop update and send operations with an error.

Draft lifecycle statuses are working, ready, archived, and sent. mailos drafts list shows only active working and ready drafts, while mailos drafts list --all includes the complete local history. Archive abandoned work with mailos drafts archive <id>. Bulk sends skip archived and retained-sent drafts. A successful send keeps its draft and changes its status to sent. Pass --delete-after only when the local Markdown should be removed after its current revision has been saved in history.

Use mailos drafts edit <id> to open the authoritative Markdown file with $VISUAL, falling back to $EDITOR. Pass --editor <command> to override it. After the editor exits, MailOS reloads and validates the saved file and returns its clickable local link. mailos drafts validate <id> performs the readiness check without opening an editor or sending anything.

Basic Usage

# Create a global local draft with a stable ID
mailos drafts create --to [email protected] --subject "Follow up" --body "Hello" --tag client

# Update, list, inspect, and send a single draft
mailos drafts list --json
mailos drafts metadata d_0123456789ab --revision <current-revision> --cc [email protected] --tag client,ready
mailos drafts list
mailos drafts path d_0123456789ab
mailos drafts history d_0123456789ab
mailos drafts diff d_0123456789ab <revision>
mailos drafts restore d_0123456789ab <revision>
mailos drafts archive d_0123456789ab
mailos drafts list --all
mailos drafts show d_0123456789ab
mailos drafts edit d_0123456789ab
mailos drafts validate d_0123456789ab
mailos send --draft-id d_0123456789ab --preview
mailos send --draft-id d_0123456789ab --draft-revision <revision-from-preview>

# Create a single draft interactively
mailos draft --interactive

# Create multiple drafts (alias)
mailos drafts --interactive

# List drafts from IMAP Drafts folder
mailos draft --list

# Read full draft content from IMAP
mailos draft --read

# Generate drafts with AI
mailos draft --ai "create follow-up email for meeting" --count 3

# Send all drafts
mailos send --drafts

Command-Line Flags

Basic Options

Flag	Short	Type	Default	Description	Example
--account		string		Email account to use	mailos drafts --account value
--bcc	-B	[]string		BCC recipients	mailos drafts --bcc value
--body	-b	string		Email body (Markdown supported)	mailos drafts --body value
--cc	-c	[]string		CC recipients	mailos drafts --cc value
--subject	-s	string		Email subject	mailos drafts --subject value
--to	-t	[]string		Recipient email addresses	mailos drafts --to value

Advanced Options

Flag	Short	Type	Default	Description	Example
--ai		bool	false	Use AI to generate drafts from query	mailos drafts --ai
--attach	-a	[]string		Attachments	mailos drafts --attach value
--count	-n	int	1	Number of drafts to generate (with AI)	mailos drafts --count value
--data		string		Data file (CSV/JSON) for bulk draft generation	mailos drafts --data value
--edit-uid		uint32	0	UID of existing draft to edit/update	mailos drafts --edit-uid value
--file	-f	string		Read body from file	mailos drafts --file value
--force		bool	false	Force create draft bypassing dynamic content warnings	mailos drafts --force
--interactive	-i	bool	false	Interactive mode for creating drafts	mailos drafts --interactive
--list	-l	bool	false	List drafts from IMAP Drafts folder	mailos drafts --list
--no-signature	-S	bool	false	Don't add signature	mailos drafts --no-signature
--plain	-P	bool	false	Send as plain text only	mailos drafts --plain
--priority		string	normal	Email priority (high/normal/low)	mailos drafts --priority value
--read	-r	bool	false	Read full content of drafts from IMAP	mailos drafts --read
--replace		[]string		Replace dynamic content with KEY=VALUE pairs (e.g., --replace USER_NAME=John --replace DATE=2024-01-01)	mailos drafts --replace value
--signature		string		Custom signature	mailos drafts --signature value
--template		string		Use a template for draft generation	mailos drafts --template value

Output Options

Flag	Short	Type	Default	Description	Example
--output		string		Output directory for drafts (default: ~/.email/drafts)	mailos drafts --output value

Key Features

📮 Automatic IMAP Synchronization

• Drafts are automatically saved to your email account's Drafts folder
• Compatible with Gmail, Outlook, Yahoo, and other IMAP providers
• Drafts appear instantly in your email client
• Proper RFC 822 email format with \Draft IMAP flag

📝 Local and Remote Storage

• Local files saved to draft-emails/ directory
• Remote copies in your email provider's Drafts folder
• Dual storage provides backup and cross-device access

🎯 Smart Draft Detection

• Automatically detects the correct Drafts folder name
• Handles provider-specific folders ([Gmail]/Drafts, INBOX.Drafts, etc.)
• Creates Drafts folder if it doesn't exist

Command Options

mailos draft [options]

Option	Description
--list, -l	List drafts from IMAP Drafts folder
--read, -r	Read full content of drafts from IMAP
--interactive, -i	Create drafts interactively with prompts
--ai	Use AI to generate drafts from a query
--count N, -n N	Number of drafts to generate (with AI)
--template STRING	Use a template for draft generation
--data FILE	Data file (CSV/JSON) for bulk generation
--output DIR	Output directory (default: "draft-emails")

Draft File Format

Drafts are saved as Markdown files with YAML frontmatter:

---
to: [email protected]
cc: [email protected]
bcc: [email protected]
subject: Meeting Follow-up
priority: high
send_after: 2024-01-15 09:00:00
attachments:
  - report.pdf
  - presentation.pptx
---

Dear Team,

Following up on our meeting yesterday...

Best regards,
Your Name

Sending Drafts

Send All Drafts

mailos send --drafts

Preview Before Sending

mailos draft preview d_0123456789ab
mailos send --drafts --dry-run
mailos send --drafts --preview
mailos send --draft-id d_0123456789ab --preview

mailos draft preview <id> is the concise read-only form for one local draft. It prints the revision and complete delivered message, including the resolved project or account signature, then returns the authoritative Markdown path. Use --no-signature or --signature <text-or-file> to override signature rendering.

The preview prints a SHA-256 revision and the concise human follow-up command. Humans can run mailos send draft <id> and confirm the displayed message. Automated workflows must pass the previewed revision with mailos send draft <id> --draft-revision <revision>; if the Markdown changes, MailOS rejects that send and requires a new preview.

Before previewing or sending, MailOS requires a working or ready status, a non-empty subject, at least one syntactically valid to, cc, or bcc recipient, an ID matching the Markdown filename, and accessible regular files for every attachment. Relative attachment paths are resolved from the directory containing the draft Markdown file.

--dry-run prints send-oriented metadata without sending. --preview renders the draft content without sending and preserves the local Markdown draft. Use --forward-message-id or --forward-message-link with either mode to verify forwarded context before a live draft send.

Filter by Priority

# Only send high priority drafts
mailos send --drafts --filter="priority:high"

Filter by Recipient

# Only send to specific domain
mailos send --drafts --filter="to:*@company.com"

Additional Send Options

# Confirm each draft before sending
mailos send --drafts --confirm

# Delete drafts after sending instead of retaining them as sent
mailos send --drafts --delete-after

# Log sent emails
mailos send --drafts --log-file="sent.log"

Reading Drafts from IMAP

List All Drafts

# Show draft headers (subject, to, date)
mailos draft --list

Read Full Draft Content

# Show complete draft with body content
mailos draft --read

The draft reader will:

• Connect to your email provider
• Automatically detect the Drafts folder
• Display all drafts with proper formatting
• Show flags (Draft, Seen, etc.)
• Format dates in readable format

Interactive Draft Creation

When using --interactive, you'll be prompted for:

1. To: Primary recipient email address
2. CC: Carbon copy recipients (optional)
3. Subject: Email subject line
4. Body: Email content (Markdown supported)
5. Priority: high/normal/low (default: normal)

Press Enter twice after the body to finish.

AI-Powered Draft Generation

# Generate drafts from natural language
mailos draft --ai "create 3 follow-up emails for recent client meetings"

# Specify number of drafts
mailos draft --ai "thank you email" --count 5

Template-Based Drafts

# Use a template (coming soon)
mailos draft --template=follow-up --data=contacts.csv

Draft Organization

draft-emails/
├── 001-meeting-follow-up-2024-01-15-143022.md
├── 002-project-update-2024-01-15-143045.md
├── 003-thank-you-2024-01-15-143102.md
├── sent/                 # Successfully sent and retained
│   └── 001-meeting-follow-up-2024-01-15-143022.md
└── failed/               # Failed to send
    └── 003-thank-you-2024-01-15-143102.md

IMAP Folder Detection

The system automatically detects your provider's Drafts folder:

Provider	Common Folder Names
Gmail	[Gmail]/Drafts
Outlook	Drafts
Yahoo	Draft
Fastmail	INBOX.Drafts
Generic	Drafts, Draft

Error Handling

• If IMAP save fails, local draft is still created
• Warning displayed but operation continues
• Drafts can still be sent using local files

Examples

Weekly Newsletter Draft

# Create draft interactively
mailos draft --interactive

# Enter details:
To: [email protected]
Subject: Weekly Update - Week 3
Body: 
## This Week's Highlights
- Completed project milestone
- New team member onboarded
- Client meeting scheduled

# Draft saved locally and to email account

Batch Follow-up Emails

# Create multiple drafts
mailos draft --interactive
# Answer 'y' when asked "Create another draft?"

# Review all drafts
ls draft-emails/

# Send with confirmation
mailos send --drafts --confirm

Priority-Based Sending

# Create drafts with different priorities
mailos draft --interactive  # Set priority: high
mailos draft --interactive  # Set priority: normal

# Send only high priority
mailos send --drafts --filter="priority:high"

# Later, send normal priority
mailos send --drafts --filter="priority:normal"

Troubleshooting

Draft Not Appearing in Email Client

• Check your email client's Drafts folder
• Refresh/sync your email client
• Verify IMAP is enabled in your email settings

IMAP Connection Failed

• Ensure app-specific password is configured
• Check IMAP is enabled for your account
• Verify network connectivity

Drafts Folder Not Found

• System will attempt to create Drafts folder
• Falls back to INBOX if creation fails
• Local draft is always created successfully

Best Practices

1. Use Priority Levels: Organize drafts by importance
2. Preview Before Sending: Always use --dry-run for recipients/metadata or --preview for full rendered content first
3. Keep Sent Drafts: Successful sends retain the Markdown with status: sent; use --delete-after only when deletion is intentional
4. Batch Similar Emails: Create related drafts together
5. Review IMAP Status: Check for sync confirmation messages

Related Commands

• mailos send - Send individual emails
• mailos template - Manage email templates
• mailos interactive - Interactive email mode
• mailos read - Read emails from inbox

See Also

• Send Command - Detailed sending options
• Template Management - Create reusable templates {/* TODO: broken link removed — target page interactive.md does not exist in this repo. Restore once an Interactive Mode doc is added. */}