Genro Mail Proxy
  • Overview
    • High-level architecture
    • Request flow
    • Client synchronisation
    • Large file handling
    • Attachment caching
  • Features
    • Editions
    • Community Edition Features
    • Enterprise Edition Features
    • Message Management
    • Multi-Tenancy
    • Attachments
    • Priority & Scheduling
    • Rate Limiting
    • Retry & Resilience
    • SMTP Connections
    • Delivery & Reporting
    • Bounce Detection
    • Database & Persistence
    • Monitoring & Metrics
    • Concurrency & Performance
    • REST API
    • CLI Tool
    • Configuration
    • Security
    • PEC Support
    • Large File Offloading
  • Architecture Overview
    • Why Use an Email Proxy?
    • Architecture Pattern
      • Traditional Direct SMTP
      • Proxy-Based Architecture
    • Key Benefits
      • 1. Decoupling (Write vs Send Concern)
      • 2. Resilience and Reliability
      • 3. Performance Optimization
        • Connection Pooling
        • Async Processing
      • 4. Centralized Rate Limiting
      • 5. Monitoring and Observability
      • 6. Multi-Tenant Support
      • 7. Debugging and Troubleshooting
      • 8. Attachment Handling
      • 9. Priority Queuing
      • 10. Scheduled Sending
    • Comparison Summary
    • When to Use This Architecture
    • Migration Path
    • Conclusion
  • Protocols and APIs
    • Authentication and base URL
    • REST command surface
    • Message batch payload
    • Attachment storage formats
    • Delivery report payload
    • Client synchronisation protocol
      • Sync request format
      • Sync response format
      • Do Not Disturb (Sync Scheduling)
      • Tenant Starvation Prevention
      • Accelerated sync loop
      • Client implementation example
    • Error handling
  • Installation
    • PyPI
    • Docker
    • Docker Compose with PostgreSQL
    • Docker Compose with SQLite
    • Local Development
    • Network Requirements
    • Kubernetes
      • ConfigMap and Secret
      • Deployment
      • Service
      • Ingress (optional)
      • PersistentVolumeClaim (SQLite only)
      • PostgreSQL with Helm (recommended)
      • Horizontal Pod Autoscaler (PostgreSQL only)
      • Apply all manifests
  • Network Requirements
    • Network Architecture
      • Network Flow Diagram
    • Connection Details
      • 1. your application → genro-mail-proxy (REST API)
      • 2. genro-mail-proxy → your application (Delivery Reports)
      • 3. genro-mail-proxy → SMTP Servers
    • Port Configuration
      • genro-mail-proxy Service Port
    • Deployment Scenarios
      • Scenario 1: Single Host (Development)
      • Scenario 2: Separate Hosts (Production)
      • Scenario 3: Kubernetes Cluster
    • Security Considerations
      • TLS/SSL Configuration
      • Authentication
      • Network Isolation
    • Troubleshooting
      • Connection Testing
      • Common Issues
    • Monitoring and Logging
    • Summary Checklist
    • See Also
  • Usage
    • Configuration
      • CLI Setup (recommended)
      • Environment Variables (Docker/Kubernetes)
      • Docker Workflow
      • API Token
      • Delivery Activity Logging
    • Interactive REPL
    • PostgreSQL Backend
    • Large File Handling
    • Proxy sync exchange
    • Endpoints
    • Test mode
    • REST Examples (curl)
    • Python (httpx)
  • CLI Reference
    • Global Commands
      • mail-proxy list
      • mail-proxy start <instance>
      • mail-proxy stop <instance>
      • mail-proxy restart <instance>
      • mail-proxy status <instance>
      • mail-proxy delete <instance>
    • Instance Commands
      • mail-proxy <instance> info
      • mail-proxy <instance> stats
      • mail-proxy <instance> token
      • mail-proxy <instance> connect
    • Tenant Commands
      • mail-proxy <instance> tenants list
      • mail-proxy <instance> tenants show <tenant_id>
      • mail-proxy <instance> tenants add
      • mail-proxy <instance> tenants update <tenant_id>
      • mail-proxy <instance> tenants delete <tenant_id>
    • Tenant-Scoped Commands
      • mail-proxy <instance> <tenant> info
      • mail-proxy <instance> <tenant> run-now
    • Account Commands
      • mail-proxy <instance> <tenant> accounts list
      • mail-proxy <instance> <tenant> accounts show <account_id>
      • mail-proxy <instance> <tenant> accounts add
      • mail-proxy <instance> <tenant> accounts delete <account_id>
    • Message Commands
      • mail-proxy <instance> <tenant> messages list
      • mail-proxy <instance> <tenant> send <file.eml>
    • REPL-Only Operations
    • Exit Codes
    • Environment Variables
    • Configuration Files
  • Attachments
    • Attachment specification
    • Fetch modes
      • endpoint mode
      • http_url mode
      • base64 mode
      • filesystem mode
    • Caching and deduplication
      • MD5 marker in filename (legacy)
      • content_md5 field (recommended)
      • Cache behavior
    • Large file handling
      • Installation
      • Configuration
      • Actions
      • Storage backends
      • Download URLs
    • Best practices
    • See also
  • Rate Limiting
    • How It Works
    • Configuration
    • Deferred Messages
    • Recommended Limits
    • Global vs Per-Instance Limits
    • Monitoring Rate Limits
    • Disabling Rate Limits
    • Best Practices
    • See Also
  • Priority Queuing
    • Priority Levels
    • How It Works
    • Setting Message Priority
    • Batch Default Priority
    • Use Cases
    • Instance Default Priority
    • Interaction with Rate Limiting
    • Monitoring Priority Distribution
    • Best Practices
    • See Also
  • Monitoring
    • Prometheus Metrics
      • Available Metrics
      • Sample Output
    • Prometheus Configuration
    • Grafana Dashboard
    • Alerting Rules
    • Health Endpoints
      • GET /health
      • GET /status
    • Kubernetes Probes
    • Docker Compose Health Check
    • Logging
      • Log Format
      • Structured Logging (JSON)
    • Best Practices
    • See Also
  • Example Client
    • Overview
    • Quick Start
      • Installation
      • Configuration
    • Usage Examples
      • Send Single Test Email
      • Send Multiple Test Emails
      • Custom Subject Line
      • View Message Statistics
      • List Pending Messages
    • Architecture
      • Integration Flow
      • Message States
      • Database Schema
    • Integration Pattern Explained
      • Why This Pattern?
      • Benefits
      • Performance Characteristics
    • Code Walkthrough
      • Step 1: Create Message Locally
      • Step 2: Submit to Mail Service
      • Step 3: Trigger Immediate Dispatch
      • Step 4: Receive Delivery Reports
    • API Reference
      • Endpoints
        • POST /send-test-email
        • GET /messages
        • GET /stats
        • POST /email/mailproxy/mp_endpoint/proxy_sync
    • Testing
      • End-to-End Test
      • Expected Timeline
    • Troubleshooting
      • Client Won’t Start
      • Mail Service Connection Refused
      • Authentication Failed
      • Messages Stuck in “submitted” State
    • Adapting for Your Application
    • Multi-tenant Integration
    • See Also
  • Integrations
    • Django Integration
      • When to use the proxy with Django
      • Comparison with Celery
      • Installation
      • Configuration
      • Client module
      • Usage in views
      • Receiving delivery reports
      • Serving attachments
      • URL configuration
      • Proxy tenant configuration
      • Celery comparison example
      • Tracking email status
    • Flask Integration
      • When to use the proxy with Flask
      • Comparison with Flask-Mail + Celery
      • Installation
      • Configuration
      • Client module
      • Flask application
      • Delivery reports endpoint
      • Flask-Mail comparison
      • Blueprint example
      • Proxy tenant configuration
    • Express.js Integration
      • When to use the proxy with Express
      • Comparison with Nodemailer + Bull
      • Installation
      • Configuration
      • Client module
      • Express application
      • Delivery reports endpoint
      • TypeScript version
      • Nodemailer comparison
      • Using native fetch (Node 18+)
      • Proxy tenant configuration
  • Multi-tenancy Architecture
    • Overview
    • Bidirectional Communication Flow
    • API Authentication Model
      • Token Types and Permissions
      • Authentication Flow
      • Automatic API Key Generation
      • Managing Tenant API Keys
      • Token Properties
      • Security Best Practices
    • Tenant Configuration
    • TenantAuth Configuration
    • Tenant Management API
    • Delivery Report Routing
    • Delivery Report Payload
    • Expected Response
      • Do Not Disturb Feature
    • Implementing the Tenant Endpoint
    • Configuration Example
    • Batch Suspension
      • Batch Code in Messages
      • Suspend/Activate API
      • Suspension Behavior
      • Complete Workflow Example
  • PEC Support (Posta Elettronica Certificata)
    • Overview
    • PEC Message Flow
    • PEC Receipt Types
    • PEC Account Configuration
    • Message Correlation
    • PEC Events
    • Timeout Detection
    • API Endpoints
    • Delivery Report Integration
      • Client implementation example for PEC
    • Italian PEC Providers
    • Best Practices
    • Complete Example
  • Security
    • Credential Encryption
      • How It Works
      • Encryption Details
      • Configuring the Encryption Key
      • Generating a Key
      • Docker Example
      • Kubernetes Example
      • Key Rotation
    • API Authentication
      • Token Types
      • Admin Token Configuration
      • Tenant Token Configuration
      • Token Storage
    • Tenant Isolation
      • Database-Level Isolation
      • API-Level Isolation
    • Network Security
      • TLS for SMTP
      • TLS for API
    • Security Best Practices
    • Audit Logging
  • API Reference
    • FastAPI
    • Core endpoints
    • Tenant management
    • Additional commands
    • Prometheus metrics
    • Outbound proxy sync
    • Client Callback Endpoints
      • Sync Endpoint (Required)
      • Attachment Endpoint (optional)
  • FAQ
    • General
    • Configuration
    • Messages and Delivery
    • Attachments
    • Multi-tenancy
    • Rate Limiting
    • Monitoring
    • Troubleshooting
    • Security
    • Licensing
    • Bounce Detection (Enterprise)
    • PEC Support (Enterprise)
  • Appendix: Endpoint Reference
    • Proxy Endpoints (Server)
    • Client Endpoints (Required)
      • Sync Endpoint Details
      • Attachment Endpoint Details
      • Configuration
  • Python Modules
    • Core Package (Apache 2.0)
      • Main Components
        • main()
        • MailProxy
        • MailProxyBase
        • CacheConfig
        • ClientSyncConfig
        • ConcurrencyConfig
        • ProxyConfig
        • QueueConfig
        • RetryConfig
        • TimingConfig
      • Interface Layer
        • create_app()
        • register_endpoint()
        • require_admin_token()
        • require_token()
        • verify_tenant_token()
        • register_endpoint()
        • add_connect_command()
        • add_stats_command()
        • add_send_command()
        • add_token_command()
        • add_run_now_command()
        • add_serve_command()
        • add_list_command()
        • add_stop_command()
        • add_restart_command()
        • add_use_command()
        • add_current_command()
        • resolve_context()
        • require_context()
        • resolve_instance()
        • require_instance()
        • BaseEndpoint
        • EndpointDispatcher
        • POST()
      • Entities
        • name
        • pkey
        • AccountsTable
        • AccountEndpoint
        • TenantsTable
        • AuthMethod
        • LargeFileAction
        • TenantEndpoint
        • get_tenant_attachment_url()
        • get_tenant_sync_url()
        • MessagesTable
        • AttachmentPayload
        • FetchMode
        • MessageEndpoint
        • MessageStatus
        • MessageEventTable
        • InstanceTable
        • InstanceEndpoint
        • CommandLogTable
        • CommandLogEndpoint
        • StoragesTable
        • StorageEndpoint
      • SMTP Components
        • SmtpSender
        • AccountConfigurationError
        • AttachmentTooLargeError
        • SMTPPool
        • PooledConnection
        • Base64Fetcher
        • StorageFetcher
        • HttpFetcher
        • AttachmentManager
        • MemoryCache
        • DiskCache
        • TieredCache
        • RetryStrategy
        • RateLimiter
      • Reporting
        • ClientReporter
    • Enterprise Package (BSL 1.1)
      • Proxy Extension
        • MailProxy_EE
        • is_ee_enabled()
        • MailProxy_EE
      • Bounce Detection
        • BounceInfo
        • BounceParser
        • BounceConfig
        • BounceReceiver
      • PEC Support
        • PecReceiptInfo
        • PecReceiptParser
        • PecReceiver
      • IMAP Client
        • IMAPClient
        • IMAPMessage
      • Large File Storage
        • LargeFileStorageError
        • StorageNotConfiguredError
        • UploadError
        • LargeFileStorage
      • Enterprise Entities
        • AccountsTable_EE
        • AccountEndpoint_EE
        • TenantsTable_EE
        • TenantEndpoint_EE
        • InstanceTable_EE
        • InstanceEndpoint_EE
        • MessagesTable_EE
        • StorageNode_EE
    • SQL Package
      • SqlDb
        • SqlDb.__init__()
        • SqlDb.encryption_key
        • SqlDb.connect()
        • SqlDb.close()
        • SqlDb.add_table()
        • SqlDb.table()
        • SqlDb.check_structure()
        • SqlDb.execute()
        • SqlDb.fetch_one()
        • SqlDb.fetch_all()
        • SqlDb.commit()
        • SqlDb.rollback()
      • Table
        • Table.name
        • Table.pkey
        • Table.db
        • Table.columns
        • Table.name
        • Table.pkey
        • Table.__init__()
        • Table.configure()
        • Table.pkey_value()
        • Table.new_pkey_value()
        • Table.trigger_on_inserting()
        • Table.trigger_on_inserted()
        • Table.trigger_on_updating()
        • Table.trigger_on_updated()
        • Table.trigger_on_deleting()
        • Table.trigger_on_deleted()
        • Table.create_table_sql()
        • Table.create_schema()
        • Table.add_column_if_missing()
        • Table.sync_schema()
        • Table.insert()
        • Table.select()
        • Table.select_one()
        • Table.select_for_update()
        • Table.record()
        • Table.update()
        • Table.update_batch()
        • Table.update_batch_raw()
        • Table.delete()
        • Table.exists()
        • Table.count()
        • Table.fetch_one()
        • Table.fetch_all()
        • Table.execute()
      • RecordUpdater
        • RecordUpdater.__init__()
        • RecordUpdater.record
        • RecordUpdater.old_record
        • RecordUpdater.where
      • Column
        • Column.__init__()
        • Column.relation()
        • Column.to_sql()
      • Columns
        • Columns.__init__()
        • Columns.column()
        • Columns.items()
        • Columns.keys()
        • Columns.values()
        • Columns.get()
        • Columns.json_columns()
        • Columns.encrypted_columns()
      • Database Adapters
        • DbAdapter
        • SqliteAdapter
        • PostgresAdapter
    • Storage Package
      • StorageManager
        • StorageManager.__init__()
        • StorageManager.configure()
        • StorageManager.register()
        • StorageManager.get_mount_names()
        • StorageManager.has_mount()
        • StorageManager.get_mount_config()
        • StorageManager.node()
      • StorageNode
        • StorageNode.__init__()
        • StorageNode.basename
        • StorageNode.stem
        • StorageNode.suffix
        • StorageNode.fullpath
        • StorageNode.path
        • StorageNode.mount_name
        • StorageNode.parent
        • StorageNode.mimetype
        • StorageNode.child()
        • StorageNode.exists()
        • StorageNode.is_file()
        • StorageNode.is_dir()
        • StorageNode.size()
        • StorageNode.mtime()
        • StorageNode.read_bytes()
        • StorageNode.read_text()
        • StorageNode.write_bytes()
        • StorageNode.write_text()
        • StorageNode.delete()
        • StorageNode.mkdir()
        • StorageNode.children()
        • StorageNode.md5hash()
        • StorageNode.url()
        • StorageNode.verify_url_token()
      • StorageError
    • Tools Package
      • EncryptionError
      • EncryptionKeyNotConfigured
      • decrypt_value()
      • decrypt_value_with_key()
      • encrypt_value()
      • encrypt_value_with_key()
      • generate_key()
      • is_encrypted()
      • set_key_for_testing()
      • MailMetrics
        • MailMetrics.registry
        • MailMetrics.sent
        • MailMetrics.errors
        • MailMetrics.deferred
        • MailMetrics.rate_limited
        • MailMetrics.pending
        • MailMetrics.__init__()
        • MailMetrics.inc_sent()
        • MailMetrics.inc_error()
        • MailMetrics.inc_deferred()
        • MailMetrics.inc_rate_limited()
        • MailMetrics.set_pending()
        • MailMetrics.init_account()
        • MailMetrics.generate_latest()
      • REPLWrapper
        • REPLWrapper.__init__()
        • REPLWrapper.__dir__()
      • is_reserved()
      • repl_wrap()
      • reserved()
  • Contributing
  • Fullstack Integration Testing
    • Overview
    • Test Structure
    • Quick Start
      • Prerequisites
      • Running Tests
    • Infrastructure Services
      • Mailpit (SMTP/IMAP)
      • Minio (S3-Compatible Storage)
      • Mail Proxy
    • Test Fixtures
    • Bounce Injection
    • CSV-Driven Tests
    • Environment Variables
    • Test Markers
    • Troubleshooting
      • Services Not Starting
      • Tests Skipped
      • Minio Not Accessible
      • Rebuild After Code Changes
    • Writing New Tests
    • See Also
  • Fullstack Test Reference
    • 00_core - Core Functionality
      • TestHealthAndBasics
      • Docker Integration Tests
      • TestInfrastructureCheck
      • TestTenantManagement
      • TestAccountManagement
    • 10_messaging - Message Handling
      • TestValidation
      • TestBasicMessageDispatch
      • TestMessageManagement
      • TestBatchOperations
      • TestBatchCodeOperations
      • TestPriorityHandling
    • 20_attachments - Attachment Handling
      • TestAttachmentsBase64
      • TestHttpAttachmentFetch
      • TestLargeFileStorage
      • TestTenantLargeFileConfigApi
      • TestUnicodeEncoding
    • 30_delivery - Delivery Handling
      • TestSmtpErrorHandling
      • TestRetryLogic
      • TestDeliveryReports
    • 40_operations - Operations
      • TestMetrics
      • TestServiceControl
      • TestExtendedSuspendActivate
      • TestAccountRateLimiting
      • TestRetentionCleanup
    • 50_security - Security
      • TestTenantIsolation
      • TestSecurityInputSanitization
      • TestPerTenantApiKeys
    • 60_imap - Bounce Detection
      • TestBounceDetection
      • TestBounceEndToEnd
      • TestBounceLivePolling
    • Test Flow Diagrams
      • Basic Message Flow
      • Bounce Detection Flow
    • See Also
Genro Mail Proxy
  • Search

© Copyright 2025, Softwell S.r.l..

Built with Sphinx using a theme provided by Read the Docs.