Publiq

Plantillas

Plantillas versionadas con variables, referenciadas por `templateKey` (`publiq.templates`).

El recurso templates cubre el ciclo de vida de una plantilla versionada: crear (con html/subject/text y variables), consultar, listar, previsualizar una versión guardada y, para el AI builder, renderizar o guardar a partir de una SPEC de json-render.

Referencia de métodos

templates.create

templates.create(params) → Promise<Template>

Crea una plantilla versionada a partir de HTML (con variables interpoladas). Genera automáticamente un key legible y la primera versión de la plantilla.

Parámetros
ParámetroTipoDescripción
nameObligatoriostringNombre de la plantilla. Debe ser único dentro de la organización.
htmlObligatoriostringCuerpo HTML de la plantilla. Puede contener {{ variables }} interpoladas en el envío o en el preview.
subjectOpcionalstringAsunto por defecto de la plantilla. También puede contener variables.
textOpcionalstringAlternativa en texto-plano al html (fallback y mejor entregabilidad).
engineOpcionalstringMotor de renderizado de las variables (ej.: handlebars). Si se omite, usa el valor por defecto de la organización.

Devuelve: La plantilla creada — incluye el key generado automáticamente y su primera versión.

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"
El key (slug legible, ej.: welcome-email) puede usarse en Emails (emails.send({ templateKey })) y en Broadcasts (broadcasts.create({ templateId })). Las variables usan {{ snake_case }} — ver Variables.

templates.get

templates.get(id) → Promise<Template>

Obtiene los detalles de una plantilla por id, incluyendo versions[] y el key legible.

Parámetros
ParámetroTipoDescripción
idObligatoriostringID de la plantilla (devuelto por templates.create).

Devuelve: La plantilla con su historial de versiones (versions[]) y key. 404 si no existe en la organización.

const template = await publiq.templates.get('tpl_123');
console.log(template.key, template.versions.length);
El key devuelto aquí es el mismo aceptado por emails.send({ templateKey }) y broadcasts.create({ templateId }) — ver Emails y Broadcasts.

templates.list

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

Lista las plantillas de la organización, de la más reciente a la más antigua, paginado por cursor. Cada ítem es un resumen con version_count.

Parámetros
ParámetroTipoDescripción
limitOpcionalnumberÍtems por página (por defecto 20, máx. 100).
afterOpcionalstringCursor: id del último ítem de la página anterior.

Devuelve: Envoltura de lista { object: "list", data: TemplateSummary[] }. Usa el id del último ítem como after en la próxima llamada.

const { data } = await publiq.templates.list({ limit: 50 });
// next page:
const next = await publiq.templates.list({ after: data[data.length - 1].id });
El listado se pagina por cursor: itera pasando el id del último ítem en after hasta que data venga vacío. Ver Errores & paginación.

templates.preview

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

Renderiza una versión guardada de la plantilla con sus variables resueltas, para revisión visual antes del envío.

Parámetros
ParámetroTipoDescripción
idObligatoriostringID de la plantilla.
versionOpcionalstringVersión a previsualizar. Si se omite, usa la versión más reciente.

Devuelve: Un preview { object: "template_preview", subject, html } con el asunto y el HTML ya 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 una SPEC de json-render ({ root, elements, state }) al vuelo, sin persistir nada — es el preview en vivo usado por el AI builder.

Parámetros
ParámetroTipoDescripción
specObligatorioobjectUna SPEC de json-render — { root, elements, state } — que describe el árbol de elementos del correo.

Devuelve: { object: "template_render", html, text } — resultado renderizado, no guardado.

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 y fromSpec alimentan el AI builder y requieren el feature de plan ai_builder. render es una vista previa que no persiste; usa templates.fromSpec para guardar el resultado como una nueva versión de la plantilla.

templates.fromSpec

templates.fromSpec(params) → Promise<Template>

Renderiza una SPEC de json-render y guarda el resultado como una nueva plantilla (o nueva versión), con un key generado automáticamente.

Parámetros
ParámetroTipoDescripción
nameObligatoriostringNombre de la plantilla. Debe ser único dentro de la organización.
specObligatorioobjectUna SPEC de json-render — { root, elements, state } — la misma estructura usada en templates.render.
subjectOpcionalstringAsunto de la plantilla.

Devuelve: La plantilla creada a partir de la SPEC renderizada, con key generado automáticamente.

const template = await publiq.templates.fromSpec({
name: 'newsletter-july',
subject: 'Your July newsletter',
spec,
});
console.log(template.key);
fromSpec (Python: from_spec) requiere el feature de plan ai_builder, igual que render. A diferencia de render, aquí el resultado se guarda como plantilla.

Los ejemplos muestran Node, Python y PHP. En Python los métodos son snake_case (ej.: cancel_run, from_spec) y reciben un dict; en PHP son camelCase y reciben un array asociativo. Las claves del cuerpo siempre son camelCase (templateKey, firstName, scheduledAt) — las respuestas de la API vienen en snake_case.

Plantillas — Publiq Docs