Skip to main content

Features

Email Templates

Keep your email bodies out of your application code. Templates are versioned, rendered server-side, and referenced at send time.

Content that lives outside your deploy

A template holds the markup and variable schema for one kind of message. Your application sends an id and a set of values, and mailkube renders the body. Changing the wording of a receipt becomes a dashboard edit, not a release.

Start from the catalog, or a blank page

Every organization can browse a catalog of ready-made templates: onboarding and email verification, receipts and shipping notices, password resets and sign-in alerts, promotions and newsletters.

Copying one makes it yours. The copy lands against your own domain and versions like any template you write yourself. The catalog entry keeps no history of its own, so copy first and edit after.

A blank page is the other way in, and the same thing with nothing in it yet.

Sending a template

Reference the template by its id instead of passing html or text. Sending both is a validation_error.

curl -X POST https://api.mailkube.com/mta/v1/emails \
  -H "Authorization: Bearer mk_<key_id>_<secret>" \
  -H "Content-Type: application/json" \
  -H "User-Agent: acme-billing/1.4" \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": "customer@example.com",
    "subject": "Welcome to Acme",
    "template_id": "3f6c2e1a-8b4d-4c2e-9a1f-2b3c4d5e6f70",
    "template_version": "latest",
    "variables": {
      "first_name": "Alice",
      "activation_url": "https://app.example.com/activate/abc123"
    }
  }'

The same send over SMTP

Three headers carry what the JSON body carried. All three are stripped before the message goes out, and the body you submit is discarded.

swaks --server smtp.mailkube.com --port 587 -tls \
      --auth --auth-user myapp01@yourdomain.com --auth-password "$SMTP_PASSWORD" \
      --from hello@yourdomain.com \
      --to customer@example.com \
      --h-Subject "Welcome to Acme" \
      --add-header "X-Mailkube-Template-Id: 3f6c2e1a-8b4d-4c2e-9a1f-2b3c4d5e6f70" \
      --add-header "X-Mailkube-Template-Version: latest" \
      --add-header 'X-Mailkube-Template-Variables: {"first_name":"Alice","activation_url":"https://app.example.com/activate/abc123"}' \
      --body "Replaced by the rendered template."

Single-quote the variables header, or the shell will eat the JSON. It has to parse as a JSON object and stay under 16 KB, and a malformed one is refused at submission. Attachments on the message are kept and delivered alongside the rendered body.

Variables

Declare the variables a template uses, written {{variable_id}} in the content. Values you pass that a template does not declare are ignored at send time. A required variable you leave out fails the send with missing_required_variable, before the message goes anywhere.

An id or version that does not exist fails the same way, with template_not_found.

Versions

Editing a template appends a version rather than overwriting one. Each version freezes the content together with the variable schema it was written against. The two can never drift apart.

Name the version you want, either a specific number or latest, which is the default. Pin a number to hold a critical message on reviewed content while the template keeps changing. Naming an older number is also how you undo a bad edit.

Template fields and where to edit them