EmailOS Download Command Documentation

The mailos download command downloads email attachments from your inbox based on search criteria and saves them to a specified directory.

Basic Usage

mailos download [flags]

Downloads attachments from emails that match your search criteria to a local directory, perfect for organizing project files and client communications.

Command-Line Flags

Flag	Description	Default	Example
--account	Email account to use		mailos download --account [email protected]
--id	Download attachments from specific email ID		mailos download --id 12345
--from	Filter by sender email address		mailos download --from "[email protected]"
--to	Filter by recipient email address		mailos download --to "[email protected]"
--subject	Filter by subject line (partial match)		mailos download --subject "contract"
--days	Search emails from last N days (0 = no limit, max: 365)	0	mailos download --days 30
--number	Maximum number of emails to search (max: 1000)	10	mailos download --number 50
--output-dir	Directory to save attachments	./attachments	mailos download --output-dir ./project-docs
--show-content	Show email content preview with attachment details	false	mailos download --show-content

Project-Based Workflows

The download command is designed for organizing emails and attachments by project or topic:

Scenario 1: Download Client Project Files

# Navigate to your project directory
cd /path/to/client-project

# Download all attachments from specific client
mailos download --from "[email protected]" --output-dir ./attachments

# Download contract-related files from last 30 days
mailos download --subject "contract" --days 30 --output-dir ./contracts

Scenario 2: Legal Document Organization

# Create organized structure
mkdir -p legal-docs/contracts legal-docs/agreements

# Download different types of legal documents
mailos download --from "[email protected]" --subject "contract" --output-dir ./legal-docs/contracts
mailos download --from "[email protected]" --subject "agreement" --output-dir ./legal-docs/agreements

Scenario 3: Specific Email Thread

# Download attachments from a specific email discussion
mailos download --id 12345 --output-dir . --show-content

Examples

Download all attachments from a specific sender

mailos download --from "[email protected]" --number 20 --output-dir ./john-files

Download recent attachments with subject filter

mailos download --subject "proposal" --days 7 --output-dir ./proposals

Download from multiple criteria

mailos download --from "[email protected]" --subject "invoice" --days 90 --output-dir ./invoices

Download with content preview

mailos download --from "[email protected]" --show-content --number 5

Getting Email IDs

Before downloading from a specific email ID, use the search command to find the ID:

# Search for emails to get IDs
mailos search --from "[email protected]"
mailos search --subject "important document"
mailos search --days 7

The search results will show email IDs that you can use with the --id flag.

Output and Organization

Attachment Handling

• Attachments are saved with their original filenames
• Duplicate filenames are automatically handled with timestamps
• Directory structure is created automatically if it doesn't exist
• Empty directories are created even if no attachments are found

Progress Indicators

• Shows total number of emails found
• Displays attachment count per email
• Indicates final save location
• Provides warnings for large operations

Performance and Limits

• Maximum 1000 emails per search (prevents system overload)
• Maximum 365 days for date range searches
• 2-minute timeout for single email operations
• 5-minute timeout for batch search operations

Error Handling

Common Issues and Solutions

Email ID not found:

Error: email with ID 12345 not found

• Verify the email ID using mailos search
• Check if the email has been deleted or moved

Operation timeout:

Error: operation timed out after 5 minutes

• Reduce search scope with --number or --days
• Check network connection
• Try searching for a more specific criteria

No attachments found:

No emails with attachments found matching criteria

• Broaden search criteria (remove filters)
• Check if emails actually have attachments
• Verify account access and authentication

Security and Privacy

• Attachments are downloaded to your local system only
• No data is transmitted to external services
• Respects existing email account authentication
• Works with all supported email providers (Gmail, FastMail, Outlook, etc.)

Integration with Other Commands

Workflow Integration

# Find emails first
mailos search --from "[email protected]" --days 30

# Read specific email for context
mailos read 12345

# Download its attachments
mailos download --id 12345 --output-dir ./client-files

# Send response
mailos send --to "[email protected]" --subject "Re: Documents received"

Batch Operations

# Download from multiple sources to organized structure
mailos download --from "[email protected]" --output-dir ./legal
mailos download --from "[email protected]" --output-dir ./finance
mailos download --from "[email protected]" --output-dir ./hr

Tips and Best Practices

1. Use specific output directories for better organization
2. Combine filters (--from, --subject, --days) for precise results
3. Use --show-content to preview before bulk downloads
4. Start with small --number values to test your filters
5. Create project-specific directories before downloading
6. Use --days parameter to limit scope and improve performance

Troubleshooting

Permission Issues

Ensure you have write permissions to the output directory:

chmod 755 ./attachments

Large Volume Downloads

For large attachment downloads:

• Use smaller --number values (10-50)
• Filter by specific date ranges (--days)
• Download in batches by sender or subject

Network Issues

If experiencing timeouts:

• Check internet connection
• Reduce search scope
• Try downloading specific emails by ID first