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.
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.
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 }) 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() 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
contextGeneratorsMapof classes with agenerate()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.
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_notificationcreateNotificationcall. - 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
NotificationTypeConfigties 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.oneIndexedtells you which.
| Python | TypeScript | |
|---|---|---|
| Install | pip install vintasend | npm install vintasend |
| Service | NotificationService() | VintaSendFactory().create() |
| Context | @register_context("x") | contextGeneratorsMap |
| Create | create_notification() | createNotification() |
| Drain | send_pending_notifications() | sendPendingNotifications() |
| Query | filter_notifications() | filterNotifications() |
| Capabilities | fields.sentAtRange | fields.sentAtRange |
| First page | page=1 | page = 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
- vintasend-djangoDjango ORM, plus an email adapter and a template renderer
- vintasend-sqlalchemySQLAlchemy, sync and async sessions
Adapters
- vintasend-fastapi-mailAsyncIO email through FastAPI-Mail
- vintasend-flask-mailEmail through Flask-Mail
- vintasend-twilioSMS through Twilio, sync and AsyncIO
- vintasend-celeryDeferred delivery on sync backends
Renderers and more
- vintasend-jinjaJinja2 templates
- vintasend-aws-s3-attachmentsAttachments in S3 via boto3
- vintasend-managed-templatesStore-backed, versioned templates
- vintasend-django-templates-managerDjango storage for managed templates
Backends
- vintasend-prismaPrisma Client, typed from your generated client
- vintasend-medplumFHIR resources on Medplum; also an adapter, attachments and a logger
Adapters
- vintasend-nodemailerEmail through any Nodemailer transport
- vintasend-sendgridSendGrid, with attachments
- vintasend-mailgunMailgun, with attachments
- vintasend-twilioSMS through Twilio
Renderers and more
- vintasend-liquidjsLiquidJS, safe for templates edited outside the repo
- vintasend-react-emailReact Email, TSX templates included
- vintasend-pugPug, for templates in your repository
- vintasend-aws-s3-attachmentsS3 and S3-compatible stores
- vintasend-winstonWinston logger
Full list, with install commands and typical combinations, on the implementations page.
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.