Managed templates · Python and TypeScript

Change the copy without a deploy. Keep every version.

A file-based renderer makes every template edit a deploy, and an edit changes what every notification renders, past and future. Managed templates live in a data store instead: someone who is not a developer edits them, every edit is a new version, a version is published on purpose, and a notification can be pinned to the exact one it should render.

Stores Django ORMMedplum (FHIR)your own backend Engines Django templatesJinja2LiquidJSin-memory maps
VintaSendNotificationsTemplates
Templates
welcomedraftv4
welcomeactivev3
base-emailactivev2
footeractivev7
invoice-readyinactivev1
SourceCompositionHistoryTags
{% managed_extends "base-email" version=2 %} {% managed_block header %}<h1>Welcome!</h1>{% managed_endblock %} <p>Hi {{ name }}, welcome aboard.</p> subject {% managed_extends "base-email" %}Welcome aboard tags onboarding · email activated 2026-11-02 by hugo@example.com
New versionPreviewDeactivateallowedTransitions: inactive, archived

How it works

Wrap the renderer you have. Reference a key instead of a path.

A managed-template renderer composes another renderer rather than replacing it: it fetches the stored template and hands the engine its source. The notification service does not change. The only difference a caller sees is that body_templatebodyTemplate names a template key.

STEP 01

Write a draft

A template has a key, a body, a subject and an optional preheader, tags and a tenant. Its first version is created in draft. Nothing sends it yet.

>>> templates.create_template(ManagedTemplateCreateInput(key="welcome", …))
> await templates.createTemplate({ key: 'welcome', … })
STEP 02

Preview, then activate

Render the draft against a context you type, check the composed output, and publish it. Every status change is written to the audit trail with who made it.

>>> templates.activate("welcome", changed_by="hugo@example.com")
> await templates.activate('welcome', { changedBy: 'hugo@example.com' })
STEP 03

Sends pick the newest active version

An unpinned send renders the highest-numbered active version, never a draft. A pinned one renders the version it was pinned to, and records the version that actually rendered either way.

>>> notification.used_template_version  # 3
> notification.usedTemplateVersion  // 3

Wiring it up

Three objects, and the notification service stays as it was.

  • A manager backend stores the versions, the status history and the tags. The Django one ships models, migrations and an admin.The Medplum one stores them as FHIR MessageDefinition resources.
  • A managed-template renderer wraps any existing email or SMSemail renderer and feeds it stored source instead of a path.
  • A managed-template service is what editors and APIs call: create, version, publish, tag, filter, preview.
  • Fallbacks let the application send a key before anyone has written its template: register a default per key and sends use it until a version is activated.
  • Wrap an engine that cannot run code. Liquid evaluates expressions and filters only. Pug compiles a template to JavaScript, so keep Pug for templates in your repository.
notifications.pynotifications.ts
from vintasend_managed_templates.managed_template_renderer import ManagedTemplateEmailRenderer
from vintasend_managed_templates.managed_template_service import ManagedTemplateService
from vintasend_django_templates_manager.django_templates_manager import DjangoTemplateManager

manager_backend = DjangoTemplateManager()                       # where the versions live
renderer = ManagedTemplateEmailRenderer(manager_backend, inner_renderer)   # wraps any email renderer
templates = ManagedTemplateService(manager_backend, renderer)   # create, version, publish, tag

# The notification service is unchanged; only the renderer is wrapped.
service = NotificationService(
    notification_adapters=[DjangoEmailNotificationAdapter(renderer, notification_backend)],
    notification_backend=notification_backend,
)

service.create_notification(
    user_id=user.id,
    notification_type="EMAIL",
    title="Welcome",
    body_template="welcome",          # a managed template key, not a file path
    context_name="welcome_context",
    context_kwargs={"user_id": user.id},
    pin_template_versions=True,       # record the version that is current right now
)
import { LiquidEmailTemplateRendererFactory } from 'vintasend-liquidjs';
import { ManagedTemplateEmailRenderer, ManagedTemplateService } from 'vintasend-managed-templates';
import { MedplumTemplateManagerBackend } from 'vintasend-medplum-template-manager';

const managerBackend = new MedplumTemplateManagerBackend(medplum);   // where the versions live
const liquid = new LiquidEmailTemplateRendererFactory<Config>().create({
  renderLimit: 1_000,   // an edited template cannot make a send hang
  strictFilters: true,
});
const renderer = new ManagedTemplateEmailRenderer<Config>(managerBackend, liquid);
const templates = new ManagedTemplateService<Config>(managerBackend, renderer);

// The notification service is unchanged; only the renderer is wrapped.
await vintasend.createNotification(
  {
    userId: user.id,
    notificationType: 'EMAIL',
    title: 'Welcome',
    bodyTemplate: 'welcome',          // a managed template key, not a file path
    contextName: 'welcomeContext',
    contextParameters: { userId: user.id },
    sendAfter: null, subjectTemplate: null, extraParams: null,
  },
  { pinTemplateVersions: true },      // record the version that is current right now
);
DRAFT ACTIVE INACTIVE ARCHIVED activate deactivate activate archive · terminal every move is written to the status history, with changed_by

Lifecycle

Versioned, never edited in place. Published on purpose.

