Name		Name	Last commit message	Last commit date
cmd		cmd
pkg		pkg
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
PERFORMANCE.md		PERFORMANCE.md
README.md		README.md
go.mod		go.mod
go.sum		go.sum
logo.png		logo.png
main.go		main.go

Repository files navigation

mail-app-cli

An Intelligrit Labs Project

A command-line interface for controlling macOS Mail.app. Provides complete scriptable access to accounts, mailboxes, messages, and attachments.

Features

List and manage Mail.app accounts
Browse and manage mailboxes
List, read, search, and manage messages
Archive, move, delete, flag, and mark messages
Send emails
Manage attachments
Fully scriptable - perfect for automation and building GUIs

Installation

From Source

go install github.com/intelligrit/mail-app-cli@latest

Build Locally

git clone https://github.com/intelligrit/mail-app-cli.git
cd mail-app-cli
go build -o mail-app-cli

Usage

Accounts

List all Mail.app accounts:

mail-app-cli accounts list

Show details for a specific account:

mail-app-cli accounts show "Gmail"

Mailboxes

List all mailboxes:

mail-app-cli mailboxes list

List mailboxes for a specific account:

mail-app-cli mailboxes list --account "Gmail"

Messages

List messages in a mailbox:

mail-app-cli messages list --account "Gmail" --mailbox "INBOX"

List with filters:

# Show only unread messages
mail-app-cli messages list -a "Gmail" -m "INBOX" --unread

# Show only flagged messages
mail-app-cli messages list -a "Gmail" -m "INBOX" --flagged

# Show messages since a specific date
mail-app-cli messages list -a "Gmail" -m "INBOX" --since "2025-12-01"

# Show messages since a specific date and time
mail-app-cli messages list -a "Gmail" -m "INBOX" --since "2025-12-14 09:00:00"

# Combine filters
mail-app-cli messages list -a "Gmail" -m "INBOX" --unread --since "2025-12-01" --limit 10

Show full message details:

mail-app-cli messages show <message-id> -a "Gmail" -m "INBOX"

Mark message as read/unread:

# Mark as read
mail-app-cli messages mark <message-id> -a "Gmail" -m "INBOX" --read

# Mark as unread
mail-app-cli messages mark <message-id> -a "Gmail" -m "INBOX" --read=false

Flag/unflag a message:

# Flag a message
mail-app-cli messages flag <message-id> -a "Gmail" -m "INBOX" --flagged

# Unflag a message
mail-app-cli messages flag <message-id> -a "Gmail" -m "INBOX" --flagged=false

Archive a message:

mail-app-cli messages archive <message-id> -a "Gmail" -m "INBOX"

Move a message to another mailbox:

mail-app-cli messages move <message-id> "Archive" -a "Gmail" -m "INBOX"

Delete a message:

mail-app-cli messages delete <message-id> -a "Gmail" -m "INBOX"

Sending Email

Send a message:

mail-app-cli send \
  --account "Gmail" \
  --to user@example.com \
  --subject "Hello" \
  --body "Message content here"

Send to multiple recipients:

mail-app-cli send \
  -a "Gmail" \
  -t user1@example.com \
  -t user2@example.com \
  -c cc@example.com \
  -s "Multi-recipient message" \
  --body "Content"

Search

Search for messages across all mailboxes:

mail-app-cli search "important meeting"

Search with limit:

mail-app-cli search "project update" --limit 20

Attachments

List attachments in a message:

mail-app-cli attachments list <message-id> -a "Gmail" -m "INBOX"

Save an attachment:

mail-app-cli attachments save <message-id> "document.pdf" -a "Gmail" -m "INBOX"

Save to a specific path:

mail-app-cli attachments save <message-id> "document.pdf" -a "Gmail" -m "INBOX" -o ~/Downloads/document.pdf

JSON Output and jq

All commands output JSON format for easy parsing and scripting. The output is formatted with 2-space indentation for human readability while remaining machine-parseable.

Pretty Printing

For even prettier output, pipe through jq:

mail-app-cli accounts list | jq

jq Examples

Filter accounts by email domain

mail-app-cli accounts list | jq '.[] | select(.emailAddress | endswith("@gmail.com"))'

Get only enabled accounts

mail-app-cli accounts list | jq '.[] | select(.enabled==true) | .name'

Count unread messages across all mailboxes

mail-app-cli mailboxes list | jq '[.[].unreadCount] | add'

Find mailboxes with unread messages

mail-app-cli mailboxes list | jq '.[] | select(.unreadCount > 0) | {account, name, unread: .unreadCount}'

Get just the subject lines from messages

mail-app-cli messages list -a "Gmail" -m "INBOX" | jq '.[].subject'

Filter unread messages from specific sender

mail-app-cli messages list -a "Gmail" -m "INBOX" | jq '.[] | select(.read==false and (.sender | contains("boss@company.com")))'

Search and format results as CSV

mail-app-cli search "important" | jq -r '.[] | [.account, .mailbox, .subject, .sender] | @csv'

Count messages by account

