Templates

Update a template

PATCH/v1/templates/{id}

Requires an API key with the templates:write scope. About keys and scopes

Edits the template's draft. Campaigns and journeys that already copied it keep the content they were built with, and API sends keep the published version until POST /templates/{id}/publish. The envelope (subject, previewText, from, replyTo) is part of the draft and is published with it; null clears a field.

Path parameters

idstringrequired: uuid

Request body

namestringoptional

1–255 characters

schemaVersionintegeroptional

The block format version.

min > 0 · max 1000

blocksEmailBlockInput[]optional

At most 200 blocks across the entire tree and five levels including the root. Footer blocks must remain at root. Known child fields are validated recursively.

at least 1 item · at most 200 items

7 child attributes

idstringrequired

Identifies the block within the template; unique among its blocks.

1–128 characters

typestringrequired

The block type: header, heading, text, image, button, divider, spacer, columns, columns3, imagetext, imagegroup, boxed, quote, list, product, video, social, menu, html, section, footer, repeat, shared. Each type reads its own fields next to type; an unknown type is kept but not validated.

1–64 characters

styleEmailBlockStyleInputoptional

Visual overrides for this block, such as colours, font and spacing.

17 child attributes

backgroundColorstringoptional

Fill behind the block.

fontFamilystringoptional

A font every client has (Arial, Verdana, Georgia, Tahoma, Times New Roman, Courier New), or a web font, which shows where the client loads it and falls back to a safe font elsewhere.

one of Arial, Verdana, Georgia, Tahoma, Times New Roman, Courier New, Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, DM Sans, Nunito, Work Sans, Oswald, Playfair Display, Merriweather, Lora, Libre Baskerville, EB Garamond

fontSizeintegeroptional

Text size in px, 12 to 72.

min 12 · max 72

mobileFontSizeintegeroptional

Text size in px on phones (screens up to 620px), 12 to 72.

min 12 · max 72

paddingobjectoptional

Space inside the block in px, 0 to 100 per side; omitted sides keep their default.

4 child attributes

topintegeroptional: min 0 · max 100
rightintegeroptional: min 0 · max 100
bottomintegeroptional: min 0 · max 100
leftintegeroptional: min 0 · max 100

borderWidthintegeroptional

Border thickness in px; 0 for none.

min 0 · max 10

borderStylestringoptional

Border line style.

one of solid, dashed, dotted

borderColorstringoptional

Border colour.

borderRadiusintegeroptional

Corner rounding in px, 0 to 100.

min 0 · max 100

textColorstringoptional

Text colour.

linkColorstringoptional

Colour of links in the text.

letterSpacingnumberoptional

Space between letters in px, such as 3 for a spaced-out eyebrow line.

min -2 · max 20

textTransformstringoptional

Set to uppercase to capitalise all text.

one of none, uppercase

lineHeightnumberoptional

A multiple of the font size.

min 1 · max 3

fontWeightstringoptional

Text weight.

one of regular, bold

fontStylestringoptional

Text style.

one of normal, italic

insetbooleanoptional

Draw the background and border as a box within the content width, not across the whole row.

visibleIfobjectoptional

Show the block only to contacts these segment rules match, checked as each message is rendered. Omit to show it to everyone. Not allowed on the footer.

One of 2 shapes

Match all

1 child attribute

allobject[]required

Every rule or nested group must match.

at least 1 item · at most 20 items

Match any

1 child attribute

anyobject[]required

At least one rule or nested group must match.

at least 1 item · at most 20 items

showOnstringoptional

Show the block only on phones (screens up to 620px) or only on wider screens. Clients that ignore screen size show the desktop version, and so does plain text. Omit to show it everywhere. Not allowed on the footer.

one of mobile, desktop

columnsobject[][]optional

Nested child block arrays: exactly two for columns, three for columns3. Each child follows this block contract. Omit to retain legacy text columns.

at most 3 items

blocksobject[]optional

A section's child blocks, drawn inside its box; or a repeat block's, written out once per item of its list, where {{ item.<field> }} reads that item. Repeats do not nest.

at most 200 items

themeEmailThemeInputoptional

Theme values this email overrides.

11 child attributes

fontstringoptional

Body font stack, such as Inter, sans-serif.

up to 200 characters

hfontstringoptional

Heading font stack.

up to 200 characters

bgstringoptional

Background of the email card, as hex.

canvasstringoptional

Background behind the card, as hex.

textstringoptional

Default text colour, as hex.

accentstringoptional

Brand colour for buttons and highlights, as hex.

linkstringoptional

Link colour, as hex.

widthstringoptional

Width of the email card on wide screens.

one of 560px, 600px, 680px

radiusstringoptional

Corner rounding of the email's card.

