EmailOS Read Command Documentation

The mailos read command displays the full content of a specific email by its ID or from email files.

For Apple Mail URL handling and macOS-specific attachment export behavior, see macOS Mail Integration.

Basic Usage

# Read from IMAP by email ID
mailos read [email_id]

# Read from email file
mailos read --file [email_file]

Displays the complete content of the specified email, including body text and attachment information. Supports reading from IMAP accounts or directly from email files in multiple formats (.eml, .mbox, .emlx, .msg).

Command-Line Flags

Basic Options

Flag	Short	Type	Default	Description	Example
--account		string		Email account to use	mailos read --account value
--from		string		Filter emails by sender (e.g., --from [email protected])	mailos read --from value
--limit		int	10	Limit number of recent emails to read	mailos read --limit value

Advanced Options

Flag	Short	Type	Default	Description	Example
--copy		bool	false	Copy email to clipboard after reading	mailos read --copy
--attachment-timeout		int	30	Timeout in seconds for attachment export fallback via Mail.app (macOS)	mailos read --attachment-timeout 15
--content		string		Read from raw text content instead of IMAP lookup	mailos read --content "From: [email protected]\nSubject: Hi\n\nBody"
--content-file		string		Read raw text content from a file path	mailos read --content-file /tmp/mail.txt
--content-from		string		Optional sender used when reading from content input	mailos read --content "Body" --content-from [email protected]
--content-html		string		Optional HTML body to use for markdown/link extraction with content input	mailos read --content "Body" --content-html "<p>Body</p>"
--content-stdin		bool	false	Read raw text content from stdin	`pbpaste
--content-subject		string		Optional subject used when reading from content input	mailos read --content "Body" --content-subject "Clipboard Email"
--eml-file		string		Read email from file (.eml, .mbox, .emlx, .msg)	mailos read --eml-file value
--eml-output		string		Directory to save EML file (default: current directory)	mailos read --eml-output value
--export-eml		bool	false	Export email to EML format	mailos read --export-eml
--file		string		Alias for --eml-file (read from email file)	mailos read --file value
--last		int	0	Show last N emails (alternative to --limit)	mailos read --last value
--list		bool	false	List recent emails with IDs for selection	mailos read --list
--links-only		bool	false	Output only extracted links for the target email	mailos read --links-only
--links-resolve-tracking		bool	false	Resolve tracking/redirect URLs to final destinations when possible	mailos read --links-resolve-tracking
--max-links		int	0	Maximum number of extracted links to output (0 = no limit)	mailos read --max-links 10
--markdown		bool	true	Output email as plain markdown (default true)	mailos read --markdown
--message-id		string		Message-ID to read (auto sync+retry on miss)	mailos read --message-id value
--message-link		bool	false	Print macOS message: URI for the resolved email	mailos read --message-link
--open-eml		bool	false	Export email to EML format and open in default mail client	mailos read --open-eml
--open-message-link		bool	false	Open macOS message: URI for the resolved email	mailos read --open-message-link
--recent		bool	false	Show recent emails without requiring Message-ID	mailos read --recent
--save-attachments		string		Directory to save attachments to disk (macOS can export via Mail.app by Message-ID)	mailos read --save-attachments value
--show-attachments		bool	true	Display attachment previews when available	mailos read --show-attachments
--suppress-attachment-errors		bool	false	Do not include attachment export errors in markdown output	mailos read --suppress-attachment-errors
--sync		bool	false	Fetch latest emails and retry Message-ID lookup when not found (for positional IDs)	mailos read --sync
--temp-eml		bool	false	Create temporary EML file (deleted after 5 minutes)	mailos read --temp-eml
--thread-id		string		Thread-ID to read	mailos read --thread-id value
--uid		uint32	0	Email UID from search results (stable handoff for mailos read)	mailos read --uid value
--write-md		string		Write full email content to markdown file (specify filename or directory)	mailos read --write-md value

Output Options

Flag	Short	Type	Default	Description	Example
--include-documents		bool	true	Parse and display attachment document content inline	mailos read --include-documents
--include-links		bool	false	Include URLs and Links section in read output	mailos read --include-links
--json		bool	false	Output emails in JSON format	mailos read --json

--json with a specific email target now includes a standardized links array with per-link metadata (text, url, canonical_url, resolved_url, type, source).

Markdown output now linkifies detected URLs and bare domains (for example meet.google.com/...) into Markdown links, and appends a standardized Links: section.

Getting Email IDs

Before using the read command, you need to find the email ID using the search command:

# Search for emails to get IDs
mailos search
mailos search --from [email protected]
mailos search --subject "meeting"

The search results will show email IDs that you can then use with the read command.

Reading from Email Files

The mailos read command can read emails directly from files without requiring an IMAP connection. This is useful for:

• Viewing archived emails (.eml files)
• Reading emails exported from other clients
• Processing batch email files
• Working offline with email data

Supported Formats

Format	Extension	Description	Status
EML	.eml	Standard MIME email format	✅ Full support
MBOX	.mbox	Unix mailbox format (extracts first message)	✅ Supported
EMLX	.emlx	Apple Mail format	✅ Supported
MSG	.msg	Outlook message format	⚠️ Limited (shows conversion instructions)

File Reading Examples

# Read standard EML file
mailos read --file email.eml

# Read Unix mailbox file
mailos read --file archive.mbox

# Read Apple Mail file
mailos read --file message.emlx

# Read and export to markdown
mailos read --file email.eml --write-md output.md

# Read with attachment extraction
mailos read --file email.eml --save-attachments ./attachments/

# Read Outlook MSG file (shows conversion instructions)
mailos read --file outlook.msg

Format-Specific Notes

MBOX Files:

• If the mbox file contains multiple messages, only the first message is displayed
• Additional messages are ignored with a warning message

EMLX Files (Apple Mail):

• XML metadata (plist) is automatically stripped from output
• Byte-count header is properly handled

MSG Files (Outlook):

• Currently not fully supported
• Command shows helpful error with conversion tool suggestions (msgconvert, outlook-msg-reader)
• Convert to .eml format first for best compatibility

Examples

Read a specific email by ID

mailos read 1423

Read email using the --uid flag

mailos read --uid 1423

Read raw content without IMAP

mailos read --content-file /tmp/mail.txt --include-links
pbpaste | mailos read --content-stdin --content-subject "Clipboard Email"

Read by Message-ID URI directly

mailos read "message://%3c79943605-7e8a-4e8a-970d-c2adec786dc1%40mtasv.net%3e"

Print email as markdown directly

mailos read --message-id "<[email protected]>" --account [email protected] --markdown

Read email without parsing document attachments

mailos read 1423 --include-documents=false

Read from EML file

mailos read --file email.eml

Read from mbox file and export to markdown

mailos read --file archive.mbox --write-md conversation.md

Read from Apple Mail file

mailos read --file message.emlx

Read email file with attachment extraction

mailos read --file email.eml --save-attachments ./attachments/

Output Format

The read command displays:

• Email Headers: From, To, Subject, Date, Message-ID
• Email Body: Full text content (HTML is converted to plain text)
• Attachments: List of attachment filenames
• Document Content: If --include-documents is enabled, displays parsed content from document attachments

Integration with Search and Files

IMAP Workflow

Typical workflow for reading from your email account:

# 1. Search for emails to find IDs
mailos search --from [email protected]

# 2. Read specific email from search results
mailos read 1423

# 3. Use search filters to narrow down results
mailos search --subject "contract" --has-attachments
mailos read 1445

File-Based Workflow

Working with email files directly:

# Read standalone email files
mailos read --file backup/important-email.eml

# Process multiple formats
mailos read --file exports/gmail-archive.mbox
mailos read --file apple-mail/message.emlx

# Export file content to markdown
mailos read --file email.eml --write-md analysis.md

Error Handling

Common errors and solutions:

# Invalid email ID format
Error: Email ID 'abc' is not a valid number
# Solution: Use numeric email IDs only

# Missing email ID
Error: Please provide an email ID
# Solution: Run 'mailos search' first to get email IDs

# Email not found
Error: Email with ID 9999 not found
# Solution: Verify the email ID exists using 'mailos search'

Notes

• Email IDs are obtained from the mailos search command
• The command reads from your configured email account or from email files
• Supports multiple email file formats: .eml, .mbox, .emlx, .msg (limited)
• Document parsing supports common formats (PDF, DOC, etc.)
• Large emails may take longer to load and display
• Email content is displayed in plain text format
• File reading works offline without IMAP connection
• MBOX files: only first message is read from multi-message files

Troubleshooting

Email not found

1. Verify the email ID is correct from search results
2. Check if email has been deleted or moved
3. Ensure you have access to the email account

Authentication errors

1. Check your email configuration: mailos setup
2. Verify your email password/app password is correct
3. Ensure IMAP access is enabled for your email provider

Document parsing issues

1. Use --include-documents=false to skip document parsing
2. Check if the attachment format is supported
3. Verify attachment isn't corrupted

See Also

• mailos search - Find emails and get IDs for reading
• mailos reply - Reply to emails after reading them