mail-app-cli search "project" | jq 'group_by(.account) | map({account: .[0].account, count: length})'

Get attachment names from a message

mail-app-cli attachments list <message-id> -a "Gmail" -m "INBOX" | jq '.[].name'

Find large attachments (>1MB)

mail-app-cli attachments list <message-id> -a "Gmail" -m "INBOX" | jq '.[] | select(.fileSize > 1048576)'

Scripting Examples

Check for unread messages

#!/bin/bash
unread=$(mail-app-cli messages list -a "Gmail" -m "INBOX" --unread | jq 'length')
if [ $unread -gt 0 ]; then
  echo "You have $unread unread messages"
fi

Archive all read messages

#!/bin/bash
mail-app-cli messages list -a "Gmail" -m "INBOX" | jq -r '.[] | select(.read==true) | .id' | while read -r msg_id; do
  mail-app-cli messages archive "$msg_id" -a "Gmail" -m "INBOX"
done

Daily unread summary

#!/bin/bash
echo "Today's Unread Email Summary"
echo "============================"
mail-app-cli mailboxes list | jq -r '.[] | select(.unreadCount > 0) | "\(.account)/\(.name): \(.unreadCount) unread"'

Save all attachments from a sender

#!/bin/bash
SENDER="colleague@company.com"
ACCOUNT="Gmail"
MAILBOX="INBOX"

# Find all messages from sender
mail-app-cli messages list -a "$ACCOUNT" -m "$MAILBOX" | jq -r ".[] | select(.sender | contains(\"$SENDER\")) | .id" | while read -r msg_id; do
  # Get attachments for each message
  mail-app-cli attachments list "$msg_id" -a "$ACCOUNT" -m "$MAILBOX" | jq -r '.[].name' | while read -r att_name; do
    echo "Saving: $att_name from message $msg_id"
    mail-app-cli attachments save "$msg_id" "$att_name" -a "$ACCOUNT" -m "$MAILBOX" -o "~/Downloads/$att_name"
  done
done

Project Structure

mail-app-cli/
├── cmd/              # Cobra command definitions
│   ├── root.go
│   ├── accounts.go
│   ├── mailboxes.go
│   ├── messages.go
│   ├── send.go
│   ├── search.go
│   └── attachments.go
├── pkg/
│   └── mail/        # Mail.app AppleScript/JXA client
│       └── client.go
└── main.go

How It Works

The CLI uses AppleScript and JavaScript for Automation (JXA) to interact with Mail.app. This provides:

Native integration with Mail.app
Access to all Mail.app features
No external dependencies or APIs required
Works with all mail providers configured in Mail.app

Requirements

macOS (tested on macOS 12+)
Mail.app configured with at least one account
Go 1.21+ (for building from source)

Development

Prerequisites

Go 1.21 or higher
macOS with Mail.app

Building

go build -o mail-app-cli

Testing

# Test account listing
./mail-app-cli accounts list

# Test mailbox listing
./mail-app-cli mailboxes list

# Test message listing
./mail-app-cli messages list -a "Your Account" -m "INBOX" --limit 5

Roadmap

Future enhancements:

Rules management
Smart mailbox operations
Signatures management
VIP contacts
Export/import functionality
Batch operations
IMAP folder synchronization
Message threading support
Draft management

Contributing

Contributions are welcome! This project follows standard Go conventions.

Guidelines

Fork the repository
Create a feature branch
Make your changes following Go best practices
Write tests for new functionality
Ensure all tests pass
Commit your changes
Push to the branch
Open a Pull Request

About Intelligrit Labs

mail-app-cli is developed by Intelligrit Labs, the R&D arm of Intelligrit LLC. We build tools for ourselves and release them for everyone. Intelligrit delivers AI-driven IT modernization for federal agencies.

License

MIT License - see LICENSE file for details

Support

For issues, questions, or contributions, please open an issue on GitHub.

Acknowledgments

Built with Cobra CLI framework
Uses AppleScript and JXA for Mail.app integration

About

A scriptable CLI interface for Mail.app

Readme

License

Activity

0 stars

0 watching

0 forks

Report repository

ezcoder/mail-app-cli: A scriptable CLI interface for Mail.app · GitHub

Latest commit

History

Folders and files

Repository files navigation

mail-app-cli

Features

Installation

From Source

Build Locally

Usage

Accounts

Mailboxes

Messages

Sending Email

Search

Attachments

JSON Output and jq

Pretty Printing

jq Examples

Filter accounts by email domain

Get only enabled accounts

Count unread messages across all mailboxes

Find mailboxes with unread messages

Get just the subject lines from messages

Filter unread messages from specific sender

Search and format results as CSV

Count messages by account

Get attachment names from a message

Find large attachments (>1MB)

Scripting Examples

Check for unread messages

Archive all read messages

Daily unread summary

Save all attachments from a sender

Project Structure

How It Works

Requirements

Development

Prerequisites

Building

Testing

Roadmap

Contributing

Guidelines

About Intelligrit Labs

License

Support

Acknowledgments

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages