norialabs-notify

Python client for Noria Notify: transactional email and SMS through one internal service. Sync and async, typed, no dependency beyond httpx.

pip install norialabs-notify      # or: uv add norialabs-notify

from noria_notify import Notify

notify = Notify(api_key=os.environ["NORIA_NOTIFY_KEY"], base_url="https://notify.noria.co.ke")

notify.emails.send({
    "from_": "Noria <hello@norialabs.com>",
    "to": "founder@example.com",
    "subject": "Welcome",
    "html": "<p>Hi there</p>",
})

notify.sms.send({"from_": "NORIA", "to": "0712345678", "text": "Your code is 482913"})

from_ carries the trailing underscore because from is a keyword; it is sent as from. Every other field is exactly what goes on the wire.

Async

The same surface, for FastAPI and anything else on asyncio.

from noria_notify import AsyncNotify

async with AsyncNotify(api_key=key, base_url=url) as notify:
    await notify.emails.send({"to": "a@example.com", "subject": "Hi", "text": "there"})
    await notify.sms.send({"to": "0712345678", "text": "Your code is 482913"})

Sending

notify.emails.send(email, idempotency_key=f"signin-{token.id}")
notify.emails.send_batch([email, email])

notify.sms.send(message, idempotency_key=f"otp-{token.id}")
notify.sms.send_batch([message, message])

Both also take template and variables instead of a body, scheduled_at for a future send and tags. Email adds attachments as base64, plus cc, bcc, reply_to and headers.

An SMS takes one recipient, because one row carries one provider message id and that is what a delivery receipt is matched against. Use send_batch for many.

Reading what was sent

One ledger covers every channel:

notify.messages.list(channel="sms", status="failed", limit=50)
notify.messages.get(message_id)
notify.messages.events(message_id)
notify.messages.cancel(message_id)
notify.messages.requeue(message_id)

Domains, senders, templates, suppressions, webhooks

notify.domains.create("norialabs.com")          # returns the DNS records to publish
notify.senders.create("NORIA")                  # registered pending approval
notify.templates.upsert("welcome", subject="Hi {{name}}", html=html)
notify.templates.upsert("otp", channel="sms", text="Code {{code}}")
notify.suppressions.add("0712345678", channel="sms", reason="unsubscribe")
notify.is_suppressed("0712345678", "sms")
notify.webhooks.create("https://app.example.com/hooks/notify", ["delivered", "bounced"])

A slug is unique per channel, so an otp email template and an otp SMS template can coexist.

Errors

Failures raise NotifyError with code, status, details and request_id, plus suppressed, over_quota and retryable for the common branches. The client retries 408, 429 and 5xx with backoff and never retries quota_exceeded, suppressed_recipient, domain_not_verified, sender_not_approved or message_too_long.

try:
    notify.sms.send(message)
except NotifyError as error:
    if error.suppressed:
        return
    raise

Webhooks

from noria_notify import verify_webhook

event = verify_webhook(
    payload=await request.body(),
    signature=request.headers["noria-signature"],
    secret=os.environ["NORIA_NOTIFY_WEBHOOK_SECRET"],
)

HMAC-SHA256 over <timestamp>.<raw body>, compared in constant time, with a five minute tolerance against replay. event["data"]["channel"] says which channel the event came from.

Tests

uv sync
uv run pytest
uv run ruff check src tests