Metadata-Version: 2.4
Name: multi-email
Version: 1.0.0
Summary: Multi-provider email sending with automatic fallback (GSMTP, Brevo, GWORK, SES, Mailgun, Mailjet, MailerSend, Resend, SendGrid)
License: MIT
Project-URL: Homepage, https://github.com/yourusername/multi-email
Project-URL: Issues, https://github.com/yourusername/multi-email/issues
Keywords: email,smtp,brevo,sendgrid,mailgun,mailjet,ses,resend,mailersend,fallback
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# multi-email

**Multi-provider email sending with automatic fallback.**

Configure a priority-ordered list of email providers. The library tries each one in order — on any failure (auth error, rate limit, network issue) it automatically moves to the next. First success wins.

```
pip install multi-email
```

---

## Supported providers

| Method       | Free limit       | Gmail sender | Notes                          |
|--------------|-----------------|--------------|--------------------------------|
| GSMTP        | 500/day          | ✅ Yes        | Local dev only (cloud-blocked) |
| BREVO        | 300/day          | ✅ Yes*       | Best free option               |
| GWORK        | ~2000/day        | ✅ Yes        | Paid ~Rs125/mo                 |
| SES          | —                | ✅ Yes*       | $0.10/1000 — cheapest at scale |
| MAILGUN      | 100/day          | ❌ No         | Needs own domain               |
| MAILJET      | 200/day          | ✅ Yes*       | EU/GDPR friendly               |
| MAILERSEND   | 3000/month       | ❌ No         | Best free volume               |
| RESEND       | 3000/month       | ❌ No         | Simple API                     |
| SENDGRID     | 100/day          | ❌ No         | Industry standard              |

\* Verify your Gmail in their dashboard first.

---

## Quick start

### Option 1 — Environment variable

Set `EMAIL_SEND_METHODS` to a JSON array (ideal for Railway, Heroku, Docker, etc.):

```bash
export EMAIL_SEND_METHODS='[
  {"method":"BREVO",    "api_key":"xkeysib-AAA", "from_email":"you@gmail.com",        "from_name":"MyApp"},
  {"method":"BREVO",    "api_key":"xkeysib-BBB", "from_email":"you@gmail.com",        "from_name":"MyApp"},
  {"method":"MAILJET",  "api_key":"abc123",       "api_secret":"xyz789",              "from_email":"you@gmail.com", "from_name":"MyApp"},
  {"method":"SES",      "user":"AKIAXXXXXXXX",    "password":"xxxx",                  "from_email":"you@gmail.com", "from_name":"MyApp", "region":"ap-south-1"},
  {"method":"RESEND",   "api_key":"re_xxx",       "from_email":"noreply@yourdomain.com","from_name":"MyApp"},
  {"method":"SENDGRID", "api_key":"SG.xxx",       "from_email":"noreply@yourdomain.com","from_name":"MyApp"}
]'
```

```python
from multi_email import send_email

ok = send_email("user@example.com", "Welcome!", "<h1>Hello!</h1>")
```

### Option 2 — Pass methods directly

```python
from multi_email import send_email

methods = [
    {"method": "BREVO",   "api_key": "xkeysib-AAA", "from_email": "you@gmail.com", "from_name": "MyApp"},
    {"method": "RESEND",  "api_key": "re_xxx",       "from_email": "noreply@yourdomain.com", "from_name": "MyApp"},
]
ok = send_email("user@example.com", "Welcome!", "<h1>Hello!</h1>", methods=methods)
```

### Test mode (no real sends)

```python
send_email("user@example.com", "Test", "<p>hi</p>", test_mode=True)
```

---

## API

### `send_email(to, subject, html_body, *, methods=None, test_mode=False) -> bool`

| Parameter   | Type            | Description                                               |
|-------------|-----------------|-----------------------------------------------------------|
| `to`        | `str`           | Recipient email address                                   |
| `subject`   | `str`           | Email subject line                                        |
| `html_body` | `str`           | Full HTML body                                            |
| `methods`   | `list \| None`  | Override the env-var provider list for this call          |
| `test_mode` | `bool`          | If `True`, log the email and return `True` without sending|

Returns `True` on first successful send, `False` only if every provider fails.

