MailBridge: Modern Form Submission & Email Response System

MailBridge is a powerful, secure, and efficient system designed to handle form submissions and automate email responses. Built with FastAPI and Docker, it provides a robust solution for managing contact forms and email communications on your website. With dual email delivery options (iCloud SMTP and Postmark API), MailBridge offers flexibility and reliability for your email needs.

Key Features

FastAPI Backend: High-performance asynchronous API for handling form submissions
Docker Containerization: Easy deployment and scaling
Redis Integration: Rate limiting and caching for enhanced security
Dual Email Delivery: Choose between iCloud SMTP and Postmark API
Dynamic Mode Switching: Seamlessly switch between email delivery methods
Automated Email Responses: Customizable templates for different types of inquiries
Form Submission Handling: Secure processing of contact form data
Rate Limiting: Protection against spam and abuse
CORS Support: Secure cross-origin resource sharing
Gzip Compression: Optimized data transfer
CAPTCHA Support: Optional integration with reCAPTCHA or hCaptcha
Multiple Email Alias Support: Manage multiple email addresses from a single instance
Pushover Notifications: Real-time alerts for form submissions and email responses

Email Delivery Options

MailBridge supports two email delivery methods, allowing you to choose the best option for your needs:

iCloud SMTP Mode

Traditional SMTP delivery using iCloud’s infrastructure
Sent folder archiving - all emails are automatically saved to your iCloud Sent Messages folder
Reliable delivery with iCloud’s established email infrastructure
No additional service costs - uses your existing iCloud account

Postmark Mode

API-based delivery using Postmark’s transactional email service
Enhanced deliverability with dedicated IP addresses and reputation management
Detailed analytics and delivery tracking
Professional email infrastructure designed for transactional emails
Identical email content - same formatting and templates as iCloud mode

How It Works

MailBridge operates as a two-part system:

Form Handler: Processes incoming form submissions from your website
Email Daemon: Monitors and responds to incoming emails

Form Submission Flow

User submits a contact form on your website
Form data is securely sent to MailBridge’s API
MailBridge validates the submission and applies rate limiting
The submission is processed and sent via the configured email delivery method
A copy is saved to the Sent Messages folder (iCloud mode) or tracked via Postmark

Email Response Flow

MailBridge monitors specified email accounts
When a new email arrives, it’s processed based on predefined rules
Appropriate response templates are selected based on the email subject
Automated responses are sent using the configured delivery method
All responses are logged and tracked appropriately

Setup and Configuration

Prerequisites

Docker and Docker Compose
iCloud account with app-specific password
(Optional) Postmark account for enhanced email delivery
Domain with SSL certificate
(Optional) CAPTCHA service (reCAPTCHA or hCaptcha)
(Optional) Pushover account for notifications

Configuration Files

config.yml: Defines form settings, allowed domains, and global mode
responses.json: Contains email templates and response configurations
compose.yaml: Docker services configuration
.env: Environment variables (iCloud and Postmark credentials)

Environment Variables

# iCloud settings (required)
ICLOUD_EMAIL=[email protected]
ICLOUD_PASSWORD=your_app_specific_password

# Postmark settings (optional, for Postmark mode)
POSTMARK_API_KEY=your_postmark_api_key
POSTMARK_SENDER_EMAIL=[email protected]

# Pushover settings (optional, for notifications)
PUSHOVER_ENABLED=true
PUSHOVER_USER_KEY=your_pushover_user_key
PUSHOVER_API_TOKEN=your_pushover_api_token

# Instance configuration
INSTANCE_EMAILS=[email protected],[email protected]

Mode Switching

MailBridge includes a built-in mode switcher that allows you to easily change between iCloud and Postmark email delivery:

Switching Modes

# Switch to iCloud mode (default)
python switch_mode.py icloud

# Switch to Postmark mode
python switch_mode.py postmark

# Check current mode
python switch_mode.py status

Mode Configuration

The mode is stored in your config.yml file:

global:
    mode: iCloud  # or "postmark"

Mode-Specific Features

iCloud Mode:

Traditional SMTP delivery
Automatic sent folder archiving
No additional service costs
Standard email delivery

Postmark Mode:

API-based delivery
Enhanced deliverability
Detailed analytics and tracking
Professional email infrastructure
Same email content and formatting as iCloud

Website Integration

Basic Form Implementation

<form id="contact" method="post">
    <input type="text" name="name" required placeholder="Your Name">
    <input type="email" name="email" required placeholder="Your Email">
    <input type="text" name="subject" required placeholder="Subject">
    <textarea name="content" required placeholder="Your Message"></textarea>
    <button type="submit">Send Message</button>
</form>

CAPTCHA Integration

MailBridge supports both reCAPTCHA and hCaptcha for additional security. Configuration is done through the config.yml file:

forms:
    your-form-key:
        captcha:
            provider: "recaptcha"  # or "hcaptcha"
            secret_key: "your-secret-key-here"

Security Features

Rate Limiting: Prevents abuse and spam
CORS Protection: Only allows requests from specified domains
CAPTCHA Support: Optional bot protection
Secure SMTP: Uses STARTTLS for email transmission
API Security: Postmark API uses secure token-based authentication
Environment Variables: Sensitive data is stored securely

Deployment

MailBridge is designed to be deployed using Docker Compose:

docker-compose up -d

The system consists of two main services:

Redis for caching and rate limiting
MailBridge for form handling and email processing

Monitoring and Maintenance

Real-time Logs: Available through Docker with detailed mode information
Email Delivery Status: Logged for both iCloud and Postmark modes
Failed Submissions: Tracked and reported
System Health: Monitored through Docker
Pushover Notifications: Real-time alerts for form submissions and email responses
Mode Switching: Clear logging when switching between delivery methods

Best Practices

Choose the Right Mode: Use iCloud for simple setups, Postmark for enhanced deliverability
Regular Updates: Keep Docker images and dependencies updated
Backup Configuration: Regularly backup your configuration files
Monitor Logs: Check logs for any issues or unusual activity
Rate Limit Tuning: Adjust rate limits based on your traffic
Template Updates: Keep email templates current and professional
Credential Management: Use environment variables for all sensitive data
Mode Testing: Test both modes to ensure proper configuration

Troubleshooting

Common issues and solutions:

Email Delivery Problems