mailbridge 2.0.0

Unified Python email library with multi-provider support (SendGrid, SES, Postmark, Mailgun, Brevo, SMTP)

MailBridge 📧

Unified Python email library with multi-provider support

MailBridge is a flexible Python library for sending emails, allowing you to use multiple providers through a single, simple interface. It supports SMTP, SendGrid, Mailgun, Amazon SES, Postmark, and Brevo.

---

✨ Features

• 🎨 Template Support - Use dynamic templates with all major providers
• 📎 Attachment Support - Add file attachment in email message
• 📦 Bulk Sending - Send thousands of emails efficiently with native API optimization
• 🔧 Unified Interface - Same code works with any provider
• ✅ Fully Tested - 156 unit tests, 96% coverage
• 🚀 Production Ready - Battle-tested and reliable
• 📚 Great Documentation - Extensive examples and guides

---

📦 Installation

pip install mailbridge

Optional dependencies:

# For SendGrid
pip install mailbridge[sendgrid]

# For Amazon SES
pip install mailbridge[ses]

# For all providers
pip install mailbridge[all]

# SMTP and Postmark work out of the box

---

🚀 Quick Start

Basic Email

from mailbridge import MailBridge

# Initialize with your provider
mailer = MailBridge(provider='sendgrid', api_key='your-api-key')

# Send email
response = mailer.send(
    to='[e-mail]',
    subject='Hello from MailBridge!',
    body='<h1>It works!</h1><p>Email sent successfully.</p>'
)

print(f"Sent! Message ID: {response.message_id}")

Template Email

# Send template with dynamic data
response = mailer.send(
    to='[e-mail]',
    subject='',  # From template
    body='',     # From template
    template_id='welcome-template',
    template_data={
        'name': 'John Doe',
        'company': 'Acme Corp',
        'activation_link': 'https://...'
    }
)

Bulk Sending

from mailbridge import MailBridge, EmailMessageDto

messages = [
    EmailMessageDto(
        to='[e-mail]',
        subject='Welcome',
        body='<p>Welcome User 1!</p>'
    ),
    EmailMessageDto(
        to='[e-mail]',
        subject='Welcome',
        body='<p>Welcome User 2!</p>'
    ),
    # ... more messages
]

result = mailer.send_bulk(messages)
print(f"Sent: {result.successful}/{result.total}")

---

🎯 Supported Providers

Provider	Templates	Bulk API	Features
SendGrid	✅	✅ Native	Personalizations, tracking
Amazon SES	✅	✅ Native	50/call batching, config sets
Postmark	✅	✅ Native	Open/click tracking, streams
Mailgun	✅	✅ Native	Templates, tracking
Brevo	✅	✅ Native	Templates, SMS support
SMTP	❌	❌	Universal compatibility

---

📖 Provider Setup

SendGrid

from mailbridge import MailBridge

mailer = MailBridge(
    provider='sendgrid',
    api_key='SG.xxxxx',
    from_email='[e-mail]'
)

• Get API Key
• Documentation
• Examples

---

Amazon SES

mailer = MailBridge(
    provider='ses',
    aws_access_key_id='AKIAXXXX',
    aws_secret_access_key='xxxxx',
    region_name='us-east-1',
    from_email='[e-mail]'
)

# Or using IAM role (EC2/Lambda)
mailer = MailBridge(
    provider='ses',
    region_name='us-east-1',
    from_email='[e-mail]'
)

• SES Console
• Documentation
• Examples

Note: Email addresses must be verified in sandbox mode. Request production access to send to any email.

---

Postmark

mailer = MailBridge(
    provider='postmark',
    server_token='xxxxx-xxxxx',
    from_email='[e-mail]'
)

# With tracking
response = mailer.send(
    to='[e-mail]',
    subject='Tracked Email',
    body='<p>Click <a href="https://...">here</a></p>',
    track_opens=True,
    track_links='HtmlAndText'
)

• Get Token
• Documentation
• Examples

---

Mailgun

mailer = MailBridge(
    provider='mailgun',
    api_key='key-xxxxx',
    domain='mg.yourdomain.com',  # Required
    from_email='[e-mail]'
)

• Get API Key
• Documentation

Note: Uses same API as SendGrid. See SendGrid examples for usage patterns.

---

Brevo (Sendinblue)

mailer = MailBridge(
    provider='brevo',
    api_key='xkeysib-xxxxx',
    from_email='[e-mail]'
)

# Template ID is a number
mailer.send(
    to='[e-mail]',
    template_id=123,  # Not a string
    template_data={'name': 'John'}
)

• Get API Key
• Documentation

