apple-mail

Search and read Apple Mail emails and extract attachments from local macOS storage.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/pepegar/nix-home --skill apple-mail-pepegar
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: apple-mail
Source: https://github.com/pepegar/nix-home/tree/main/skills/apple-mail
Command: npx skills add https://github.com/pepegar/nix-home --skill apple-mail-pepegar

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

This Skill allows users to efficiently search, read, and extract information and attachments from their local Apple Mail data, overcoming the limitations of the native Mail app's search and export capabilities.

Core Features & Use Cases

  • Search Emails: Query emails by sender, recipient, subject, body content, date range, mailbox, and flags (unread, flagged).
  • Read Raw Emails: View the complete RFC822 format of any email message.
  • Extract Attachments: Save attachments from specific emails to a designated temporary directory.
  • View Mailboxes: List all available mailboxes with their message counts.
  • Use Case: Quickly find an important invoice email from a specific sender within the last year, or extract all attachments from a project-related thread.

Quick Start

Search for emails from '[email protected]' with 'invoice' in the subject, limiting results to 5.

Frequently Asked Questions about apple-mail

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search Apple Mail emails by sender and subject from the command line?

You can search Apple Mail emails by sender and subject by querying the local SQLite envelope index with a bash script. This allows filtering messages by sender, recipient, subject, body content, date range, mailbox, and read or flagged status.

Can I extract attachments from Apple Mail messages using a script?

Yes, you can extract attachments from Apple Mail messages using a script. It accesses local .emlx files and saves email attachments from specific messages directly to a designated temporary directory.

Does macOS Apple Mail scripting support retrieving raw RFC822 email data?

Yes, macOS Apple Mail scripting supports retrieving raw RFC822 email data. It reads the complete RFC822 format of any message directly from local .emlx files stored on your macOS device.

What is the best way to list all Apple Mail mailboxes and their message counts?

The best way to list all Apple Mail mailboxes and their message counts is by using a bash script. It queries the local SQLite envelope index to display all available mailboxes alongside their respective message counts.

Are there limitations to scripting read-only access for Apple Mail local storage?

Yes, limitations of scripting read-only access for Apple Mail local storage include the inability to modify, send, or delete emails. The script strictly queries the SQLite envelope index and extracts .emlx files without altering mailbox data.