herfy-email 0.1.0

Provider-abstracted email SDK for Herfy applications — send via Control Center credentials

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

pip install herfy-email[mailgun]

Usage

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="[e-mail]", 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="[e-mail]", 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

EMAIL_PROVIDER=mailgun
MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxxxxx
MAILGUN_DOMAIN=mg.herfy.com
MAILGUN_FROM_ADDRESS=[e-mail]