Templates

Templates versionados com variáveis, referenciados por `templateKey` (`publiq.templates`).

O recurso templates cobre o ciclo de vida de um template versionado: criar (com html/subject/text e variáveis), consultar, listar, pré-visualizar uma versão salva e, para o AI builder, renderizar ou salvar a partir de uma SPEC de json-render.

Referência de métodos

`templates.create`

templates.create(params) → Promise<Template>

Cria um template versionado a partir de HTML (com variáveis interpoladas). Gera automaticamente um key legível e a primeira versão do template.

Parâmetros

Parâmetro	Tipo	Descrição
`name`Obrigatório	`string`	Nome do template. Deve ser único dentro da organização.
`html`Obrigatório	`string`	Corpo HTML do template. Pode conter `{{ variáveis }}` interpoladas no envio ou no preview.
`subject`Opcional	`string`	Assunto padrão do template. Também pode conter variáveis.
`text`Opcional	`string`	Alternativa em texto-plano ao `html` (fallback e melhor entregabilidade).
`engine`Opcional	`string`	Motor de renderização das variáveis (ex.: `handlebars`). Se omitido, usa o padrão da organização.

Retorna: O template criado — inclui o key gerado automaticamente e a sua primeira versão.

const template = await publiq.templates.create({
name: 'welcome-email',
subject: 'Welcome, {{ first_name }}!',
html: '<h1>Hi {{ first_name }}</h1><p>Welcome to {{ company }}.</p>',
text: 'Hi {{ first_name }}, welcome to {{ company }}.',
});
console.log(template.id, template.key); // "tpl_...", "welcome-email"

O key (slug legível, ex.: welcome-email) pode ser usado em Emails (emails.send({ templateKey })) e em Broadcasts (broadcasts.create({ templateId })). Variáveis usam {{ snake_case }} — veja Variáveis.

`templates.get`

templates.get(id) → Promise<Template>

Busca os detalhes de um template pelo id, incluindo versions[] e o key legível.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do template (retornado por `templates.create`).

Retorna: O template com o histórico de versões (versions[]) e o key. 404 se não existir na organização.

const template = await publiq.templates.get('tpl_123');
console.log(template.key, template.versions.length);

O key retornado aqui é o mesmo aceito por emails.send({ templateKey }) e broadcasts.create({ templateId }) — veja Emails e Broadcasts.

`templates.list`

templates.list({ limit?, after? }) → Promise<TemplateList>

Lista os templates da organização, do mais recente ao mais antigo, com paginação por cursor. Cada item é um resumo com version_count.

Parâmetros

Parâmetro	Tipo	Descrição
`limit`Opcional	`number`	Itens por página (padrão 20, máx. 100).
`after`Opcional	`string`	Cursor: `id` do último item da página anterior.

Retorna: Envelope de lista { object: "list", data: TemplateSummary[] }. Use o id do último item como after na próxima chamada.

const { data } = await publiq.templates.list({ limit: 50 });
// next page:
const next = await publiq.templates.list({ after: data[data.length - 1].id });

A listagem é paginada por cursor: itere passando o id do último item em after até data vir vazio. Veja Erros & paginação.

`templates.preview`

templates.preview(id, { version? }) → Promise<TemplatePreview>

Renderiza uma versão salva do template com as variáveis de exemplo resolvidas, para conferência visual antes do envio.

Parâmetros

Parâmetro	Tipo	Descrição
`id`Obrigatório	`string`	ID do template.
`version`Opcional	`string`	Versão a pré-visualizar. Se omitida, usa a versão mais recente.

Retorna: Um preview { object: "template_preview", subject, html } com o assunto e o HTML já renderizados.

const preview = await publiq.templates.preview('tpl_123', { version: '2' });
console.log(preview.subject, preview.html);

`templates.render`

templates.render(params) → Promise<TemplateRender>

Renderiza uma SPEC de json-render ({ root, elements, state }) sob demanda, sem persistir nada — é o preview ao vivo usado pelo AI builder.

Parâmetros

Parâmetro	Tipo	Descrição
`spec`Obrigatório	`object`	SPEC de json-render — `{ root, elements, state }` — descrevendo a árvore de elementos do e-mail.

Retorna: { object: "template_render", html, text } — resultado renderizado, não salvo.

const spec = {
root: 'body',
elements: {
  body: { type: 'container', children: ['heading'] },
  heading: { type: 'text', content: 'Hi {{ first_name }}' },
},
state: {},
};
const rendered = await publiq.templates.render({ spec });
console.log(rendered.html);

render e fromSpec alimentam o AI builder e exigem o recurso de plano ai_builder. render é uma pré-visualização que não persiste; use templates.fromSpec para salvar o resultado como uma nova versão do template.

`templates.fromSpec`

templates.fromSpec(params) → Promise<Template>

Renderiza uma SPEC de json-render e salva o resultado como um novo template (ou nova versão), com key gerado automaticamente.

Parâmetros

Parâmetro	Tipo	Descrição
`name`Obrigatório	`string`	Nome do template. Deve ser único dentro da organização.
`spec`Obrigatório	`object`	SPEC de json-render — `{ root, elements, state }` — a mesma estrutura usada em `templates.render`.
`subject`Opcional	`string`	Assunto do template.

Retorna: O template criado a partir da SPEC renderizada, com key gerado automaticamente.

const template = await publiq.templates.fromSpec({
name: 'newsletter-july',
subject: 'Your July newsletter',
spec,
});
console.log(template.key);

fromSpec (Python: from_spec) exige o recurso de plano ai_builder, assim como render. Diferente de render, aqui o resultado é salvo como template.

Os exemplos mostram Node, Python e PHP. No Python os métodos são snake_case (ex.: cancel_run, from_spec) e recebem um dict; no PHP são camelCase e recebem um array associativo. As chaves do corpo são sempre camelCase (templateKey, firstName, scheduledAt) — o retorno da API vem em snake_case.