See every notification. Resend the ones that failed.
Every notification is a row, so a dashboard is a query away. The VintaSend dashboard lists, filters, previews, resends and cancels notifications through one HTTP contract, served by the Python API on Djangothe TypeScript API on Hono. It holds no database credentials and never sees the API key in the browser.
| id | kind | template | recipient | status | sent |
|---|---|---|---|---|---|
| 8f3c…a21 | user | invoice_ready | user 4821 | FAILED | 09:00 |
| 21d0…7be | one-off | appointment_sms | +1 555 … | FAILED | 08:41 |
| c04e…f90 | user | password_reset | user 917 | SENT | 08:12 |
| 77ab…310 | user | weekly_digest | user 4821 | PENDING | — |
| e1c2…9d4 | user | welcome | user 5102 | READ | yesterday |
How it fits
A UI, an API, and your service. The key stays on the server.
The dashboard is a pure client of the API. Everything that needs credentials, from database access to rendering a template at the commit that sent it, lives behind the API, next to the VintaSend service you already built to send notifications.
One contract, two servers
The Python and TypeScript APIs ship the same openapi.yaml byte for byte, so the dashboard is built once and does not know which library is behind it.
Nothing secret in the browser
The UI calls its own route, which checks the visitor's session and re-signs the request with the bearer key. Set a CORS origin only if you put per-user auth in front of the API first.
Capabilities, not assumptions
The UI reads the backend's capability report and greys out filters and sort fields it cannot honour, including which page number is the first.
What it does
The operations a support engineer actually needs.
Read-mostly by design. The two writes it offers, resend and cancel, are the two things you cannot do from a mail provider's log.
Browse and filter
Status, type, template, context name, tenant, date ranges and template versions, with ordering by any sortable field. Filters live in the URL, so a view is shareable and survives a reload.
Users and one-offs together
Every row carries a kind of user or one-off, so notifications sent to an email address with no account sit in the same list, discriminated rather than sniffed.
Inspect the record
One notification with its stored context, the context it was created with, the adapter that delivered it, the git commit that sent it and the template version that rendered.
Preview what went out
Templates rendered at the notification's commit, fetched from the repository, or at the managed template version it used. A notification with no commit reports PREVIEW_UNAVAILABLE rather than a guess.
Resend
Clones the notification and sends now, leaving the original untouched. Reuse the exact context it rendered with, or regenerate it through the context registry.
Cancel
Stops a pending notification before its send time arrives. Everything already sent stays as the audit trail.
The API
Mount it in the app that already has your service.
The Python API is a Django app, vintasend_api.dashboard, built with django-ninja. Install it, include its URLs under a prefix, and point NOTIFICATION_SERVICE_FACTORY at the callable that builds your service. A FastAPI project storing notifications through SQLAlchemy is served the same way: the factory decides, the HTTP layer neither knows nor cares.
The TypeScript API is a Hono app returned by createApp. It takes a standard Request and returns a Response, so it mounts in a Next.js route handler, TanStack Start, behind Express, or anywhere that speaks fetch. Hand it the service you already built and your own check of who is calling.
- Or run it alone. The package ships a project that runs the API by itself, behind one shared key.The
vintasend-apicommand runs a server configured from environment variables, behind one shared key, on port 3333. - Bring your own authentication. Set
VINTASEND_API_AUTHENTICATORto a callable and the key is not checked.Pass anauthenticatefunction tocreateAppand the key is not checked. - Conventions a client can rely on. Pages are 1-indexed on the wire,
hasMoreinstead of a total count, ISO-8601 UTC timestamps, and one error envelope with a machine-readablecode. - Read a replica.
VINTASEND_BACKEND_IDENTIFIERpoints the API at a non-primary backendA backend identifier points the API at a non-primary backend of a multi-backend service.
# settings.py
INSTALLED_APPS = [
# ...
"vintasend_api.dashboard",
]
NOTIFICATION_SERVICE_FACTORY = "myproject.notifications.create_notification_service"
VINTASEND_API_KEY = os.environ["VINTASEND_API_KEY"] # or VINTASEND_API_AUTHENTICATOR
# urls.py
urlpatterns = [
# ...
path("notifications-api/", include("vintasend_api.dashboard.urls")),
]// app/api/notifications/[...path]/route.ts (Next.js), or any fetch-shaped server
import { createApp } from 'vintasend-api';
import { vintasend } from '@/notifications'; // the service you already built
const api = createApp({
service: vintasend,
authenticate: async (request) => { /* your own check of who is calling */ },
});
export const GET = (request: Request) => api.fetch(request);
export const POST = (request: Request) => api.fetch(request);
// or, on its own, behind one shared key:
// VINTASEND_API_KEY=… vintasend-api # port 3333'use client';
import { useFilteredNotifications, getApiErrorCode } from 'vintasend-dashboard-core';
import { useNextRouterAdapter } from 'vintasend-dashboard-core/next';
export function Inbox() {
const {
notifications, isLoading, error, // the list, from the generated client
filters, setFilter, clearFilters, // state that lives in the URL
page, hasNextPage, nextPage, setSort, // 1-indexed on the wire
} = useFilteredNotifications({ router: useNextRouterAdapter() });
// …render with your own components
} Your own UI
The dashboard is an example. The data layer is a package.
Everything that is not a component comes from vintasend-dashboard-core: a typed client generated from the contract, TanStack Query hooks over it, and filter state that lives in the URL. Want the same screens inside your admin app, in your design system, with your login? Install the core and replace the components, not the data layer.
- Typed from the contract.
openapi-typescriptandopenapi-fetch, so a field the API renames fails at compile time. - Filters in the URL. Illegal values are dropped or clamped, a changed filter resets to page 1, and the back button steps through views.
- Router adapters. Next.js app router, plain
window.history, or two members of your own for react-router and friends. - Three ways to hold the key. Through your own proxy route, with your app's session token, or server-side only.
Setup
Three steps from a service to a screen.
Run the API next to your service
Install the Django app, include its URLs, and point the factory setting at your service. Or run the bundled project on its own.
Mount createApp in your server with the service you already built, or run the standalone command behind one key.
$ pip install vintasend-api $ npm install vintasend-api vintasend Point the dashboard at it
Two variables, read on the dashboard's server side only. The key is the same one the API was started with.
VINTASEND_API_URL=http://localhost:3333 VINTASEND_API_KEY=…
Pick a login and start it
Set AUTH_PROVIDER to clerk or auth0 with that provider's keys. Route protection and the sign-in flow follow from it.
$ npm run dev # http://localhost:3000
Already sending with VintaSend? The dashboard is an afternoon.
The API mounts next to the service you have. The dashboard clones, takes two environment variables and a login provider, and runs.