npm package: @mneuhaus/ms365-mail
Description: Microsoft 365 Email CLI - A lightweight, focused CLI tool for Microsoft Graph email operations
Author: Marc Neuhaus
Latest version: 1.0.0

# 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](https://bun.sh) runtime installed
- Microsoft 365 or Outlook.com account

### Install Dependencies
```bash
cd ms365-mail
bun install
```

### Build Executable (Optional)
```bash
bun run build
```

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

## Quick Start

1. **Authenticate**:
   ```bash
   bun run src/index.js auth login
   ```

2. **List recent emails**:
   ```bash
   bun run src/index.js list
   ```

3. **Search emails**:
   ```bash
   bun run src/index.js search "project update"
   ```

4. **View email details**:
   ```bash
   bun run src/index.js show abc123def
   ```

## Usage

### Authentication Commands

```bash
# 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

```bash
# 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 user@domain.com

# 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

```bash
# Search email content
ms365-mail search "keyword"

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

# Search with sender filter
ms365-mail search --from user@domain.com "report"

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

### Email Details

```bash
# 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

```bash
# 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

```bash
# List all mail folders
ms365-mail folders

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

## Global Options

```bash
--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`:

```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

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

# Find emails from specific person with attachments
ms365-mail search --from "martin@company.com" --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](https://portal.azure.com)
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
```bash
bun test
```

### Building
```bash
# 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.