POST/v1/templates/{id}/publish

Publish the draft as a new version

Scope templates.writeIdempotent with a key

Path parameters

idstringrequired

Headers

Idempotency-Keystringmax length 255

Up to 255 characters, scoped to the organisation and the endpoint, kept for 24 hours: a repeat with the same body replays the stored response with Idempotent-Replayed: true (API-004).

Body

sampleVariablesobject

sampleRecipientobject

6 fields

namestringrequired

addressLine1stringrequired

addressLine2string

postalCodestringrequired

citystringrequired

countrystringrequired

Returns

12 fields of the 201 answer

idstringrequired

numberintegerrequired

publishedAtdate-timerequired

publishedByTypeenumrequired

USERAPI_KEY

publishedByIdstringrequired

staticLayerStatusenumrequired

PENDINGREADYFAILED

templateIdstringrequired

documentobjectrequired

6 fields

schemaVersionnumberrequired

productobjectrequired

5 fields

specificationIdstringrequiredmin length 1

trimWidthMmnumberrequired

trimHeightMmnumberrequired

bleedMmnumberrequiredmin 0

safeZoneMmnumberrequiredmin 0

pagesarray of objectsrequiredmin items 1

3 fields

idstringrequired

sidestringrequiredmin length 1max length 32

elementsarray of one ofrequiredmax items 500

colorsobjectrequired

fontsarray of objectsrequired

3 fields

idstringrequiredmin length 1

familystringrequiredmin length 1

sourceenumrequired

curatedorganisationgoogle

metaobject

schemaVersionintegerrequired

variableSchemaarray of objectsrequired

7 fields

namestringrequired

typeenumrequired

textnumberdatebooleanimageUrlurl

requiredbooleanrequired

fallbackstring

maxLengthinteger

formatstring

descriptionstring

staticElementIdsobjectrequired

warningsarray of objectsrequired

5 fields

codestringrequired

severityenumrequired

errorwarning

messagestringrequired

pageIdstring

elementIdstring

Responses

201Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

409A request with this Idempotency-Key is still in progress (idempotency_in_progress)

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

Request

curl -X POST https://api.postbuddy.nl/v1/templates/tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K/publish \
  -H "Authorization: Bearer $POSTBUDDY_API_KEY" \
  -H "Idempotency-Key: crm-0062p00001Xyz-signed" \
  -H "Content-Type: application/json" \
  -d '{
    "sampleVariables": {
      "key": "first_name"
    },
    "sampleRecipient": {
      "name": "Welcome card",
      "addressLine1": "Oudegracht 112",
      "postalCode": "3511 AX",
      "city": "Utrecht",
      "country": "NL"
    }
  }'

import { PostBuddyClient } from '@postbuddy/sdk';

const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! });

const result = await client.templates.publish('tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K', {
  body: {
    sampleVariables: {
      key: 'first_name',
    },
    sampleRecipient: {
      name: 'Welcome card',
      addressLine1: 'Oudegracht 112',
      postalCode: '3511 AX',
      city: 'Utrecht',
      country: 'NL',
    },
  },,
  idempotencyKey: 'crm-0062p00001Xyz-signed',
});

import os
from postbuddy import Client

client = Client(os.environ["POSTBUDDY_API_KEY"])

result = client.templates.publish("tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", {
    "sampleVariables": {
        "key": "first_name",
    },
    "sampleRecipient": {
        "name": "Welcome card",
        "addressLine1": "Oudegracht 112",
        "postalCode": "3511 AX",
        "city": "Utrecht",
        "country": "NL",
    },
}, idempotency_key="crm-0062p00001Xyz-signed")

Response

{
  "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "number": 1,
  "publishedAt": "2026-10-16T09:14:02.000Z",
  "publishedByType": "USER",
  "publishedById": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "staticLayerStatus": "READY",
  "templateId": "tpl_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "document": {
    "schemaVersion": 1,
    "product": {
      "specificationId": "psp_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
      "trimWidthMm": 1,
      "trimHeightMm": 1,
      "bleedMm": 1,
      "safeZoneMm": 1
    },
    "pages": [
      {
        "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
        "side": "Example",
        "elements": [
          {
            "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
            "name": "Welcome card",
            "x": 1,
            "y": 1,
            "width": 1,
            "height": 1,
            "rotation": 1,
            "opacity": 1,
            "locked": false,
            "hidden": false,
            "visibleIf": {
              "variable": "first_name",
              "op": "isSet",
              "value": "Example"
            },
            "system": false,
            "scopes": {
              "move": false,
              "resize": false,
              "rotate": false,
              "content": false,
              "style": false,
              "arrange": false,
              "hide": false,
              "delete": false
            },
            "onTop": false,
            "keepClear": false,
            "type": "text",
            "fitMode": "none",
            "minFontSizePt": 1,
            "verticalAlign": "top",
            "padding": {
              "top": 1,
              "right": 1,
              "bottom": 1,
              "left": 1
            },
            "defaultStyle": {
              "fontId": "fnt_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
              "sizePt": 1,
              "weight": 100,
              "italic": false,
              "underline": false,
              "strike": false,
              "colorRef": "Example",
              "color": "#D44050",
              "letterSpacingPt": 1
            },
            "paragraphs": [
              {
                "align": "left",
                "lineHeight": 1,
                "spaceBeforeMm": 1,
                "spaceAfterMm": 1,
                "list": {
                  "kind": "bullet",
                  "level": 1,
                  "marker": "Exam"
                },
                "style": {
                  "fontId": "fnt_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
                  "sizePt": 1,
                  "weight": 100,
                  "italic": false,
                  "underline": false,
                  "strike": false,
                  "colorRef": "Example",
                  "color": "#D44050",
                  "letterSpacingPt": 1
                },
                "runs": [
                  {
                    "text": "Example",
                    "variable": "first_name",
                    "style": {
                      "fontId": "fnt_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
                      "sizePt": 1,
                      "weight": 100,
                      "italic": false,
                      "underline": false,
                      "strike": false,
                      "colorRef": "Example",
                      "color": "#D44050",
                      "letterSpacingPt": 1
                    }
                  }
                ]
              }
            ],
            "autoHeight": false
          }
        ]
      }
    ],
    "colors": {
      "key": {
        "rgb": "#D44050",
        "cmyk": [
          null,
          null
        ]
      }
    },
    "fonts": [
      {
        "id": "fnt_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
        "family": "Example",
        "source": "curated"
      }
    ],
    "meta": {}
  },
  "schemaVersion": 1,
  "variableSchema": [
    {
      "name": "Welcome card",
      "type": "text",
      "required": false,
      "fallback": "Example",
      "maxLength": 1,
      "format": "2026-10-16T09:14:02.000Z",
      "description": "Welcome card for new customers"
    }
  ],
  "staticElementIds": {
    "key": [
      "first_name"
    ]
  },
  "warnings": []
}

{
  "type": "https://docs.postbuddy.nl/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Not found",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}

{
  "type": "https://docs.postbuddy.nl/errors/idempotency_in_progress",
  "title": "Request with this idempotency key in progress",
  "status": 409,
  "code": "idempotency_in_progress",
  "detail": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K"
}

{
  "type": "https://docs.postbuddy.nl/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_failed",
  "detail": "Validation failed",
  "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K",
  "errors": [
    {
      "field": "recipient.postalCode",
      "code": "invalid_string",
      "message": "Invalid postal code"
    }
  ]
}