Templates quick start

Templates are designed in the portal editor; the API reads them, publishes versions and renders previews. This walk-through uses the TypeScript SDK; every call maps to an operation in the reference.

#1. Pick a product

const products = await client.products.list();
const specificationId = products[0].specification.id;

#2. Create a template and publish a version

const template = await client.templates.create({
  body: { name: 'Welcome card', productSpecificationId: specificationId },
  idempotencyKey: 'crm-template-welcome',
});
// Design the draft in the portal editor, then:
const version = await client.templates.publish(template.id, { body: {} });

A publish that fails validation answers 422 validation_failed with element-level errors (missing variables, low image resolution, text overflow).

#3. Render a preview and a proof PDF

const preview = await client.renders.preview(template.id, String(version.number), {
  body: { variables: { firstName: 'Anna' } },
});
// 202 while rendering: poll
let status = await client.renders.getPreview(preview.id);
while (status.status !== 'READY') {
  await new Promise((r) => setTimeout(r, 1000));
  status = await client.renders.getPreview(preview.id);
}
console.log(status.urls);

Proof PDFs work the same way through renders.proof and renders.getJob. Both requests count against the preview rate limit class.

#4. Upload an image asset

Uploads are two steps: create a session (answers a presigned PUT URL), upload the bytes to that URL, then complete the session so the file is scanned and processed.

const session = await client.uploads.create({
  body: {
    kind: 'image',
    fileName: 'hero.jpg',
    contentType: 'image/jpeg',
    sizeBytes: bytes.length,
    sha256,
  },
});
await fetch(session.url, { method: 'PUT', headers: session.headers, body: bytes });
const done = await client.uploads.complete(session.id);

#5. Fixed parts of a product

A product version can come with a base design: elements that PostBuddy places on every new template of that product, such as the address block, a franking mark or a return address. A new template starts as a copy of that base. Each base element carries scopes that say what you may change (move, resize, rotate, content, style, arrange, hide, delete). Saving a draft or publishing a version that changes a fixed aspect answers 422 base_template_violation with one entry per element and rule. Images placed by PostBuddy are listed by GET /v1/platform-assets?ids=... with a display rendition; they never appear in GET /v1/assets.