Metadata-Version: 2.4
Name: simple-email-gw
Version: 0.1.0
Summary: Simple email gateway with IMAP/SMTP clients, connection pooling, and MCP server
Author-email: Christophe VG <contact@christophe.vg>
License: MIT
License-File: LICENSE
Keywords: email,imap,mcp,model-context-protocol,smtp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aioimaplib>=1.0.0
Requires-Dist: aiosmtplib>=3.0.0
Requires-Dist: fastmcp>=3.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: tox>=4.0.0; extra == 'dev'
Requires-Dist: twine>=6.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.0.0; extra == 'docs'
Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
Requires-Dist: sphinx>=7.0.0; extra == 'docs'
Description-Content-Type: text/markdown

# simple-email-gw

[![PyPI version](https://img.shields.io/pypi/v/simple-email-gw.svg)](https://pypi.org/project/simple-email-gw/)
[![Python versions](https://img.shields.io/pypi/pyversions/simple-email-gw.svg)](https://pypi.org/project/simple-email-gw/)
[![License](https://img.shields.io/github/license/christophevg/simple-email-gw.svg)](https://github.com/christophevg/simple-email-gw/blob/main/LICENSE)
[![CI](https://github.com/christophevg/simple-email-gw/actions/workflows/ci.yml/badge.svg)](https://github.com/christophevg/simple-email-gw/actions/workflows/ci.yml)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-blue.svg)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](https://mypy.readthedocs.io/)
[![Read the Docs](https://img.shields.io/readthedocs/simple-email-gw.svg)](https://simple-email-gw.readthedocs.io/)

A simple email gateway with IMAP/SMTP clients, connection pooling, and MCP server for AI assistant integration.

> **Note:** This package provides **async-only** APIs. All client methods are async and must be used with `asyncio.run()` or in async contexts.

## Features

- Async IMAP and SMTP clients (aioimaplib, aiosmtplib)
- Connection pooling with automatic management
- Token bucket rate limiting
- Audit logging for security compliance
- CRLF injection prevention
- Recipient whitelist enforcement
- TLS 1.2+ minimum encryption
- MCP server for AI assistant integration

## Installation

### Using pip

```bash
pip install simple-email-gw
```

### Using uv

```bash
uv add simple-email-gw
```

## Quick Start

### MCP Server

Run the MCP server for AI assistant integration:

```bash
# Set environment variables
export EMAIL_IMAP_HOST=imap.gmail.com
export EMAIL_SMTP_HOST=smtp.gmail.com
export EMAIL_USERNAME=your-email@gmail.com
export EMAIL_PASSWORD=your-app-password

# Run server
uvx --from simple-email-gw mcp-server
```

### Programmatic Usage

```python
import asyncio
from simple_email_gw import IMAPClient, SMTPClient, EmailAccount

# Create account configuration
account = EmailAccount(
  name="work",
  imap_host="imap.gmail.com",
  smtp_host="smtp.gmail.com",
  username="user@gmail.com",
  password="app-password"
)

async def main():
  # Use IMAP client
  async with IMAPClient(account) as client:
    folders = await client.list_folders()
    messages = await client.search(folder="INBOX")
    print(f"Found {len(messages)} messages")

  # Use SMTP client
  smtp = SMTPClient(account)
  result = await smtp.send_email(
    to=["recipient@example.com"],
    subject="Test",
    body="Hello world"
  )
  print(f"Sent: {result}")

asyncio.run(main())
```

## Configuration

### Environment Variables

Single account configuration:

```bash
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_USERNAME=user@gmail.com
EMAIL_PASSWORD=app-password
```

Multiple accounts (JSON):

```bash
EMAIL_ACCOUNTS_JSON='[{"name":"work","imap_host":"imap.gmail.com","smtp_host":"smtp.gmail.com","username":"work@example.com","password":"secret"},{"name":"personal","imap_host":"imap.icloud.com","smtp_host":"smtp.icloud.com","username":"personal@icloud.com","password":"secret"}]'
```

See [docs/configuration.md](docs/configuration.md) for detailed configuration options.

### Rate Limiting

Default limits:
- IMAP: 60 requests per minute per account
- SMTP: 100 sends per hour per account

### Recipient Whitelist

Restrict outgoing emails to specific domains or addresses:

```bash
EMAIL_RECIPIENT_DOMAINS=gmail.com,icloud.com
EMAIL_RECIPIENT_ADDRESSES=admin@company.com
```

## Security Features

### TLS 1.2+ Minimum

All connections require TLS 1.2 or higher. Connections with older TLS versions are rejected.

### CRLF Injection Prevention

All email headers are sanitized to prevent CRLF injection attacks:
- Subject lines
- Message-IDs
- References headers
- Email addresses

### Recipient Whitelist

Optional whitelist restricts outgoing emails to approved recipients.

### Rate Limiting

Token bucket algorithm prevents abuse with separate limits per account.

### Audit Logging

All operations are logged for security compliance.

See [docs/security.md](docs/security.md) for complete security documentation.

## MCP Tools

| Tool | Purpose |
|------|---------|
| `list_accounts` | List configured email accounts |
| `list_folders` | List IMAP folders |
| `search_emails` | Search messages by criteria |
| `get_email` | Fetch single message |
| `download_attachment` | Download attachment to workspace |
| `send_email` | Send new email |
| `reply_email` | Reply to thread |
| `move_email` | Move between folders |
| `delete_email` | Delete message |
| `mark_email_read` | Mark message as read |

See [docs/api.md](docs/api.md) for complete API reference.

## Development

See [docs/development.md](docs/development.md) for development setup and contribution guidelines.

Quick commands:

```bash
make dev-env    # Install development dependencies
make test       # Run tests
make lint       # Run linter
make typecheck  # Run type checker
make all        # Run all checks
make mcp-server # Run the MCP server
```

## License

MIT License - see [LICENSE](LICENSE) for details.
