Mailpark
API reference

Templates

Versioned emails with {{variable}} placeholders. Values come from the send's data, then the contact's fields, then the declared default; {{name|fallback}} sets an inline fallback.

Every PUT publishes a new version; sends record which version they used. Eight ready-made, branded templates are one call away with POST /v1/templates/essentials.

The Template object
type Template = {
  key: string;                 // "password-reset"
  version: number;
  type: "transactional" | "marketing";
  subject: string; preview_text: string | null;
  source_kind: "html" | "react" | "markdown" | "blocks";
  source: string;              // HTML/Markdown with {{var}}, or a JSON block document
  variables: { name: string; default?: string; description?: string }[];
  essential: boolean;          // one of the 8 ready-made templates
  updated_at: string;
  versions?: { version: number; created_at: string }[]; // GET /v1/templates/{key}
};

List templates

GET/v1/templates

Every template at its latest version.

curl https://api.mailpark.io/v1/templates \
  -H "Authorization: Bearer $MAILPARK_API_KEY"
Response · 200
{
  "data": [
    {
      "key": "password-reset",
      "version": 3,
      "type": "transactional",
      "subject": "Reset your {{product_name}} password",
      "preview_text": "This link expires in 1 hour.",
      "source_kind": "html",
      "source": "<html>…<a href=\"{{reset_url}}\">Reset password</a>…</html>",
      "variables": [
        {
          "name": "reset_url",
          "description": "Link to the reset page"
        }
      ],
      "essential": true,
      "updated_at": "2026-10-12T15:30:00Z"
    }
  ],
  "next_cursor": null
}
▶ Try it in the playground

Create a template

POST/v1/templates

A new template at version 1.

scope templates:write

Body

  • keystringrequired

    Lowercase id you send with, e.g. trial-ending.

  • typestringrequired

    transactional or marketing.

  • subjectstringrequired

    May contain {{variables}}.

  • sourcestringrequired

    The body: HTML or Markdown with {{variables}}, or a blocks JSON document.

  • source_kindstring

    html (default), react, markdown or blocks.

  • preview_textstring

    The line inboxes show after the subject.

  • variablesobject[]

    The variables it uses.

    • namestringrequired

      Placeholder name.

    • defaultstring

      Used when the send and contact have no value.

    • descriptionstring

      What goes in it.

  • fontsobject

    { heading?, body?, custom? }: Google Fonts families from GET /v1/fonts, or custom stylesheets.

curl -X POST https://api.mailpark.io/v1/templates \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "trial-ending",
    "type": "marketing",
    "subject": "Your {{product_name}} trial ends in 3 days",
    "source": "<p>Hi {{first_name|there}},</p><p>Your trial ends on {{trial_end}}.</p>",
    "variables": [
      {
        "name": "trial_end",
        "description": "Date the trial ends"
      }
    ]
  }'
Response · 200
{
  "key": "trial-ending",
  "version": 1,
  "type": "marketing",
  "subject": "Your {{product_name}} trial ends in 3 days",
  "preview_text": "This link expires in 1 hour.",
  "source_kind": "html",
  "source": "<html>…<a href=\"{{reset_url}}\">Reset password</a>…</html>",
  "variables": [
    {
      "name": "reset_url",
      "description": "Link to the reset page"
    }
  ],
  "essential": false,
  "updated_at": "2026-10-12T15:30:00Z"
}
▶ Try it in the playground

Get a template

GET/v1/templates/{key}

The latest version, or an earlier one with ?version=, plus the list of versions.

Path parameters

  • keystringrequired

    Template key.

Query parameters

  • versioninteger

    A specific version.

curl https://api.mailpark.io/v1/templates/password-reset \
  -H "Authorization: Bearer $MAILPARK_API_KEY"
Response · 200
{
  "key": "password-reset",
  "version": 3,
  "type": "transactional",
  "subject": "Reset your {{product_name}} password",
  "preview_text": "This link expires in 1 hour.",
  "source_kind": "html",
  "source": "<html>…<a href=\"{{reset_url}}\">Reset password</a>…</html>",
  "variables": [
    {
      "name": "reset_url",
      "description": "Link to the reset page"
    }
  ],
  "essential": true,
  "updated_at": "2026-10-12T15:30:00Z",
  "versions": [
    {
      "version": 3,
      "created_at": "2026-10-12T15:30:00Z"
    },
    {
      "version": 2,
      "created_at": "2026-10-01T09:00:00Z"
    },
    {
      "version": 1,
      "created_at": "2026-09-02T08:10:00Z"
    }
  ]
}
▶ Try it in the playground

Publish a new version

PUT/v1/templates/{key}

