Metadata-Version: 2.4
Name: herfy-email
Version: 1.0.0
Summary: Provider-abstracted email SDK for Herfy applications — send via Control Center credentials
Author: Herfy Development Team
License-Expression: MIT
Keywords: email,mailgun,sendgrid,herfy,control-center
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: mailgun
Requires-Dist: mailgun>=1.0.0; extra == "mailgun"
Provides-Extra: sendgrid
Requires-Dist: sendgrid>=6.0.0; extra == "sendgrid"
Provides-Extra: all
Requires-Dist: mailgun>=1.0.0; extra == "all"
Requires-Dist: sendgrid>=6.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: respx>=0.20.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"

# herfy-email

Provider-abstracted email SDK for Herfy applications. Send transactional email using only your Control Center `client_id` and `client_secret` — no email provider credentials in app config.

## Installation

```bash
pip install herfy-email[mailgun]
```

## Usage

```python
from herfy_email import HerfyEmailClient, AsyncHerfyEmailClient

# Sync
client = HerfyEmailClient.from_credentials(
    client_id="app_pettycash",
    client_secret="your_secret",
    control_center_url="https://cc.herfy.com",
)
client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")

# Async (FastAPI)
client = AsyncHerfyEmailClient.from_credentials(
    client_id="app_pettycash",
    client_secret="your_secret",
    control_center_url="https://cc.herfy.com",
)
await client.send(to="user@herfy.com", subject="Hello", html="<p>Hello</p>", text="Hello")

# From environment variables (CC_CLIENT_ID / AUTH_CLIENT_ID, CC_CLIENT_SECRET / AUTH_CLIENT_SECRET, CC_URL / CONTROL_CENTER_URL)
client = HerfyEmailClient.from_env()
```

## How it works

1. SDK authenticates with Control Center via `POST /api/app-auth/token` (cached, TTL 300s)
2. SDK fetches provider config from `GET /api/config/email` (cached for process lifetime)
3. SDK calls the configured provider (Mailgun, SendGrid, …) directly

Switching email providers requires only a Control Center env-var change — zero app changes.

## Provider support

| Provider | Extra |
|----------|-------|
| Mailgun  | `pip install herfy-email[mailgun]` |
| SendGrid | `pip install herfy-email[sendgrid]` |

## Control Center configuration

```env
EMAIL_PROVIDER=mailgun
MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxx
MAILGUN_DOMAIN=mg.herfy.com
MAILGUN_FROM_ADDRESS=noreply@herfy.com
```
