# hotmail-agent

**Repository Path**: jerryzu/hotmail-agent

## Basic Information

- **Project Name**: hotmail-agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-21
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Hotmail Agent

> Automated Hotmail/Outlook email backup system powered by Claude Code skills and agent-browser

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node Version](https://img.shields.io/badge/node-%3E=18.0.0-brightgreen)](https://nodejs.org)
[![agent-browser](https://img.shields.io/badge/agent--browser-installed-blue)](https://github.com/microsoft/playwright)

## 📋 Overview

Hotmail Agent is a complete automation solution for backing up Hotmail/Outlook emails. It provides multiple ways to interact:

- **CLI Tool** - Command-line interface for automation
- **Claude Code Skills** - AI-powered workflow automation
- **Slash Commands** - Quick one-command execution
- **Programmatic API** - Integrate into your own projects

## ✨ Features

- 🔐 **Automated Login** - Secure authentication with credentials
- 📧 **Batch Download** - Download all unread emails as HTML
- 📄 **HTML Preservation** - Keep original formatting and styles
- 🚪 **Auto Logout** - Securely sign out after operations
- 🎯 **Multiple Interfaces** - CLI, Skills, or API
- 📊 **Progress Tracking** - Real-time status updates
- 🛡️ **Session Management** - Maintain browser state

## 🚀 Quick Start

### Prerequisites

```bash
# Install agent-browser globally
npm install -g agent-browser

# Install browser binaries
agent-browser install
```

### Installation

```bash
# Clone or extract hotmail-agent
cd hotmail-agent

# Install dependencies
npm install

# Install Claude Code skills (optional)
npm run install-skills
```

### Usage

#### Option 1: CLI (Recommended for automation)

```bash
# Set credentials (or use -e and -p options)
export HOTMAIL_EMAIL="your_email@hotmail.com"
export HOTMAIL_PASSWORD="<password>"

# Run complete backup
npm run backup

# Or use CLI directly
node src/cli.js backup

# With custom credentials
node src/cli.js backup -e your@email.com -p yourpassword
```

#### Option 2: Claude Code Skills

```
# Complete workflow
使用 hotmail-workflow skill 完成邮件备份

# Step by step
使用 hotmail-login skill 登录
使用 download-unread-emails skill 下载邮件
使用 hotmail-logout skill 退出
```

#### Option 3: Slash Command

```bash
# In Claude Code
/hotmail-backup
```

## 📖 Commands

### CLI Commands

```bash
# Complete backup workflow
hotmail-agent backup
hotmail-agent backup -e your@email.com -p password

# Individual operations
hotmail-agent login      # Login only
hotmail-agent download   # Download emails (requires active session)
hotmail-agent logout     # Logout only
hotmail-agent status     # Check status and configuration

# Install Claude Code skills
hotmail-agent install-skills
```

### Options

| Option | Alias | Description | Default |
|--------|-------|-------------|---------|
| `--email` | `-e` | Hotmail email address | HOTMAIL_EMAIL env var |
| `--password` | `-p` | Hotmail password | HOTMAIL_PASSWORD env var |
| `--session` | `-s` | Browser session name | `hotmail` |
| `--verbose` | `-v` | Verbose output | `false` |
| `--help` | `-h` | Show help | - |
| `--version` | `-V` | Show version | - |

## 📁 Project Structure

```
hotmail-agent/
├── package.json           # Project configuration
├── README.md              # This file
├── src/
│   ├── index.js          # Main HotmailAgent class
│   └── cli.js            # CLI interface
├── skills/               # Claude Code skills
│   ├── hotmail-login/
│   ├── download-unread-emails/
│   ├── hotmail-logout/
│   └── hotmail-workflow/
├── commands/             # Slash commands
│   └── hotmail-backup.md
├── examples/             # Usage examples
├── tests/                # Test files
├── docs/                 # Additional documentation
└── config/               # Configuration files
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file or set environment variables:

```bash
# Hotmail credentials
HOTMAIL_EMAIL=your_email@hotmail.com
HOTMAIL_PASSWORD=<password>

# Optional settings
HOTMAIL_SESSION=hotmail
NODE_ENV=production
```

### Configuration File

Create `config/hotmail.json`:

```json
{
  "email": "your_email@hotmail.com",
  "password": "<password>",
  "sessionName": "hotmail",
  "downloadDir": "./downloads",
  "maxEmails": 50,
  "timeout": 30000
}
```

## 📝 Examples

### Basic Usage

```javascript
const HotmailAgent = require('hotmail-agent');

// Create agent instance
const agent = new HotmailAgent({
  email: 'your_email@hotmail.com',
  password: '<password>',
  verbose: true
});

// Run complete backup
const result = await agent.backup();
console.log(`Downloaded ${result.downloaded} emails`);
```

### Advanced Usage

```javascript
const HotmailAgent = require('hotmail-agent');

const agent = new HotmailAgent({
  email: process.env.HOTMAIL_EMAIL,
  password: process.env.HOTMAIL_PASSWORD,
  sessionName: 'my-session',
  workingDir: './backups'
});

// Step by step control
try {
  await agent.login();
  const emails = await agent.downloadEmails();
  console.log(`Downloaded: ${emails.emails.join(', ')}`);
  await agent.logout();
} catch (error) {
  console.error('Backup failed:', error);
  await agent.close();
}
```

### With Error Handling

```javascript
const HotmailAgent = require('hotmail-agent');

async function backupWithRetry() {
  const agent = new HotmailAgent({
    email: 'your@email.com',
    password: 'yourpassword',
    verbose: true
  });

  try {
    const result = await agent.backup();

    if (result.success) {
      console.log('✅ Backup successful!');
      console.log(`📧 ${result.downloaded} emails downloaded`);
      console.log(`⏱️  Took ${result.duration} seconds`);
    } else {
      console.error('❌ Backup failed:', result.error);
    }
  } catch (error) {
    console.error('💥 Unexpected error:', error);
  } finally {
    await agent.close();
  }
}

backupWithRetry();
```

## 🧪 Testing

```bash
# Run tests
npm test

# Check status
npm run status

# Verify agent-browser installation
agent-browser --version
```

## 🤝 Integration with Claude Code

### Skills Installation

```bash
# Install skills to Claude Code
npm run install-skills
```

Skills will be available in Claude Code:

- `hotmail-login` - Login to Hotmail
- `download-unread-emails` - Download unread emails
- `hotmail-logout` - Logout from Hotmail
- `hotmail-workflow` - Complete workflow

### Slash Command

Install the command by copying `commands/hotmail-backup.md` to your Claude commands directory:

```bash
mkdir -p ~/.claude/commands
cp commands/hotmail-backup.md ~/.claude/commands/
```

Then use in Claude Code:
```
/hotmail-backup
```

## 🔒 Security

- **Never commit credentials** to version control
- Use environment variables for sensitive data
- Consider using a password manager
- Rotate passwords regularly
- Use session-specific passwords when possible

## 🐛 Troubleshooting

### agent-browser not found

```bash
npm install -g agent-browser
agent-browser install
```

### Login fails

1. Verify credentials are correct
2. Check for 2FA requirements
3. Try manual login first
4. Check network connectivity

### No emails downloaded

1. Check if there are unread emails
2. Verify session is active
3. Try running with `--verbose` flag
4. Check file permissions in download directory

### Session errors

```bash
# Close existing sessions
agent-browser --session hotmail close

# Try again
npm run backup
```

## 📊 Performance

| Operation | Typical Time |
|-----------|--------------|
| Login | 5-10 seconds |
| Download per email | 2-3 seconds |
| Logout | 3-5 seconds |
| Complete backup (10 emails) | ~60 seconds |

## 🗺️ Roadmap

- [ ] Support for multiple accounts
- [ ] Incremental backup (only new emails)
- [ ] Email filtering by date/sender
- [ ] Export to PDF/Text formats
- [ ] Parallel email downloading
- [ ] Web dashboard
- [ ] Database storage option
- [ ] Email categorization

## 📄 License

MIT License - see LICENSE file for details

## 🙏 Acknowledgments

- Built with [agent-browser](https://github.com/microsoft/agent-browser)
- Powered by [Claude Code](https://claude.ai/code)
- Uses [Playwright](https://playwright.dev/) under the hood

## 📧 Support

For issues and questions:
- Check documentation in `docs/`
- Review examples in `examples/`
- Open an issue on GitHub

## 🌟 Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

---

Made with ❤️ by Claude Code Assistant