one of 0px, 6px, 12px, 16px, 24px, 999px

btnRadiusstringoptional

Button corners; radius rounds the email's card and, when this is unset, buttons.

one of 0px, 6px, 12px, 16px, 24px, 999px

btnstringoptional

Button style.

one of solid, outline

plainTextOverridestring | nulloptional

Plain text sent instead of the version generated from the blocks; null clears it.

up to 100000 characters

subjectstring | nulloptional

Used by an API send that names this template, unless the send gives its own. Merge tags may read event.properties.*.

1–998 characters

previewTextstring | nulloptional

Used by an API send that names this template, unless the send gives its own. Merge tags may read event.properties.*.

1–255 characters

fromstring | nulloptional

Used by an API send that names this template, unless the send gives its own. One address, optionally with a display name; its domain must be verified when a send uses it.

1–320 characters

replyTostring | nulloptional

Used by an API send that names this template, unless the send gives its own.

email · up to 320 characters

aliasstring | nulloptional

Unique in the workspace; an API send may name the template by it in templateId. Null clears it.

up to 64 characters

expectedRevisionintegeroptional

The revision you read. When it is no longer current the update is refused with 409 REVISION_CONFLICT, whose details carry the current revision, updatedAt and who made the change. Omit it to overwrite whatever is there.

min > 0 · max 2147483647

Returns

Returns 200 OK with a Template in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

namestringrequired

schemaVersionintegerrequired

The block format version.

min > 0 · max 1000

blocksEmailBlock[]required

At most 200 blocks across the entire tree and five levels including the root. Footer blocks must remain at root. Known child fields are validated recursively.

at least 1 item · at most 200 items

7 child attributes

idstringrequired

Identifies the block within the template; unique among its blocks.

1–128 characters

typestringrequired

1–64 characters

styleEmailBlockStyleoptional

Visual overrides for this block, such as colours, font and spacing.

17 child attributes

backgroundColorstringoptional

Fill behind the block.

fontFamilystringoptional

A font every client has (Arial, Verdana, Georgia, Tahoma, Times New Roman, Courier New), or a web font, which shows where the client loads it and falls back to a safe font elsewhere.

fontSizeintegeroptional

Text size in px, 12 to 72.

min 12 · max 72

mobileFontSizeintegeroptional

Text size in px on phones (screens up to 620px), 12 to 72.

min 12 · max 72

paddingobjectoptional

Space inside the block in px, 0 to 100 per side; omitted sides keep their default.

4 child attributes

topintegeroptional: min 0 · max 100
rightintegeroptional: min 0 · max 100
bottomintegeroptional: min 0 · max 100
leftintegeroptional: min 0 · max 100

borderWidthintegeroptional

Border thickness in px; 0 for none.

min 0 · max 10

borderStylestringoptional

Border line style.

one of solid, dashed, dotted

borderColorstringoptional

Border colour.

borderRadiusintegeroptional

Corner rounding in px, 0 to 100.

min 0 · max 100

textColorstringoptional

Text colour.

linkColorstringoptional

Colour of links in the text.

letterSpacingnumberoptional

Space between letters in px, such as 3 for a spaced-out eyebrow line.

min -2 · max 20

textTransformstringoptional

Set to uppercase to capitalise all text.

one of none, uppercase

lineHeightnumberoptional

A multiple of the font size.

min 1 · max 3

fontWeightstringoptional

Text weight.

one of regular, bold

fontStylestringoptional

Text style.

one of normal, italic

insetbooleanoptional

Draw the background and border as a box within the content width, not across the whole row.

visibleIfobjectoptional

Show the block only to contacts these segment rules match, checked as each message is rendered. Omit to show it to everyone. Not allowed on the footer.

One of 2 shapes

Match all

1 child attribute

allobject[]required

Every rule or nested group must match.

at least 1 item · at most 20 items

Match any

1 child attribute

anyobject[]required

At least one rule or nested group must match.

at least 1 item · at most 20 items

showOnstringoptional

one of mobile, desktop

columnsobject[][]optional

Nested child block arrays: exactly two for columns, three for columns3. Each child follows this block contract. Omit to retain legacy text columns.

at most 3 items

blocksobject[]optional

A section's child blocks, drawn inside its box; or a repeat block's, written out once per item of its list, where {{ item.<field> }} reads that item. Repeats do not nest.

at most 200 items

themeEmailThemerequired

Theme values this email overrides.

11 child attributes

fontstringoptional

Body font stack, such as Inter, sans-serif.

up to 200 characters

hfontstringoptional

Heading font stack.

up to 200 characters

bgstringoptional

Background of the email card, as hex.

canvasstringoptional

Background behind the card, as hex.

textstringoptional

Default text colour, as hex.

