Manage Templates

Create, list, update, and delete message templates.

Manage reusable message templates via the API.

Scope: templates:write (create/update/delete), templates:read (list/get)

Rate limit: 1,000/hr

Create a template

POST /api/v1/templates

Field	Type	Required	Description
name	string	Yes	Unique template name (used as a slug)
subject	string	No	Subject line template (supports variables)
body	string	Yes	HTML body with Handlebars variables
description	string	No	Internal description

curl -X POST https://api.platformxe.com/api/v1/templates \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "name": "welcome-email",
    "subject": "Welcome to {{appName}}, {{firstName}}!",
    "body": "<h1>Welcome, {{firstName}}!</h1><p>Get started with {{appName}}.</p>",
    "description": "Sent after user registration"
  }'

await px.createTemplate({
  name: 'welcome-email',
  subject: 'Welcome to {{appName}}, {{firstName}}!',
  body: '<h1>Welcome, {{firstName}}!</h1><p>Get started with {{appName}}.</p>',
  description: 'Sent after user registration',
});

List templates

GET /api/v1/templates

curl https://api.platformxe.com/api/v1/templates \
  -H "x-api-key: pxk_live_your_api_key_here"

const templates = await px.listTemplates();

Get a template

GET /api/v1/templates/:id

curl https://api.platformxe.com/api/v1/templates/tpl_abc123 \
  -H "x-api-key: pxk_live_your_api_key_here"

Update a template

PATCH /api/v1/templates/:id

Send only the fields to change. Every field is optional.

Field	Type	Description
name	string	Template name (non-empty)
description	string	Internal description
subject	string	Subject line template
bodyBlocks	TemplateBlock[]	Replaces the body. Each block has a type of text, heading, button, image, divider or spacer, plus content / level / label / url / src / alt / height as the type needs.
variables	string[]	Declared variable names
ctaLabel	string | null	Call-to-action button label. null clears it.
ctaUrl	string | null	Call-to-action URL — http(s) only. null clears it.

Unknown fields are ignored. A malformed bodyBlocks entry (for example an unknown type) returns VALIDATION_ERROR (HTTP 400).

Clearing a field

description, ctaLabel and ctaUrl are nullable, so sending null clears them. Omitting a field leaves it unchanged, and sending null for a non-nullable field (name, subject) is rejected with VALIDATION_ERROR.

curl -X PATCH https://api.platformxe.com/api/v1/templates/tpl_abc123 \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{ "ctaLabel": null, "ctaUrl": null }'

curl -X PATCH https://api.platformxe.com/api/v1/templates/tpl_abc123 \
  -H "Content-Type: application/json" \
  -H "x-api-key: pxk_live_your_api_key_here" \
  -d '{
    "bodyBlocks": [
      { "type": "heading", "content": "Welcome aboard, {{firstName}}!", "level": 1 },
      { "type": "text", "content": "Your account is ready." }
    ],
    "ctaLabel": "Open dashboard",
    "ctaUrl": "https://app.example.com"
  }'

Delete a template

DELETE /api/v1/templates/:id

curl -X DELETE https://api.platformxe.com/api/v1/templates/tpl_abc123 \
  -H "x-api-key: pxk_live_your_api_key_here"

Error responses

Code	Description
BAD_REQUEST	Missing template name or body
CONFLICT	Template with that name already exists
FORBIDDEN	API key missing required scope
NOT_FOUND	Template does not exist