An update copies the latest version forward and applies what changed, so a published version's body can never change under a notification that already referenced it. Status moves follow a transition table, and anything else is refused.

  • Several versions can be active. Activating v2 while v3 is active does not change what is sent: an unpinned send renders the highest-numbered active one.
  • Only a never-published version can be deleted. A version that was ever active may be pinned by a notification, so it is archived instead. Status history is never deleted, and a deleted version's number is never reused.
  • Tags edit in place. Tags are how a template is found, not part of what it renders, so retagging does not spawn a version. Slugs are derived by shared rules, so every store agrees on what a label becomes.
  • Allowed transitions travel with the payload. A UI enables buttons from allowedTransitions instead of discovering the rules by catching errors.

Composition

Bases, blocks and includes, resolved before the engine runs.

Django's extends and Jinja's include hand a name to a loader, and a loader reads files. Stored templates reach the engine as source, so those tags have nothing to load. Managed templates bring their own tags, resolve them against the store, and hand the engine one flat string with no managed_ tag left in it.

SourceComposition
base-email v2 <html><body> {% managed_block header %}<h1>Acme</h1>{% managed_endblock %} {% managed_children %} {% managed_include "footer" %} </body></html> welcome v3 {% managed_extends "base-email" version=2 %} {% managed_block header %}<h1>Welcome!</h1>{% managed_endblock %} <p>Hi {{ name }}, welcome aboard.</p> what the engine receives for welcome <html><body> <h1>Welcome!</h1> <p>Hi {{ name }}, welcome aboard.</p> <p>Acme Inc · unsubscribe</p> </body></html>
TagWhat it does
managed_extends "key"This template is a child of key. Pin the parent with version=2.
managed_childrenIn a base: where the child's content goes.
managed_block nameA named region a child may replace. Blocks may nest.
managed_superInside a child's block: the content it is overriding.
managed_include "key"Splice another template in, composed in full first. Pins the same way.
  • Abstract templates. A template with a managed_children hole, or blocks without a parent, is a base to build on. The flag is derived from the source on every write, so "the templates I can send" is a filter, not a parse.
  • Pin the parent too. A notification pinned to v3 of welcome renders v3 of welcome, but an unpinned base still resolves to today's. Name the version on the reference when a child must keep composing against an exact parent.
  • Failures surface at edit time. Unknown tags, missing references, cycles and runaway depth are the package's own errors, raised by validation before a send ever hits them.
  • One tag language, both ecosystems. The Python and TypeScript packages agree on the tags, the slug rules and the filter vocabulary, so a store written by one renders in the other.

The stack

Four packages, each on its own release cycle.

The seam and the service, a store for it, an API over it, and a dashboard on the API. Install what you need; the lower layers work without the upper ones.

vintasend-managed-templates

The BaseTemplateManagerBackend seam, ManagedTemplateService, the email and SMS wrapping renderers, composition, tags and lifecycle rules. Storage-agnostic. GitHub ↗

vintasend-django-templates-manager

DjangoTemplateManager, the models behind it, and an admin that enforces the same delete rules as the service. GitHub ↗

vintasend-templates-management-api

A Django + django-ninja REST API over a ManagedTemplateService. Mount it in your project or run it alone. Its openapi.yaml is generated from the routes and tested against them. GitHub ↗

templates-management-dashboard

A Next.js UI over that contract, with the data layer in a core package. Shared with the TypeScript ecosystem. GitHub ↗

vintasend-managed-templates

The template manager seam, ManagedTemplateService, the wrapping renderer, composition, tags and lifecycle rules. Storage-agnostic. GitHub ↗

vintasend-medplum-template-manager

Stores managed templates as FHIR MessageDefinition resources, next to the notifications that reference them. GitHub ↗

vintasend-templates-management-api

A REST API over a configured ManagedTemplateService. Mount it with createApp or run the command on its own. Shares its openapi.yaml byte for byte with the Python API. GitHub ↗

templates-management-dashboard

A Next.js UI over that contract, with the data layer in a core package. Shared with the Python ecosystem. GitHub ↗

The dashboard

A write tool for the people who own the copy.

Where the notifications dashboard is read-mostly, this one creates templates, versions them, moves them through the lifecycle, previews what they render to and manages the tags. It is a pure client of the templates API, with the key held in its own proxy route, and it is meant to be copied: the data layer is vintasend-templates-management-dashboard-core, the screens are one example in Tailwind and shadcn/ui.

  • Templates screen. One row per version, collapsed to each key's current version by default. Source and composition side by side, status history, every version the key has had.
  • Tags screen. Create, rename, archive, restore, delete. Renaming is flagged, because the slug is the identity the filters match on.
  • Ordering is gated, filtering is not. The two capability namespaces default in opposite directions, so a column only becomes sortable once the backend says so, and a filter control is not drawn when it cannot be honoured.
  • Three errors it understands. INVALID_STATUS_TRANSITION, TEMPLATE_COMPOSITION_ERROR and PREVIEW_UNAVAILABLE get their own UI instead of a generic failure.
openapi.yaml · /api/v1 · port 3334
GET/templatesone row per key by default
POST/templatesfirst version, in draft
POST/templates/{key}/versionsthe edit: a new version from the latest
GET/templates/{key}/compositionwhat the engine receives
POST/templates/{key}/previewrender against a supplied context
POST/templates/{key}/activatealso deactivate, archive, status
GET/templates/{key}/status-historythe audit trail
PUT/templates/{key}/tagsreplace one version's tags
DEL/templates/{key}/versions/{v}never-published only; 409 otherwise
GET/tagsplus create, rename, archive, restore, delete
GET/capabilitieswhat the backend can filter and sort by

Wrap the renderer. Move the templates. Nothing else changes.

The notification service, the adapters and the backend stay exactly as they are. A key replaces a path, and the copy stops being a deploy.