Integrations

Send and verify email events in FastAPI.

The notix-sdk client is synchronous, so declare the routes that use it with plain def: FastAPI runs those in its thread pool and the event loop stays free. The webhook route reads the raw request body so the signature check sees exactly what Notix signed.

The send

Send an email from FastAPI.

main.py

import os
from fastapi import FastAPI
from notix import Notix

app = FastAPI()
notix = Notix(os.environ["NOTIX_API_KEY"])

@app.post("/orders/{order_id}/receipt")
def send_receipt(order_id: int, to: str):
    resp, _ = notix.emails.send(
        payload={
            "from": "Acme <receipts@acme.com>",
            "to": to,
            "subject": "Your receipt",
            "html": "<p>Thanks for your order.</p>",
        },
        options={"idempotency_key": f"order-{order_id}-receipt"},
    )
    return {"id": resp["emailId"]}

The from address must be on a domain you have verified in Notix. Step by step: the Python quickstart and the longer guide to sending email from FastAPI.

Environment

One API key, kept on the server.

Create an API key on the API keys page of the Notix console and store it as NOTIX_API_KEY in the process environment. Read it only in code that runs on the server, never in anything shipped to a browser.

A Send only key is enough for code that only sends: if it leaks, it cannot read your contacts or delete a domain.

.env

NOTIX_API_KEY=notix_xxxxxxxxxxxx
NOTIX_WEBHOOK_SECRET=whsec_xxxxxxxxxxxx

Webhooks

Verify delivery events over the raw body.

Notix signs every webhook call with the webhook's signing secret: an HMAC-SHA256 of the X-Notix-Timestamp header, a dot and the raw body, sent in X-Notix-Signature. The SDKs check the signature and refuse a call more than 5 minutes old.

Pass the request body as bytes, before any JSON parsing: the signature covers the exact bytes Notix sent. A bad call raises WebhookVerificationError; answer 400.

main.py

from fastapi import HTTPException, Request
from notix import WebhookVerificationError

webhooks = notix.webhooks(os.environ["NOTIX_WEBHOOK_SECRET"])

@app.post("/webhooks/notix")
async def notix_webhook(request: Request):
    try:
        event = webhooks.construct_event(await request.body(), headers=request.headers)
    except WebhookVerificationError:
        raise HTTPException(status_code=400, detail="invalid signature")
    return {"received": event["type"]}

FAQ

Questions, answered.

Is the Python SDK async?

No, notix-sdk makes blocking calls. Declare the routes that send with def rather than async def, and FastAPI runs them in a worker thread instead of blocking the event loop.

What if the same request runs twice?

Send an Idempotency-Key header (idempotencyKey in notix-js) with a value that names the thing being sent, such as order-4471-receipt. A repeat with the same key and body returns the first result and sends nothing new; the same key with a different body is refused with 409.

Why is my send refused with a from-address error?

The from address must be on a domain you have verified in Notix. Add the domain in the console, publish the DNS records it shows, and wait for verification; until then, sends from that domain are refused.

The free plan does not ask for a card.

Guides