Configuration Guide¶

This document describes all configuration options for simple-email-gw.

Environment Variables¶

Single Account Configuration¶

For a single email account, use these environment variables:

EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=587
EMAIL_USERNAME=user@gmail.com
EMAIL_PASSWORD=app-specific-password
EMAIL_ACCOUNT_NAME=default

Multiple Accounts¶

For multiple accounts, provide a JSON configuration:

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"
  }
]'

OAuth2 Authentication¶

For providers that require OAuth2 (like Gmail with modern authentication):

EMAIL_AUTH_METHOD=oauth2
EMAIL_OAUTH2_TOKEN=ya29.a0...

Or in JSON format:

{
  "name": "gmail",
  "imap_host": "imap.gmail.com",
  "smtp_host": "smtp.gmail.com",
  "username": "user@gmail.com",
  "auth_method": "oauth2",
  "oauth2_token": "ya29.a0..."
}

Account Options¶

Option	Type	Default	Description
`name`	string	“default”	Friendly name for the account
`imap_host`	string	required	IMAP server hostname
`imap_port`	int	993	IMAP server port
`smtp_host`	string	required	SMTP server hostname
`smtp_port`	int	587	SMTP server port
`username`	string	required	Email address or username
`password`	string	None	Password or app-specific password
`oauth2_token`	string	None	OAuth2 access token
`auth_method`	string	“password”	Authentication method: “password” or “oauth2”
`use_ssl`	bool	True	Use SSL/TLS for connections

Rate Limiting¶

Configure rate limits to prevent abuse:

EMAIL_RATE_LIMITS__IMAP_REQUESTS_PER_MINUTE=60
EMAIL_RATE_LIMITS__SMTP_SENDS_PER_HOUR=100

Option	Type	Default	Description
`imap_requests_per_minute`	int	60	IMAP requests per minute per account
`smtp_sends_per_hour`	int	100	SMTP sends per hour per account

Recipient Whitelist¶

Restrict outgoing emails to specific recipients:

Domain Whitelist¶

EMAIL_RECIPIENT_DOMAINS=gmail.com,icloud.com,company.com

Address Whitelist¶

EMAIL_RECIPIENT_ADDRESSES=admin@company.com,support@partner.org

JSON Configuration¶

For more complex whitelist configurations:

EMAIL_RECIPIENT_WHITELIST_JSON='{
  "enabled": true,
  "domains": ["trusted.com", "partner.org"],
  "addresses": ["admin@company.com"]
}'

Workspace Configuration¶

Attachment downloads are confined to a workspace directory:

EMAIL_WORKSPACE=/path/to/workspace

Default: /tmp/email_workspace

.env File¶

You can use a .env file in the project root for local development:

# .env
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_USERNAME=user@gmail.com
EMAIL_PASSWORD=app-password
EMAIL_RECIPIENT_DOMAINS=gmail.com

Load the .env file automatically:

from simple_email_gw.config import get_config

config = get_config()  # Automatically loads .env if present

Provider-Specific Settings¶

Gmail¶

EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=587
# Use an app-specific password, not your regular password
EMAIL_PASSWORD=xxxx-xxxx-xxxx-xxxx

iCloud¶

EMAIL_IMAP_HOST=imap.mail.me.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_HOST=smtp.mail.me.com
EMAIL_SMTP_PORT=587
EMAIL_USERNAME=your-icloud-email@icloud.com
EMAIL_PASSWORD=app-specific-password

Outlook/Office 365¶

EMAIL_IMAP_HOST=outlook.office365.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_HOST=smtp.office365.com
EMAIL_SMTP_PORT=587

Security Best Practices¶

Never commit credentials to version control
Use app-specific passwords when available
Use OAuth2 for providers that support it
Configure recipient whitelists to prevent data exfiltration
Set appropriate rate limits for your use case
Use a dedicated workspace for attachment downloads