MS365-Mail - Microsoft 365 Email CLI

A lightweight, focused CLI tool for Microsoft Graph email operations built with Bun. Inspired by tools like gh and glab - simple, intuitive, and purpose-built for email management.

Features

• 🔐 Easy Authentication: Device code flow for secure login
• 📧 Email Operations: List, search, read, and manage emails
• 📎 Attachment Handling: Download individual or all attachments
• 📁 Folder Management: Browse and manage mail folders
• 🎨 Multiple Output Formats: Table (default) and JSON output
• ⚡ Fast Performance: Built with Bun for lightning-fast startup
• 🔧 Configurable: Customizable defaults and preferences

Installation

Prerequisites

• Bun runtime installed
• Microsoft 365 or Outlook.com account

Install Dependencies

cd ms365-mail
bun install

Build Executable (Optional)

bun run build

This creates a single binary ms365-mail file that can be moved to your PATH.

Quick Start

1. Authenticate:

   bun run src/index.js auth login

2. List recent emails:

   bun run src/index.js list

3. Search emails:

   bun run src/index.js search "project update"

4. View email details:

   bun run src/index.js show abc123def

Usage

Authentication Commands

# Login with device code flow
ms365-mail auth login

# Check authentication status
ms365-mail auth status

# Logout and clear credentials
ms365-mail auth logout

Email Management

# List recent emails (default: 20)
ms365-mail list

# List specific number of emails
ms365-mail list --count 50

# List unread emails only
ms365-mail list --unread

# List emails from specific sender
ms365-mail list --from [email protected]

# List emails from last 7 days
ms365-mail list --since 7d

# List emails with attachments
ms365-mail list --has-attachments

# List emails from specific folder
ms365-mail list --folder sent

Search Operations

# Search email content
ms365-mail search "keyword"

# Search in subject only
ms365-mail search --subject "meeting"

# Search with sender filter
ms365-mail search --from [email protected] "report"

# Search emails with attachments
ms365-mail search --has-attachments "invoice"

Email Details

# Show email content
ms365-mail show <email-id>

# Show with full headers
ms365-mail show <email-id> --headers

# Show raw email data
ms365-mail show <email-id> --raw

Attachment Operations

# List attachments for an email
ms365-mail attachments <email-id>

# Download all attachments
ms365-mail download <email-id>

# Download to specific directory
ms365-mail download <email-id> --output ./my-downloads

# Download specific attachment
ms365-mail download <email-id> "report.pdf"

Folder Operations

# List all mail folders
ms365-mail folders

# List emails from specific folder
ms365-mail list --folder "Project Updates"

Global Options

--format json       # Output as JSON instead of table
--no-color         # Disable colored output
--config <file>    # Use custom config file
--help             # Show help information
--version          # Show version number

Configuration

The CLI stores configuration in ~/.config/ms365-mail/config.json:

{
  "auth": {
    "tenant_id": "common",
    "client_id": "your-app-id"
  },
  "defaults": {
    "count": 20,
    "format": "table",
    "folder": "inbox"
  },
  "output": {
    "color": true,
    "date_format": "YYYY-MM-DD HH:mm"
  }
}

Time Filters

Support for relative time expressions:

• 1h, 6h - Hours
• 1d, 7d - Days
• 1w, 2w - Weeks
• 1m, 3m - Months

Examples

# Daily email check
ms365-mail list --unread --count 10

# Find emails from specific person with attachments
ms365-mail search --from "[email protected]" --has-attachments

# Download all attachments from an email
ms365-mail show abc123 | grep "ID:" | cut -d' ' -f2 | xargs ms365-mail download

# Check emails from last week in sent folder
ms365-mail list --folder sent --since 1w --count 50

# Search for invoices and export to JSON
ms365-mail search "invoice" --format json > invoices.json

Error Codes

• 0 - Success
• 1 - General error
• 2 - Authentication required

Microsoft App Registration

For organizational use, you may need to register your own Azure AD application:

1. Go to Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Create new registration with these settings:
   • Name: MG Email CLI
   • Supported account types: Accounts in any organizational directory and personal Microsoft accounts
   • Redirect URI: Public client/native (mobile & desktop) - http://localhost
4. Under API permissions, add:
   • Mail.Read (Delegated)
   • Mail.ReadWrite (Delegated)
5. Update your config with the new client_id

Development

Project Structure

ms365-mail/
├── src/
│   ├── commands/          # Individual command implementations
│   ├── lib/              # Core libraries (auth, graph client, config)
│   ├── utils/            # Utilities (formatters, parsers)
│   └── index.js          # Main CLI entry point
├── package.json
└── README.md

Running Tests

bun test

Building

# Development build
bun run dev

# Production build (single binary)
bun run build

Troubleshooting

Authentication Issues

• Ensure you have internet connectivity
• Try clearing credentials: ms365-mail auth logout then ms365-mail auth login
• Check if your organization requires app approval

Permission Issues

• Verify the required Microsoft Graph permissions are granted
• Contact your IT administrator for organizational accounts

Performance Issues

• Use --count to limit results for large mailboxes
• Consider using date filters (--since) for recent emails only

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and feature requests, please create an issue on the GitHub repository.