Installation — mailbridge

Requirements

Python 3.10+

Minimum supported version

No hard dependencies

Core package installs nothing extra — only what you need per provider

Email account or API key

From whichever provider you choose to use

Install

If you don't have uv installed yet:

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

bash

uv add mailbridge

bash

pip install mailbridge

bash

poetry add mailbridge

This installs the core package. SMTP, Postmark, Mailgun and Brevo are included and ready to use — no additional steps needed.

Optional Dependencies

Install only what you need. Async support, SendGrid, and Amazon SES each require an optional extra:

Async support

optional

bash

uv add "mailbridge[async]"

bash

pip install "mailbridge[async]"

Installs aiohttp + aiosmtplib — native non-blocking I/O for all providers

SendGrid

optional

bash

uv add "mailbridge[sendgrid]"

bash

pip install "mailbridge[sendgrid]"

Installs sendgrid SDK

Amazon SES

optional

bash

uv add "mailbridge[ses]"

bash

pip install "mailbridge[ses]"

Installs boto3 (AWS SDK)

Everything

all

bash

uv add "mailbridge[all]"

bash

pip install "mailbridge[all]"

Installs aiohttp + aiosmtplib + sendgrid + boto3

What needs an extra?

Feature / Provider	Extra	Installs
Async support (`AsyncMailBridge`)	`[async]`	`aiohttp`, `aiosmtplib`
SendGrid	`[sendgrid]`	`sendgrid`
Amazon SES	`[ses]`	`boto3`
Postmark	✓ Included — no extra needed
Mailgun	✓ Included — no extra needed
Brevo	✓ Included — no extra needed
SMTP	✓ Included — uses Python stdlib

AsyncMailBridge works without the [async] extra — it falls back to a thread pool executor. Install [async] to get native non-blocking I/O via aiohttp and aiosmtplib.

Verify Installation

Confirm MailBridge is installed correctly:

bash

python -c "from mailbridge import MailBridge; print('MailBridge OK')"

Or check the installed version:

bash

pip show mailbridge

If you're using an optional provider, verify that its SDK is also available:

bash

# SendGrid
python -c "import sendgrid; print('sendgrid OK')"

# Amazon SES
python -c "import boto3; print('boto3 OK')"

Which provider should I choose?

Not sure where to start? Here's a quick guide:

Getting started / development

Use SMTP with your Gmail or Outlook account. No sign-up, no API keys — works immediately with credentials you already have.

bash

pip install mailbridge   # SMTP works out of the box

Production transactional email

Use Postmark or SendGrid. Both have excellent deliverability, template support, and are easy to set up. Postmark requires no extra install.

bash

pip install mailbridge               # Postmark included
pip install mailbridge[sendgrid]     # SendGrid needs the SDK

Already on AWS

Use Amazon SES. If you're running on EC2 or Lambda, you can use IAM roles — no API keys needed in your code at all.

bash

pip install mailbridge[ses]

High volume / newsletters

Use SendGrid, Mailgun, or Brevo — all support native batch APIs for sending thousands of emails efficiently.

bash

pip install mailbridge[sendgrid]     # SendGrid
pip install mailbridge               # Mailgun or Brevo — included

You can switch providers at any time — the rest of your code stays the same. So starting with SMTP for development and switching to SendGrid for production is completely straightforward.

Next: Quick Start