sdk-example

Keplars Python SDK Example

FastAPI demo showing idiomatic Python integration with the Keplars email SDK using both sync (Keplars) and async (AsyncKeplars) clients.

Requirements

• Python 3.8+
• A Keplars API key (get one here)

SDK Dependency

Install via pip:

pip install keplars

Then import and initialise:

from keplars import Keplars

keplars = Keplars(api_key="kms_your_api_key")

response = keplars.emails.send_instant(
    to="user@example.com",
    from_email="hello@yourdomain.com",
    subject="Hello!",
    html="<h1>Hello World</h1>",
)

Or use the async client:

from keplars import AsyncKeplars

async with AsyncKeplars(api_key="kms_your_api_key") as keplars:
    response = await keplars.emails.send_instant(
        to="user@example.com",
        from_email="hello@yourdomain.com",
        subject="Hello!",
        html="<h1>Hello World</h1>",
    )

Setup

cd sdk-example
cp .env.example .env

Set your API key in .env:

KEPLARS_API_KEY=kms_your_key_here

Install dependencies and run:

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8080

Server starts on http://localhost:8080.

Project Structure

sdk-example/
├── app/
│   ├── main.py              Entry point, FastAPI setup, Keplars wiring
│   └── routes/
│       ├── emails.py        Transactional + marketing endpoints
│       └── webhooks.py      Webhook receiver with signature verification
└── tests/
    └── test_email_routes.py

API Endpoints

Transactional Emails

Send welcome email:

curl -X POST http://localhost:8080/api/emails/welcome \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","firstName":"Jane"}'

Send OTP:

curl -X POST http://localhost:8080/api/emails/otp \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","otp":"847291"}'

Send password reset:

curl -X POST http://localhost:8080/api/emails/password-reset \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","resetLink":"https://yourapp.com/reset/abc123"}'

Send order confirmation:

curl -X POST http://localhost:8080/api/emails/order-confirmation \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","orderId":"ORD-9921","total":"$49.99"}'

Marketing Emails

Send newsletter (bulk):

curl -X POST http://localhost:8080/api/emails/newsletter \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["a@example.com","b@example.com"],
    "subject": "Our Monthly Update",
    "html": "<h1>Hello!</h1><p>Here is what is new this month.</p>"
  }'

Schedule newsletter:

curl -X POST http://localhost:8080/api/emails/newsletter/schedule \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["a@example.com","b@example.com"],
    "subject": "Weekend Deal",
    "html": "<h1>Special offer inside!</h1>",
    "scheduledFor": "2025-06-01T09:00:00Z"
  }'

Webhooks

Point your Keplars webhook URL to:

POST https://your-server.com/webhooks/keplars

Set the webhook secret in .env:

KEPLARS_WEBHOOK_SECRET=your_webhook_secret

Supported events: email.delivered, email.bounced, email.complained, email.opened, email.clicked, email.failed

Priority Queue

Use Case	Method	Priority
OTP, auth codes	send_instant	Instant (fastest)
Password reset, alerts	send_high	High
Welcome, notifications	send	Async
Newsletters, campaigns	send_bulk	Bulk

Running Tests

pip install -r requirements-dev.txt
pytest

Related Examples

• Node.js Examples — Express + async/await
• Kotlin Examples — Ktor + coroutines
• Java Examples — Spring Boot + CompletableFuture

License

MIT