accentstringoptional

Brand colour for buttons and highlights, as hex.

linkstringoptional

Link colour, as hex.

widthstringoptional

Width of the email card on wide screens.

one of 560px, 600px, 680px

radiusstringoptional

Corner rounding of the email's card.

one of 0px, 6px, 12px, 16px, 24px, 999px

btnRadiusstringoptional

Button corners; radius rounds the email's card and, when this is unset, buttons.

one of 0px, 6px, 12px, 16px, 24px, 999px

btnstringoptional

Button style.

one of solid, outline

plainTextOverridestring | nullrequired

Plain text sent instead of the version generated from the blocks.

subjectstring | nullrequired

What an API send by templateId uses by default.

previewTextstring | nullrequired

What an API send by templateId uses by default.

fromstring | nullrequired

What an API send by templateId uses by default.

replyTostring | nullrequired

What an API send by templateId uses by default.

aliasstring | nullrequired

The name an API send may use in templateId.

publishedVersioninteger | nullrequired

The version API sends use; null until published. The template itself is the draft.

min > 0 · max 9007199254740991

hasUnpublishedChangesbooleanrequired

The draft differs from the published version, or was never published.

revisionintegerrequired

Raised by every edit. Send it back as expectedRevision on the update so a change made since you read it is refused instead of overwritten.

min > 0 · max 2147483647

thumbnailUrlstring | nullrequired

A small picture of the design (WebP, 320 × 427), redrawn a few seconds after each save; null until the first is drawn.

uri

thumbnailUpdatedAtstring | nullrequired

When the thumbnail was last drawn.

date-time

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

curl -X PATCH https://api.kirora.io/v1/templates/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend specials",
    "schemaVersion": 1,
    "blocks": [
      {
        "id": "id_example",
        "type": "type_example"
      }
    ],
    "theme": {},
    "plainTextOverride": "plainTextOverride_example",
    "subject": "Your order is on its way",
    "previewText": "Arriving Thursday",
    "from": "Juniper Kitchen <hello@juniperkitchen.com>",
    "replyTo": "amaka@juniperkitchen.com",
    "alias": "alias_example",
    "expectedRevision": 1
  }'

const response = await fetch('https://api.kirora.io/v1/templates/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Weekend specials",
    "schemaVersion": 1,
    "blocks": [
      {
        "id": "id_example",
        "type": "type_example"
      }
    ],
    "theme": {},
    "plainTextOverride": "plainTextOverride_example",
    "subject": "Your order is on its way",
    "previewText": "Arriving Thursday",
    "from": "Juniper Kitchen <hello@juniperkitchen.com>",
    "replyTo": "amaka@juniperkitchen.com",
    "alias": "alias_example",
    "expectedRevision": 1
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.patch(
    "https://api.kirora.io/v1/templates/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "name": "Weekend specials",
        "schemaVersion": 1,
        "blocks": [
            {
                "id": "id_example",
                "type": "type_example",
            },
        ],
        "theme": {},
        "plainTextOverride": "plainTextOverride_example",
        "subject": "Your order is on its way",
        "previewText": "Arriving Thursday",
        "from": "Juniper Kitchen <hello@juniperkitchen.com>",
        "replyTo": "amaka@juniperkitchen.com",
        "alias": "alias_example",
        "expectedRevision": 1,
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "name": "Weekend specials",
	  "schemaVersion": 1,
	  "blocks": [
	    {
	      "id": "id_example",
	      "type": "type_example"
	    }
	  ],
	  "theme": {},
	  "plainTextOverride": "plainTextOverride_example",
	  "subject": "Your order is on its way",
	  "previewText": "Arriving Thursday",
	  "from": "Juniper Kitchen <hello@juniperkitchen.com>",
	  "replyTo": "amaka@juniperkitchen.com",
	  "alias": "alias_example",
	  "expectedRevision": 1
	}`)
	req, err := http.NewRequest("PATCH", "https://api.kirora.io/v1/templates/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 200

{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "name": "Weekend specials",
    "schemaVersion": 1,
    "blocks": [
      {
        "id": "id_example",
        "type": "type_example"
      }
    ],
    "theme": {},
    "plainTextOverride": "plainTextOverride_example",
    "subject": "Your order is on its way",
    "previewText": "Arriving Thursday",
    "from": "Juniper Kitchen <hello@juniperkitchen.com>",
    "replyTo": "amaka@juniperkitchen.com",
    "alias": "alias_example",
    "publishedVersion": 1,
    "hasUnpublishedChanges": true,
    "revision": 1,
    "thumbnailUrl": "https://example.com",
    "thumbnailUpdatedAt": "2030-03-14T09:30:00Z",
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}

Example values are generated from the schema.