### `load_methods(env_var="EMAIL_SEND_METHODS") -> list`

Re-read and parse the method list from an environment variable. Useful if you update the env var at runtime.

---

## Provider setup

<details>
<summary><strong>BREVO</strong> (best free option — 300/day, Gmail sender)</summary>

1. Sign up at [brevo.com](https://brevo.com)
2. Senders & IPs → Add sender → verify your Gmail address
3. API Keys → Generate a new API key

```json
{"method":"BREVO", "api_key":"xkeysib-...", "from_email":"you@gmail.com", "from_name":"MyApp"}
```
Add multiple BREVO entries with different accounts to stack free limits.
</details>

<details>
<summary><strong>GSMTP</strong> (Gmail personal SMTP — local dev only)</summary>

1. Google Account → Security → 2-Step Verification → App Passwords → create one
2. Use it as the `password` (not your real Gmail password)

```json
{"method":"GSMTP", "user":"you@gmail.com", "password":"xxxx xxxx xxxx xxxx", "from_email":"you@gmail.com", "from_name":"MyApp"}
```
⚠️ Blocked on Railway, Heroku, and most cloud hosts.
</details>

<details>
<summary><strong>GWORK</strong> (Google Workspace — ~2000/day)</summary>

1. [workspace.google.com](https://workspace.google.com) → buy plan → create a user
2. Use that user's email + password

```json
{"method":"GWORK", "user":"support@yourdomain.com", "password":"xxxxx", "from_email":"support@yourdomain.com", "from_name":"MyApp"}
```
</details>

<details>
<summary><strong>SES</strong> (Amazon SES — cheapest at scale)</summary>

1. AWS Console → SES → Verified Identities → verify your sender email
2. Request Production Access (sandbox → production, ~24 hr approval)
3. SES → SMTP Settings → Create SMTP Credentials → copy user + password

```json
{"method":"SES", "user":"AKIAXXXXXXXXXXXXXXXX", "password":"xxxx", "from_email":"support@yourdomain.com", "from_name":"MyApp", "region":"ap-south-1"}
```
Regions: `ap-south-1` (Mumbai), `us-east-1`, `ap-southeast-1`
</details>

<details>
<summary><strong>MAILGUN</strong> (100/day free)</summary>

1. [mailgun.com](https://mailgun.com) → Sending → Domains → Add domain → configure DNS
2. API Keys → create private key

```json
{"method":"MAILGUN", "api_key":"key-xxx", "domain":"mg.yourdomain.com", "from_email":"noreply@yourdomain.com", "from_name":"MyApp"}
```
EU accounts: add `"base_url": "https://api.eu.mailgun.net"`
</details>

<details>
<summary><strong>MAILJET</strong> (200/day free, EU-friendly)</summary>

1. [mailjet.com](https://mailjet.com) → free account
2. Senders & Domains → Add sender → verify your Gmail
3. API Keys → copy **both** API Key and Secret Key

```json
{"method":"MAILJET", "api_key":"abc123", "api_secret":"xyz789", "from_email":"you@gmail.com", "from_name":"MyApp"}
```
</details>

<details>
<summary><strong>MAILERSEND</strong> (3000/month free)</summary>

1. [mailersend.com](https://mailersend.com) → free account
2. Domains → Add domain → verify DNS
3. API Tokens → Generate token

```json
{"method":"MAILERSEND", "api_key":"mlsn.xxx", "from_email":"noreply@yourdomain.com", "from_name":"MyApp"}
```
</details>

<details>
<summary><strong>RESEND</strong> (3000/month free)</summary>

1. [resend.com](https://resend.com) → add domain → verify DNS
2. API Keys → create key

```json
{"method":"RESEND", "api_key":"re_xxx", "from_email":"noreply@yourdomain.com", "from_name":"MyApp"}
```
</details>

<details>
<summary><strong>SENDGRID</strong> (100/day free)</summary>

1. [sendgrid.com](https://sendgrid.com) → Settings → Sender Authentication → verify domain
2. API Keys → create key with Mail Send permission

```json
{"method":"SENDGRID", "api_key":"SG.xxx", "from_email":"noreply@yourdomain.com", "from_name":"MyApp"}
```
</details>

---

## License

MIT