Note: Similar to SendGrid/Postmark. Template IDs are integers. See SendGrid examples for usage patterns.

---

SMTP (Gmail, Outlook, Custom)

# Gmail
mailer = MailBridge(
    provider='smtp',
    host='smtp.gmail.com',
    port=587,
    username='[e-mail]',
    password='app-password',  # Not your regular password!
    use_tls=True,
    from_email='[e-mail]'
)

# Outlook
mailer = MailBridge(
    provider='smtp',
    host='smtp.office365.com',
    port=587,
    username='[e-mail]',
    password='your-password',
    use_tls=True,
    from_email='[e-mail]'
)

# Custom server
mailer = MailBridge(
    provider='smtp',
    host='mail.yourdomain.com',
    port=465,
    username='user',
    password='pass',
    use_ssl=True,  # For port 465
    from_email='[e-mail]'
)

• Examples

Gmail: Use App Password (requires 2FA)

---

💡 Common Use Cases

Welcome Emails

mailer.send(
    to=new_user.email,
    template_id='welcome-email',
    template_data={
        'name': new_user.name,
        'activation_link': generate_activation_link(new_user)
    }
)

Password Reset

mailer.send(
    to=user.email,
    template_id='password-reset',
    template_data={
        'reset_link': generate_reset_link(user),
        'expiry_hours': 24
    }
)

Newsletters (Bulk)

from mailbridge import EmailMessageDto

subscribers = User.objects.filter(subscribed=True)

messages = [
    EmailMessageDto(
        to=sub.email,
        template_id='newsletter',
        template_data={
            'name': sub.name,
            'unsubscribe_link': generate_unsubscribe_link(sub)
        }
    )
    for sub in subscribers
]

result = mailer.send_bulk(messages)
print(f"Sent: {result.successful}/{result.total}")

Transactional Notifications

mailer.send(
    to=order.customer_email,
    template_id='order-confirmation',
    template_data={
        'order_number': order.id,
        'total': order.total,
        'items': order.items,
        'tracking_url': order.tracking_url
    }
)

---

🔧 Advanced Features

Attachments

from pathlib import Path

mailer.send(
    to='[e-mail]',
    subject='Your Invoice',
    body='<p>Invoice attached.</p>',
    attachments=[
        Path('invoice.pdf'),
        Path('receipt.pdf')
    ]
)

CC and BCC

mailer.send(
    to='[e-mail]',
    subject='Project Update',
    body='<p>Latest update...</p>',
    cc=['[e-mail]', '[e-mail]'],
    bcc=['[e-mail]']
)

Custom Headers and Tags

mailer.send(
    to='[e-mail]',
    subject='Campaign Email',
    body='<p>Special offer!</p>',
    headers={'X-Campaign-ID': 'summer-2024'},
    tags=['marketing', 'campaign']
)

Context Manager

with MailBridge(provider='smtp', host='...', port=587) as mailer:
    mailer.send(to='[e-mail]', subject='Test', body='...')
# Connection automatically closed

---

📊 Bulk Sending Performance

Provider Optimizations:

• SendGrid: Uses native batch API (up to 1000/call)
• SES: Auto-batches to 50 recipients per call
• Postmark: Uses batch API (up to 500/call)
• Mailgun: Native batch API
• Brevo: Native batch API
• SMTP: Reuses connection for multiple sends

Example:

# Send 1000 emails efficiently
messages = [
    EmailMessageDto(
        to=f'user{i}@example.com',
        template_id='campaign',
        template_data={'user_id': i}
    )
    for i in range(1000)
]

result = mailer.send_bulk(messages)
print(f"Sent {result.successful} in {result.total_time:.2f}s")

---

📚 Documentation & Examples

• Examples Directory - Complete examples for all providers
  • SendGrid Examples - Basic, template, bulk
  • SES Examples - AWS setup, templates, bulk
  • Postmark Examples - Tracking features
  • SMTP Examples - Gmail, Outlook, custom
• Test Suite - 156 unit tests, 96% coverage
• Changelog - Version history

---

🧪 Testing

MailBridge includes a comprehensive test suite:

# Clone repo
git clone https://github.com/radomirbrkovic/mailbridge
cd mailbridge

# Install dev dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/ -v

# With coverage
pytest tests/ --cov=mailbridge --cov-report=html

# Results: 156 tests, 96% coverage

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

# Setup development environment
git clone https://github.com/radomirbrkovic/mailbridge
cd mailbridge
pip install -e ".[dev]"

# Run tests
pytest

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

Built with ❤️ for developers who need reliable email delivery.

Credits:

• SendGrid Python SDK
• Boto3 (AWS SDK)
• Postmark API
• Python SMTP library

---

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---