# Email Sorter - Credentials Management

This directory stores authentication credentials for email providers. The system supports up to 3 accounts of each type (Gmail, Outlook, IMAP).

## Directory Structure

```
credentials/
├── gmail/
│   ├── account1.json          # Primary Gmail account
│   ├── account2.json          # Secondary Gmail account
│   ├── account3.json          # Tertiary Gmail account
│   └── account1.json.example  # Template
├── outlook/
│   ├── account1.json          # Primary Outlook account
│   ├── account2.json          # Secondary Outlook account
│   ├── account3.json          # Tertiary Outlook account
│   └── account1.json.example  # Template
└── imap/
    ├── account1.json          # Primary IMAP account
    ├── account2.json          # Secondary IMAP account
    ├── account3.json          # Tertiary IMAP account
    └── account1.json.example  # Template
```

## Gmail Setup

### 1. Create OAuth Credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Create a new project (or select existing)
3. Enable Gmail API
4. Go to "Credentials" → "Create Credentials" → "OAuth client ID"
5. Choose "Desktop app" as application type
6. Download the JSON file
7. Save as `credentials/gmail/account1.json` (or account2.json, account3.json)

### 2. Credential File Format

```json
{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "project_id": "your-project-id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uris": ["http://localhost"]
  }
}
```

### 3. Usage

```bash
# Account 1
python -m src.cli run --source gmail --credentials credentials/gmail/account1.json --limit 1000

# Account 2
python -m src.cli run --source gmail --credentials credentials/gmail/account2.json --limit 1000

# Account 3
python -m src.cli run --source gmail --credentials credentials/gmail/account3.json --limit 1000
```

## Outlook Setup

### 1. Register Azure AD Application

1. Go to [Azure Portal](https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps)
2. Click "New registration"
3. Name your app (e.g., "Email Sorter")
4. Choose "Accounts in any organizational directory and personal Microsoft accounts"
5. Set Redirect URI to "Public client/native" with `http://localhost:8080`
6. Click "Register"
7. Copy the "Application (client) ID"
8. (Optional) Create a client secret in "Certificates & secrets" for server apps

### 2. Configure API Permissions

1. Go to "API permissions"
2. Click "Add a permission"
3. Choose "Microsoft Graph"
4. Select "Delegated permissions"
5. Add:
   - Mail.Read
   - Mail.ReadWrite
6. Click "Grant admin consent" (if you have admin rights)

### 3. Credential File Format

```json
{
  "client_id": "YOUR_AZURE_APP_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET_OPTIONAL",
  "tenant_id": "common",
  "redirect_uri": "http://localhost:8080"
}
```

**Note:** `client_secret` is optional for desktop apps using device flow authentication.

### 4. Usage

```bash
# Account 1
python -m src.cli run --source outlook --credentials credentials/outlook/account1.json --limit 1000

# Account 2
python -m src.cli run --source outlook --credentials credentials/outlook/account2.json --limit 1000

# Account 3
python -m src.cli run --source outlook --credentials credentials/outlook/account3.json --limit 1000
```

## IMAP Setup

### 1. Get IMAP Credentials

For Gmail IMAP:
1. Enable 2-factor authentication on your Google account
2. Go to https://myaccount.google.com/apppasswords
3. Generate an "App Password" for "Mail"
4. Use this app password (not your real password)

For Outlook/Office365 IMAP:
- Host: `outlook.office365.com`
- Port: `993`
- Use your regular password or app password

### 2. Credential File Format

```json
{
  "host": "imap.gmail.com",
  "port": 993,
  "username": "your.email@gmail.com",
  "password": "your_app_password_or_password",
  "use_ssl": true
}
```

### 3. Usage

```bash
# Account 1
python -m src.cli run --source imap --credentials credentials/imap/account1.json --limit 1000

# Account 2
python -m src.cli run --source imap --credentials credentials/imap/account2.json --limit 1000

# Account 3
python -m src.cli run --source imap --credentials credentials/imap/account3.json --limit 1000
```

## Security Notes

### Important Security Practices

1. **Never commit credentials to git**
   - The `.gitignore` file excludes `credentials/` directory
   - Only `.example` files should be committed

2. **File permissions**
   - Set restrictive permissions: `chmod 600 credentials/*/*.json`

3. **Credential rotation**
   - Rotate credentials periodically
   - Revoke unused credentials in provider dashboards

4. **Separation**
   - Keep each account's credentials in separate files
   - Use descriptive names (account1, account2, account3)

### Credential Storage Locations

**This directory** (`credentials/`) is for:
- Development and testing
- Personal use
- Single-user deployments

**NOT recommended for:**
- Production servers (use environment variables or secret managers)
- Multi-user systems (use proper authentication systems)
- Public repositories (credentials would be exposed)

## Troubleshooting

### Gmail Issues

**Error: "credentials_path required"**
- Ensure you're passing `--credentials` flag
- Verify file exists and path is correct

**Error: "GMAIL DEPENDENCIES MISSING"**
- Install dependencies: `pip install google-api-python-client google-auth-oauthlib`

**Error: "CREDENTIALS FILE NOT FOUND"**
- Check file exists at specified path
- Ensure filename is correct (case-sensitive)

### Outlook Issues

**Error: "client_id required"**
- Verify JSON file has `client_id` field
- Check Azure app registration

**Error: "OUTLOOK DEPENDENCIES MISSING"**
- Install dependencies: `pip install msal requests`

**Authentication timeout**
- Complete device flow authentication within time limit
- Check browser for authentication prompt
- Verify Azure app has correct permissions

### IMAP Issues

**Error: "Authentication failed"**
- For Gmail: Use app password, not regular password
- Enable "Less secure app access" if using regular password
- Verify username/password are correct

**Connection timeout**
- Check host and port are correct
- Verify firewall isn't blocking IMAP port
- Test connection with: `telnet imap.gmail.com 993`

## Testing Credentials

Test each credential file before running full classification:

```bash
# Test Gmail connection
python -m src.cli test-gmail --credentials credentials/gmail/account1.json

# Test Outlook connection
python -m src.cli test-outlook --credentials credentials/outlook/account1.json

# Test IMAP connection
python -m src.cli test-imap --credentials credentials/imap/account1.json
```

## Dependencies

### Gmail
```bash
pip install google-api-python-client google-auth-oauthlib google-auth-httplib2
```

### Outlook
```bash
pip install msal requests
```

### IMAP
No additional dependencies required (uses Python standard library).

---

**Remember:** Keep your credentials secure and never share them publicly!