Saves a new version of the template. New sends use it right away; sent emails keep the version they used. Omit variables to keep the current list.

scope templates:write

Path parameters

  • keystringrequired

    Template key.

Body

  • typestringrequired

    transactional or marketing.

  • subjectstringrequired

    May contain {{variables}}.

  • sourcestringrequired

    The body.

  • source_kindstring

    html, react, markdown or blocks.

  • preview_textstring

    Inbox preview line.

  • variablesobject[]

    Replaces the variable list.

curl -X PUT https://api.mailpark.io/v1/templates/password-reset \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transactional",
    "subject": "Reset your {{product_name}} password",
    "source": "<p>Click <a href=\"{{reset_url}}\">here</a> to reset your password. The link expires in 1 hour.</p>"
  }'
Response · 200
{
  "key": "password-reset",
  "version": 4,
  "type": "transactional",
  "subject": "Reset your {{product_name}} password",
  "preview_text": "This link expires in 1 hour.",
  "source_kind": "html",
  "source": "<html>…<a href=\"{{reset_url}}\">Reset password</a>…</html>",
  "variables": [
    {
      "name": "reset_url",
      "description": "Link to the reset page"
    }
  ],
  "essential": true,
  "updated_at": "2026-10-12T15:30:00Z"
}
▶ Try it in the playground

Delete a template

DELETE/v1/templates/{key}

Deletes every version. Refused while a sequence or an unfinished campaign uses it.

scope templates:write

Path parameters

  • keystringrequired

    Template key.

Errors

curl -X DELETE https://api.mailpark.io/v1/templates/trial-ending \
  -H "Authorization: Bearer $MAILPARK_API_KEY"
Response · 200
{
  "deleted": true,
  "next_steps": []
}
▶ Try it in the playground

Preview a template

POST/v1/templates/{key}/preview

Renders the template with your data: subject, HTML, plain text, a screenshot URL, and any variables you didn't fill.

Path parameters

  • keystringrequired

    Template key.

Body

  • dataobject

    Values for the variables.

curl -X POST https://api.mailpark.io/v1/templates/welcome/preview \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "first_name": "Jane"
    }
  }'
Response · 200
{
  "subject": "Welcome to Acme, Jane",
  "html": "<!doctype html><html>…</html>",
  "text": "Hi Jane, welcome to Acme…",
  "image_url": "https://assets.mailpark.io/previews/welcome.png",
  "missing_variables": [],
  "next_steps": []
}
▶ Try it in the playground

Add the essential templates

POST/v1/templates/essentials

Adds 8 ready-made templates in your brand, built for mobile and dark mode: welcome, verify-email, password-reset, magic-link, receipt, payment-failed, team-invite and product-update.

scope templates:write

Body

  • brandobject

    Defaults to the account's brand.

    • product_namestring

      Shown in headers and subjects.

    • logo_urlstring

      HTTPS URL of your logo.

    • primary_colorstring

      Hex colour for buttons and links.

    • support_emailstring

      Shown in footers.

curl -X POST https://api.mailpark.io/v1/templates/essentials \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": {
      "product_name": "Acme",
      "logo_url": "https://acme.dev/logo.png",
      "primary_color": "#4f46e5",
      "support_email": "help@acme.dev"
    }
  }'
Response · 200
{
  "data": [
    {
      "key": "password-reset",
      "version": 3,
      "type": "transactional",
      "subject": "Reset your {{product_name}} password",
      "preview_text": "This link expires in 1 hour.",
      "source_kind": "html",
      "source": "<html>…<a href=\"{{reset_url}}\">Reset password</a>…</html>",
      "variables": [
        {
          "name": "reset_url",
          "description": "Link to the reset page"
        }
      ],
      "essential": true,
      "updated_at": "2026-10-12T15:30:00Z"
    }
  ],
  "next_steps": [
    "Preview one with POST /v1/templates/welcome/preview."
  ]
}
▶ Try it in the playground

List fonts

GET/v1/fonts

Google Fonts families templates can use for fonts.heading and fonts.body. Web fonts show in Apple Mail, iOS and Outlook for Mac; Gmail and Outlook for Windows use the fallback.

curl https://api.mailpark.io/v1/fonts \
  -H "Authorization: Bearer $MAILPARK_API_KEY"
Response · 200
{
  "data": [
    {
      "family": "Inter",
      "category": "sans",
      "weights": [
        400,
        500,
        600,
        700
      ]
    },
    {
      "family": "Playfair Display",
      "category": "serif",
      "weights": [
        400,
        700
      ]
    }
  ]
}
▶ Try it in the playground
PreviousEventsNextAssets