Open source · MIT · Python 3.10 to 3.14Node.js 20+, strictly typed

Every notification is a record. Rendered the moment it sends.

VintaSend stores each email, SMS, push and in-app notification before delivery, generates its data when it is actually sent, and delivers it through the database, template engine and provider you already run. One design, in Python and TypeScript. You are reading the Python version.Python and TypeScript. You are reading the TypeScript version.

Quick start GitHub ↗ GitHub ↗
Ships with DjangoSQLAlchemyFastAPI-MailFlask-MailCeleryTwilioJinja2S3
Ships with PrismaMedplumNodemailerSendGridMailgunTwilioLiquidJSReact EmailS3
pythontypescriptbilling/notifications.pybilling/notifications.ts
from vintasend.services.notification_service import NotificationService, register_context
from vintasend.constants import NotificationTypes

service = NotificationService()  # backend, adapters and renderer come from settings


@register_context("invoice_ready")
def invoice_ready(invoice_id: int):
    invoice = Invoice.objects.get(pk=invoice_id)  # runs when the email is sent
    return {"first_name": invoice.customer.first_name, "total": invoice.total}


service.create_notification(
    user_id=invoice.customer_id,
    notification_type=NotificationTypes.EMAIL,
    title="Invoice ready",
    body_template="billing/invoice_ready.html",
    subject_template="billing/invoice_ready_subject.txt",
    context_name="invoice_ready",
    context_kwargs={"invoice_id": invoice.id},
    send_after=invoice.due_at - timedelta(days=3),  # a row now, an email later
)
import { VintaSendFactory, type ContextGenerator } from 'vintasend';

class InvoiceReady implements ContextGenerator<{ invoiceId: number }> {
  async generate({ invoiceId }: { invoiceId: number }) {
    const invoice = await getInvoice(invoiceId); // runs when the email is sent
    return { firstName: invoice.customer.firstName, total: invoice.total };
  }
}

const contextGeneratorsMap = { invoiceReady: new InvoiceReady() } as const;

const vintasend = new VintaSendFactory<NotificationTypeConfig>().create({
  adapters: [emailAdapter], backend, logger, contextGeneratorsMap,
});

await vintasend.createNotification({
  userId: invoice.customerId,
  notificationType: 'EMAIL',
  title: 'Invoice ready',
  bodyTemplate: 'billing/invoice-ready.liquid',
  subjectTemplate: 'billing/invoice-ready-subject.liquid',
  contextName: 'invoiceReady',
  contextParameters: { invoiceId: invoice.id },
  sendAfter: addDays(invoice.dueAt, -3), // a row now, an email later
  extraParams: null,
});

How it works

Create a row. Send it when it is due. Keep the trail.

Nothing in VintaSend is fire-and-forget. A notification is persisted first, rendered at send time from data generated at send time, and left behind as a record you can query, resend and cancel.

STEP 01

Create a record

The service writes a row with status PENDING_SEND, the template names, the name of the function that will produce the data, its arguments, and when to send. No body is rendered yet.

>>> service.create_notification(..., send_after=next_monday)
> await vintasend.createNotification({ ..., sendAfter })
STEP 02

Send when due

Immediately, or when your cron drains the pending ones. The context generator runs now, so a reminder written last week renders this week's data. The renderer builds the body; the adapter delivers it.

$ celery beat → periodic_send_pending_notifications()
$ cron → await vintasend.sendPendingNotifications()
STEP 03

Keep the trail

The row becomes SENT or FAILED, with the timestamp, the context that was used, the template version that rendered and the git commit that sent it. Filter it, resend it, cancel it, from code or a dashboard.

>>> service.resend_notification(notification.id)
> await vintasend.resendNotification(notification.id)

Context at send time

Schedule the notification, not the data.

A notification stores a context name and the arguments to call it with, never the rendered data. The generator behind that name runs the moment the notification is sent, so a scheduled message always carries current information, and a template edit applies to everything still pending.

  • One decorator. @register_context("name") puts a sync or async function in the registry.
  • One map. A contextGeneratorsMap of classes with a generate() method, typed end to end.
  • Stored on send. The context that actually rendered is kept with the record, so a resend can reuse it instead of regenerating.
  • Nothing to serialize. Only the name and plain arguments travel through the queue, which is what makes background sending and replication safe.
notification · 8f3c…a21
status "SENT" # was PENDING_SEND until monday
notification_type "EMAIL"
title "Invoice ready" # for the audit trail
body_template "billing/invoice_ready" # a path, or a managed key
context_name "invoice_ready" # looked up at send time
context_kwargs {"invoice_id": 4821}
context_used {"first_name": "Ada", …} # what actually rendered
send_after 2026-11-09T09:00:00Z
sent_at 2026-11-09T09:00:14Z
used_template_version 3 # pinned, or whatever was current
git_commit_sha "c1f9e4…" # the revision that sent it
attachments [invoice-4821.pdf] # deduplicated by checksum
Your app create_notification() createNotification() NotificationService records · schedules · sends context registry inside sync and AsyncIO twins VintaSendFactory<Config> Backend store and query Renderer template + context Adapter email · SMS · push · in-app required · one each optional · off until configured Attachments Queue Replication Git SHA Logger

Architecture

Three seams you implement. Four you can leave unset.

