Tools · notifications dashboard and API

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.

Built on Next.jsTanStack QueryOpenAPIDjango + django-ninjaHonoClerk / Auth0
VintaSendNotificationsTemplatesacme-prod
status = FAILED ×type = EMAIL ×sentAt ≥ 24h ×+ tenant+ template sort sentAt ↓
idkindtemplaterecipientstatussent
8f3c…a21userinvoice_readyuser 4821FAILED09:00
21d0…7beone-offappointment_sms+1 555 …FAILED08:41
c04e…f90userpassword_resetuser 917SENT08:12
77ab…310userweekly_digestuser 4821PENDING—
e1c2…9d4userwelcomeuser 5102READyesterday
8f3c…a21 · rendered at c1f9e4 · template v3 PreviewResendCancel page 1 · hasMore

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.

Browser vintasend-dashboard components + dashboard-core signed in with Clerk or Auth0 Proxy route /api/vintasend, server side checks the session adds the API key: the only place it exists VintaSend API Django + django-ninja Hono · createApp() openapi.yaml is the contract same bytes in both languages Your service backend adapters renderer HTTPS + session HTTPS + Authorization: Bearer $VINTASEND_API_KEY in process

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-api command runs a server configured from environment variables, behind one shared key, on port 3333.
  • Bring your own authentication. Set VINTASEND_API_AUTHENTICATOR to a callable and the key is not checked.Pass an authenticate function to createApp and the key is not checked.
  • Conventions a client can rely on. Pages are 1-indexed on the wire, hasMore instead of a total count, ISO-8601 UTC timestamps, and one error envelope with a machine-readable code.
  • Read a replica. VINTASEND_BACKEND_IDENTIFIER points the API at a non-primary backendA backend identifier points the API at a non-primary backend of a multi-backend service.
settings.py · urls.pyroute.ts
# 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
openapi.yaml · /api/v1
GET/healthliveness probe, unauthenticated
GET/api/v1/capabilitiesfilter and order capabilities of the configured backend
GET/api/v1/notificationslist with filters, ordering and pagination
GET/api/v1/notifications/pendingawaiting send
GET/api/v1/notifications/futurescheduled for later
GET/api/v1/notifications/one-offsent to an address or number, not a user
GET/api/v1/notifications/{id}one notification, context payloads included
GET/api/v1/notifications/{id}/previewtemplates rendered at the notification's commit
POST/api/v1/notifications/{id}/resendclone and send now
POST/api/v1/notifications/{id}/cancelstop a pending one
inbox.tsx
'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-typescript and openapi-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.

STEP 01

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
STEP 02

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=…
STEP 03

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

The sibling for templates

The same split, for the templates themselves.

Where this dashboard is read-mostly, the templates management dashboard is a write tool: create templates, version them, move them through draft, active, inactive and archived, tag them and preview what they render to. Same architecture, same server-side key, its own API and its own core package.

VintaSendNotificationsTemplates
keyversionstatustags
welcomev4draftonboarding
welcomev3activeonboarding
base-emailv2activelayout
invoice-readyv7activebilling
New versionPreviewActivate v4

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.