Transactional email

Use the transactional endpoints when you want to send a saved template directly, and to manage those templates programmatically.

GET /v1/transactional lists available templates.
POST /v1/transactional/send renders and sends one template to one recipient.
POST /v1/transactional/create creates a new template.
GET /v1/transactional/{templateId} fetches a single template’s metadata.
PUT /v1/transactional/update updates an existing template.
POST /v1/transactional/delete deletes a template.
GET /v1/transactional/{templateId}/content/{locale} fetches a locale’s content tree.
PUT /v1/transactional/{templateId}/content/{locale} sets a locale’s content tree.

Throughout these endpoints, templateId is the workspace-unique slug ID (the id returned by the list endpoint), not the internal UUID.

Listing templates

GET /v1/transactional returns every active template in the workspace, including its rendered body and its variables:

curl https://api.mailkatana.com/v1/transactional \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "welcome",
    "name": "Welcome",
    "subject": "Welcome, {{first_name}}!",
    "htmlBody": "<p>Welcome, {{first_name}}!</p>",
    "textBody": "Welcome, {{first_name}}!",
    "variables": [
      { "name": "first_name", "kind": "user_defined", "data_type": "string", "required": true, "auto_resolved": false, "editable_in_rule": true }
    ],
    "autoResolvedVariables": [
      { "name": "company_name", "kind": "built_in", "data_type": "string", "required": false, "auto_resolved": true, "editable_in_rule": false },
      { "name": "contact.email", "kind": "contact_built_in", "data_type": "string", "required": false, "auto_resolved": true, "editable_in_rule": false }
    ],
    "emailCategory": "notification",
    "defaultStatus": "active",
    "createdAt": "2023-11-07T05:31:56Z"
  }
]

htmlBody / textBody are the rendered body for the template’s primary locale, with {{variable}} placeholders preserved. Use GET /v1/transactional/{templateId}/content/{locale} when you need the source component tree or a specific locale.
variables are the placeholders you supply in the send endpoint’s dataVariables.
autoResolvedVariables are platform-filled placeholders (for example company_name, date, and any contact.* field). MailKatana resolves these automatically at send time — do not pass them in dataVariables. They are listed here so you know what the template references.

Both variable arrays carry the same shape: name, label, kind, data_type, required, auto_resolved, editable_in_rule, and optional sources / child_fields / legacy_aliases.

Email content is a component tree

Email bodies are built from a small, fixed set of React Email components rather than raw HTML. A template’s body (per locale) is a JSON component tree — an ordered list of nodes:

{
  "schema": 1,
  "nodes": [
    { "type": "header", "props": {} },
    { "type": "heading", "props": { "text": "Welcome, {{first_name}}", "level": 1 } },
    { "type": "text", "props": { "text": "Thanks for joining {{company_name}}." } },
    { "type": "button", "props": { "text": "Get started", "href": "{{cta_url}}" } },
    { "type": "footer", "props": { "links": [{ "label": "Unsubscribe", "href": "{{unsub_url}}" }] } }
  ]
}

Available component types: container, section, header, footer, heading, text, button, link, image, list. {{variable}} placeholders are allowed in any text prop and are substituted at send time. The platform renders the tree to HTML/text and caches it; you never send raw HTML.

Example send

curl -X POST https://api.mailkatana.com/v1/transactional/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "avery@example.com",
    "templateId": "welcome_registration_success",
    "locale": "en-us",
    "dataVariables": {
      "first_name": "Avery",
      "login_url": "https://app.mailkatana.com/login"
    },
    "addToContact": true,
    "firstName": "Avery",
    "lastName": "Stone",
    "externalId": "usr_123",
    "properties": {
      "plan": "pro"
    }
  }'

The send response preserves success and supplies the public Activity ID:

{ "success": true, "messageId": "msg_example", "status": "accepted" }

Use messageId to correlate the request with Email Activity. Acceptance does not prove delivery or Inbox placement. A timeout remains ambiguous; do not blindly resend it.

Managing templates

Create a template with metadata and an optional content tree for the primary locale. The response id is the slug ID you pass to send, update, delete, content, and get-by-id endpoints.

curl -X POST https://api.mailkatana.com/v1/transactional/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome",
    "subject": "Welcome, {{first_name}}!",
    "preheader": "Glad to have you",
    "content": { "schema": 1, "nodes": [
      { "type": "heading", "props": { "text": "Welcome, {{first_name}}", "level": 1 } },
      { "type": "text", "props": { "text": "Thanks for joining." } }
    ] }
  }'

Update applies a partial change — metadata fields present in the body are modified; when content is present it replaces the primary-locale tree:

curl -X PUT https://api.mailkatana.com/v1/transactional/update \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "welcome", "subject": "Welcome aboard, {{first_name}}!" }'

Set or fetch a specific locale’s content tree:

curl -X PUT https://api.mailkatana.com/v1/transactional/welcome/content/fr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": { "schema": 1, "nodes": [
    { "type": "heading", "props": { "text": "Bienvenue, {{first_name}}", "level": 1 } }
  ] } }'

curl https://api.mailkatana.com/v1/transactional/welcome/content/fr \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete a template:

curl -X POST https://api.mailkatana.com/v1/transactional/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "welcome" }'

Delivery-rule automation remains managed in the MailKatana app.

Rendering rules

Email bodies render from the component tree; dataVariables use simple {{key}} replacement against the rendered subject/body.
Locale fallback order is exact locale, base locale, workspace brand primary locale, then English.

Attachments

Attachments are base64-encoded and support these content types:

application/pdf
image/png
image/jpeg
text/plain
text/csv

Limits:

up to 3 attachments
10 MB decoded per file
20 MB decoded total
25 MB total request size

Contact linking

When addToContact is true, MailKatana best-effort creates or updates the recipient as a contact and links the outbound recipient row without changing marketing consent.

Guides

Reference

Listing templates

Email content is a component tree

Example send

Managing templates

Rendering rules

Attachments

Contact linking

​Listing templates

​Email content is a component tree

​Example send

​Managing templates

​Rendering rules

​Attachments

​Contact linking

Listing templates

Email content is a component tree

Example send

Managing templates

Rendering rules

Attachments

Contact linking