simple-email-gw 0.1.0

Simple email gateway with IMAP/SMTP clients, connection pooling, and MCP server

simple-email-gw

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

pip install simple-email-gw

Using uv

uv add simple-email-gw

Quick Start

MCP Server

Run the MCP server for AI assistant integration:

# Set environment variables
export EMAIL_IMAP_HOST=imap.gmail.com
export EMAIL_SMTP_HOST=smtp.gmail.com
export EMAIL_USERNAME=[e-mail]
export EMAIL_PASSWORD=your-app-password

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

Programmatic Usage

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="[e-mail]",
  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=["[e-mail]"],
    subject="Test",
    body="Hello world"
  )
  print(f"Sent: {result}")

asyncio.run(main())

Configuration

Environment Variables

Single account configuration:

EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_USERNAME=[e-mail]
EMAIL_PASSWORD=app-password

Multiple accounts (JSON):

EMAIL_ACCOUNTS_JSON='[{"name":"work","imap_host":"imap.gmail.com","smtp_host":"smtp.gmail.com","username":"[e-mail]","password":"secret"},{"name":"personal","imap_host":"imap.icloud.com","smtp_host":"smtp.icloud.com","username":"[e-mail]","password":"secret"}]'

See 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:

EMAIL_RECIPIENT_DOMAINS=gmail.com,icloud.com
EMAIL_RECIPIENT_ADDRESSES=[e-mail]

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 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 for complete API reference.

Development

See docs/development.md for development setup and contribution guidelines.

Quick commands:

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 for details.