Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DataTalksClub/datamailer/llms.txt

Use this file to discover all available pages before exploring further.

Transactional templates are the building blocks for one-to-one triggered emails — password resets, welcome messages, verification links, and similar system-initiated sends. Each template belongs to a client and is identified by a unique key that client applications pass in API calls. The template catalog in the operator UI lists all active transactional templates with their context requirements and recent send activity.

​
The Template Catalog

Browse all transactional templates at /templates/. The catalog can be filtered by client using the dropdown at the top of the page. Each row in the catalog shows:
  • Key — the slug used by client applications in API calls (e.g. registration-welcome)
  • Name — a human-readable label for the operator UI
  • Client — the client this template belongs to
  • Required context — the named variables that must be provided in every send request
  • Send counts — queued, sent, skipped, and failed message totals

​
Template Fields

When creating or editing a template (via the Django admin), the following fields are available:
FieldTypeNotes
keySlugUnique within a client. Passed by client apps in POST /api/transactional/send.
nameStringHuman-readable label shown in the catalog.
descriptionTextOptional notes for your team.
subjectStringEmail subject line. Supports Django template syntax.
html_bodyTextFull HTML body. Supports Django template syntax.
text_bodyTextPlain-text fallback. Supports Django template syntax.
required_contextJSON listNamed variables that must be present in every API send request.
example_contextJSON dictExample values used for preview rendering on the template detail page.
is_transactionalBooleanMust be true for the template to appear in the catalog and accept API sends.
is_activeBooleanInactive templates are not accessible via the API.
clientFKThe client this template belongs to.

​
Template Rendering

Template bodies and subjects are rendered using Django’s template engine (Template + Context), which supports the full Django template language. Variables are injected from the context object provided in the API request. 
Account verified — welcome to {{ product_name }}!

​
Required Context and Validation

The required_context field is a JSON list of variable names (or objects with name and description keys) that must be present and non-empty in every API send request. Each entry can be a bare string or a dictionary: 
[
  "first_name",
  { "name": "login_url", "description": "Full URL to the login page" },
  "product_name"
]
When a client application calls POST /api/transactional/send, the catalog service validates that every required context key is present and non-empty in the context payload. If any key is missing or blank, the request is rejected with a validation error listing the offending fields (context.<name>: required).

​
Template Detail

The template detail page at /templates/{id}/ shows:
  • Full template content (subject, HTML body, text body)
  • A rendered preview using example_context values
  • The list of required context variables with optional descriptions
  • The last 10 transactional messages sent using this template, with status badges and metadata

​
Common Template Key Examples

Template keys are set by staff in the operator UI. They must exactly match the template_key value passed in API calls. By convention, keys are lowercase, hyphen-separated slugs:
KeyTypical use
registration-welcomeSent after a new user registers
email-verificationContains a link for the user to verify their address
password-resetContains a one-time password reset link
order-confirmationE-commerce order receipt
The API returns a 404 response if the requested template_key does not exist for the authenticated client, or if the matching template has is_active = false. Ensure the key is created in the operator UI and is_active is checked before deploying client code that references it.
Template keys are owned by staff operators, not by client developers. If a client application needs a new template, a staff member must create it in the operator UI (or Django admin) first, then share the exact key string with the client team. Mismatches between the key in the codebase and the key in the database are the most common cause of 404 errors on the transactional send endpoint.

Build docs developers (and LLMs) love

Get started for freeTalk to us