The core defines the interfaces and the orchestration and ships none of the integrations. A backend persists and queries, a template renderer turns a template plus context into a body, an adapter delivers it. Each is a small base class with a working fake, and each is swapped without touching the code that creates notifications.

  • Pick per seam. Django ORM today, a faster store after the first million rows, same create_notificationcreateNotification call.
  • Optional seams gate features. No attachment manager, no attachments. No queue, no background sending. Nothing fails silently where it matters.
  • Versioned contract. A new abstract method on a seam is a minor release with a backwards-compatibility note, so downstream packages are never surprised.
  • Settings or code. Inject an instance, a dotted import string, or a NOTIFICATION_* setting read from Django, Flask, env vars or a config object.
  • Typed end to end. One NotificationTypeConfig ties the context map and id types through every factory.

Backend required

Persist, query and update notifications. Reports which filters, lookups and sort fields it supports so a UI can grey out the rest.

Adapter required

Deliver a rendered notification over one channel. Returns the render so the service can record which template version went out.

Template renderer required

Template plus context in, subject and body out. File-based, or wrapped by a managed-template renderer that reads from a store.

Attachment manager optional

Stores the bytes behind an attachment. The backend only keeps a checksum-indexed record and a join row.

Queue service optional

Enqueues a notification id for a worker to deliver. The worker rebuilds the service from a factory and reloads the real record.

Replication queue optional

Takes replica writes off the request path when a service runs more than one backend.

Git commit SHA provider optional

Returns the running revision so every sent notification records which code sent it.

AsyncIO twins python

Every seam except the renderer has an AsyncIO base class, and AsyncIONotificationService drives them with the same API, awaited.

Logger required

Receives structured LogMessages built from ids, counts and labels, never free text, so logs stay free of personal data.

What comes with the record

Because every notification is a row, the rest follows.

Scheduling, auditing, retries, dashboards and migrations are what you get when delivery is a state transition on a stored record rather than a side effect in a request handler.

Scheduling

Set send_aftersendAfter and the row waits. One periodic call drains everything that is due, safely re-runnable.

Attachments

Files from paths, buffers, streams or stored references, deduplicated by checksum, reusable by id, stored by a pluggable manager such as S3.

One-off notifications

Send to an email address or phone number that has no user record, with the recipient validated before anything is persisted.

In-app notifications

Unread listing, counts and idempotent bulk read-marking scoped to a user, so one user can never mark another's as read.

In-app notifications

Unread listing and read marking on the same records as every other channel, with only SENT and READ ever exposed to the user.

Filtering and dashboards

A JSON-friendly filter grammar with and / or / not, date ranges, string lookups, stable pagination and a capability report per backend.

Resend and cancel

Resend clones the record and leaves the original untouched, optionally with the exact context it rendered with. Cancel stops a pending one.

Background sending

An adapter opts in, the request enqueues only an id, and a worker delivers with the real record and its attachments reloaded from the backend.

Multiple backends

A primary plus replicas, replicated inline or through a queue, with sync verification, per-backend health and a copy-only migration between stores.

Template versions

Pin a notification to a template version, record the version that actually rendered, and keep templates in a database with a draft-to-archived lifecycle.

Git commit tracking

Each sent notification records the 40-character revision that delivered it, resolved at send time and never allowed to block a send.

Historical rendering

Render a notification against the template content it had at the time, from its stored context, for a preview or an audit, without sending anything.

Sync and AsyncIO

Two services with the same API. FastAPI gets await all the way down; Django and Flask stay synchronous.

Strict typing

Context names and parameters are checked against your generator map at compile time, and the Prisma backend infers its types from your generated client.

Python and TypeScript

Siblings, not ports. One contract across both.

Both libraries share the seams, the five statuses, the filter vocabulary and its capability keys, the managed-template tag language, and the OpenAPI contract the dashboard speaks. Names follow each language's conventions, and the few places the ecosystems differ are documented rather than papered over.

  • One dashboard for both. A Django service and a Node service can report to the same UI through the same API contract.
  • Shared template store. Managed templates written by one library render in the other: same tags, same slug rules, same lifecycle.
  • Read, don't assume. Python backends page from 1, TypeScript backends from 0, and pagination.oneIndexed tells you which.
same idea, each language's spelling
PythonTypeScript
Installpip install vintasendnpm install vintasend
ServiceNotificationService()VintaSendFactory().create()
Context@register_context("x")contextGeneratorsMap
Createcreate_notification()createNotification()
Drainsend_pending_notifications()sendPendingNotifications()
Queryfilter_notifications()filterNotifications()
Capabilitiesfields.sentAtRangefields.sentAtRange
First pagepage=1page = 0

Ecosystem

Official implementations for the stack you already run.

Every package implements one or more seams and is released on its own cycle. Pick one per required seam, add the optional ones you need, or start from the implementation template to write your own.

Backends

Adapters

Renderers and more

Backends

Adapters

Renderers and more

Full list, with install commands and typical combinations, on the implementations page.

Need a UI on top?

A dashboard that works against either library.

The notifications API (Django + django-ninjaTypeScript) exposes a configured service over HTTP behind an API key, and the Next.js dashboard browses, previews, resends and cancels through that contract alone. Both language APIs ship the same openapi.yaml byte for byte, and a second API plus dashboard does the same for managed templates.

dashboard · notifications
filter status in (FAILED) · sent_at last 24h
──────────────────────────────────────────
8f3c…a21 EMAIL invoice_ready tenant=acme FAILED [resend]
21d0…7be SMS appointment tenant=acme FAILED [resend]
c04e…f90 EMAIL password_reset tenant=beta SENT [preview]
──────────────────────────────────────────
capabilities fields.tenant ✓ orderBy.sentAt ✓ pagination.oneIndexed truefalse

Install the core. Pick your seams.

The core is tiny on purpose. Add one backend, one adapter and one renderer for your stack, and every feature above is already there.

Documentation PyPI npm