API de Plantillas de Email

La API de Plantillas de Email gestiona las plantillas de email reutilizables detrás de los preajustes de email de una aplicación — las mismas plantillas que construyes en el editor de email del Panel de Control. Cada plantilla almacena asuntos por localidad, información del remitente y contenido del editor, y se identifica por el código del preajuste de email al que está conectada. Usa ese código para enviar la plantilla a través de Notify (payload de email email_template) o un punto Enviar email de Customer Journey.

URL Base

https://rpc-api.svc-nue.pushwoosh.com

Todos los endpoints se sirven a través de HTTPS. Las solicitudes y respuestas usan application/json a menos que se indique lo contrario.

Autenticación

Cada solicitud debe incluir un encabezado Authorization con tu token de API del Servidor:

Authorization: Api YOUR_API_TOKEN

Convenciones

• Nomenclatura de campos: los cuerpos de las solicitudes y los parámetros de consulta/ruta aceptan lowerCamelCase (por ejemplo, previewSettings, searchByLabel, includeHtml) — el servidor decodifica cualquiera de las dos mayúsculas. Las respuestas siempre se codifican usando los nombres de campo de proto, en snake_case (per_page, email_template, sender_info, preview_settings, y así sucesivamente). Los ejemplos de respuesta y la referencia de objetos a continuación usan esa nomenclatura.
• code: cada respuesta de plantilla lleva el código de su preajuste de email conectado, no un ID de plantilla interno. Pasa este mismo código a Get, Update, Delete, y a las APIs de mensajería/journey mencionadas anteriormente.
• Campos no poblados: las respuestas incluyen todos los campos, incluso cuando están vacíos o con valor cero.

Respuestas de error

Estado HTTP	Significado
400 Bad Request	Argumento inválido — falta un campo requerido o está mal formado, o una precondición falló (por ejemplo, eliminar una plantilla que todavía está en uso por un journey).
401 Unauthorized	Encabezado Authorization faltante o inválido.
403 Forbidden	La aplicación o el preajuste no pertenece a la cuenta del solicitante.
404 Not Found	No se encontró la plantilla, el preajuste o la aplicación.
500 Internal Server Error	Falla inesperada del lado del servidor.

Endpoints

Método	Ruta	Descripción
POST	/api/email_templates	Crear una nueva plantilla de email
GET	/api/email_templates	Listar las plantillas de email de una aplicación
GET	/api/email_templates/{code}	Obtener una única plantilla de email
PUT	/api/email_templates/{code}	Actualizar una plantilla de email
DELETE	/api/email_templates/{code}	Eliminar una plantilla de email
POST	/api/email_templates:clone	Clonar una plantilla de email en una aplicación

Crear

Crea una nueva plantilla de email — su contenido de editor más un preajuste de email conectado — en una aplicación, y devuelve el código de plantilla generado.

POST /api/email_templates

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	El código de aplicación de Pushwoosh en el que crear la plantilla.
name	string	Sí	Nombre de la plantilla, 1–255 caracteres.
content	object	Sí	El objeto de contenido de email.
label	string	No	Etiqueta de texto libre, hasta 255 caracteres.
categories	array of strings	No	Nombres de categorías para etiquetar la plantilla.
previewSettings	object	No	Configuraciones de vista previa del editor arbitrarias, almacenadas y devueltas tal cual.
system	boolean	No	Marca la plantilla como una plantilla de sistema — una característica interna, p. ej., un fragmento de bloque sincronizado. Las plantillas de sistema están ocultas de List (ver nota a continuación), pero permanecen accesibles por código. El valor predeterminado es false.

Ejemplo de solicitud

{
  "application": "XXXXX-XXXXX",
  "name": "Welcome email",
  "label": "onboarding",
  "categories": ["lifecycle"],
  "content": {
    "senderInfo": {
      "from": { "email": "hello@acme.com", "name": "Acme" },
      "replyTo": { "email": "support@acme.com", "name": "Acme Support" }
    },
    "subject": { "en": "Welcome to Acme!", "default": "Welcome to Acme!" },
    "pushwoosh": {
      "html": "<html><body>Welcome, {name|string|there}!</body></html>",
      "localizationData": { "default": { "name": "there" } }
    }
  }
}

Respuesta

Devuelve { "email_template": { ... } } — el objeto de plantilla de email creado, pero sin content (este endpoint no lo devuelve). Llama a Get con el code devuelto si necesitas leer el contenido de vuelta.

Listar

Lista las plantillas de email de una aplicación — solo metadatos, sin contenido — con paginación, ordenación y filtrado por nombre, etiqueta o categoría.

GET /api/email_templates

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
application	string	Sí	El código de la aplicación para la cual listar plantillas.
orderBy	string	No	NAME (predeterminado), CREATED, o UPDATED.
orderDirection	string	No	ASC (predeterminado) o DESC.
page	integer	No	Índice de página basado en cero.
perPage	integer	No	Tamaño de la página. El valor predeterminado es 100 cuando se omite o es 0. Este endpoint no impone un máximo explícito.
searchByName	string	No	Coincidencia de subcadena (like %value%) contra el nombre de la plantilla o su código — cualquiera de las coincidencias es suficiente.
searchByLabel	string	No	Coincidencia de subcadena en la etiqueta (like %label%), o coincidencia exacta cuando strictSearchByLabel es true.
strictSearchByLabel	boolean	No	Usa coincidencia exacta en lugar de subcadena para searchByLabel.
searchByCategory	array of strings	No	Repite el parámetro para filtrar por varias categorías, p. ej., ?searchByCategory=lifecycle&searchByCategory=promo.

Nota

Las plantillas de sistema (creadas con system: true) nunca son devueltas por List, independientemente de los filtros.

Respuesta

Campo	Tipo	Descripción
email_templates	array of objects	La página actual de objetos de plantilla de email. content es null en cada elemento.
page	integer	El índice de página devuelto.
per_page	integer	El tamaño de página utilizado para esta respuesta.
total	integer	Número total de plantillas que coinciden con los filtros, en todas las páginas.

Ejemplo de respuesta

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "Welcome email", "label": "onboarding", "categories": ["lifecycle"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Obtener

Devuelve una única plantilla de email por su código, incluyendo información del remitente, asuntos por localidad y el contenido completo del editor.

GET /api/email_templates/{code}

Parámetros de ruta

Parámetro	Tipo	Descripción
code	string	El código de la plantilla (el código de su preajuste de email conectado).

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
includeHtml	boolean	No	Si se debe devolver el html renderizado junto con el contenido del editor. El valor predeterminado es true. Establécelo en false para omitirlo — típicamente es más de la mitad del payload, y el contenido del editor ya describe la plantilla.

Respuesta

Devuelve { "email_template": { ... } }, el objeto de plantilla de email completo.

Actualizar

Actualiza una plantilla de email existente por código, sobrescribiendo los campos proporcionados.

PUT /api/email_templates/{code}

Parámetros de ruta

Parámetro	Tipo	Descripción
code	string	El código de la plantilla a actualizar.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
name	string	No	Nuevo nombre, 1–255 caracteres. Omite para mantener el nombre actual.
content	object	No	Nuevo objeto de contenido de email, reemplazando el contenido almacenado por completo. Omite para dejar el contenido sin cambios.
label	string	No	Nueva etiqueta. Siempre se sobrescribe — omite o envía "" para borrarla.
categories	array of strings	No	Nuevo conjunto completo de nombres de categorías. Omite para dejar las categorías sin cambios; envía [] para borrarlas.
previewSettings	object	No	Nuevas configuraciones de vista previa. Omite para dejar sin cambios.

Ejemplo de solicitud

{
  "name": "Welcome email v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "hello@acme.com", "name": "Acme" } },
    "subject": { "default": "Welcome to Acme — updated!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

Respuesta

Devuelve { "email_template": { ... } } — el objeto de plantilla de email actualizado, también sin content. Llama a Get si necesitas leer el contenido de vuelta.

Eliminar

Elimina una plantilla de email y su preajuste conectado por código, eliminando el contenido almacenado.

DELETE /api/email_templates/{code}

Precaución

Falla con 400 Bad Request si la plantilla es utilizada por un punto send_email en un journey en ejecución o pausado — elimina o reasigna ese punto primero a través de Update. Esta acción no se puede deshacer.

Parámetros de ruta

Parámetro	Tipo	Descripción
code	string	El código de la plantilla a eliminar.

Respuesta

Un objeto vacío en caso de éxito: {}.

Clonar

Clona una plantilla de email — su contenido y preajuste — en una aplicación de destino, opcionalmente bajo un nuevo nombre.

POST /api/email_templates:clone

Nota

Solo se conserva el asunto de la localidad default (o en, usado como respaldo) en el clon; otros asuntos localizados se eliminan.

Cuerpo de la solicitud

Parámetro	Tipo	Requerido	Descripción
emailPresetCode	string	Sí	El code de la plantilla (devuelto por Create, Get, List, o Update) a clonar. Nombrado emailPresetCode aquí porque es el código del preajuste de email conectado — ver Convenciones.
application	string	Sí	Código de la aplicación de destino. Puede ser la misma aplicación, o una diferente propiedad de la misma cuenta.
name	string	No	Nombre para el clon, 1–255 caracteres. El valor predeterminado es el nombre de la plantilla de origen.

Ejemplo de solicitud

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "Welcome email (copy)"
}

Respuesta

Campo	Tipo	Descripción
email_preset_code	string	El code de la nueva plantilla — el mismo identificador que Get/Update/Delete llaman code.

Referencia de objetos

Los nombres de los campos a continuación coinciden con lo que Get, List, Update, y Create realmente devuelven — nombres de campo de proto en snake_case (ver Convenciones). Cuando envías estas mismas estructuras de vuelta en un cuerpo de solicitud (Create, Update), la forma lowerCamelCase utilizada en los ejemplos de solicitud anteriores también funciona; el servidor acepta cualquiera de las dos mayúsculas en la entrada.

Objeto de plantilla de email

Campo	Tipo	Descripción
code	string	Código del preajuste de email conectado. Identifica esta plantilla en cualquier otro lugar de la API.
name	string	Nombre de la plantilla.
label	string	Etiqueta de texto libre.
categories	array of strings	Nombres de categorías.
content	object	El objeto de contenido de email. Poblado solo por Get; null en las respuestas de Create, List, y Update.
preview_settings	object	Configuraciones de vista previa del editor arbitrarias.
created	string (RFC 3339)	Marca de tiempo de creación.
updated	string (RFC 3339)	Marca de tiempo de la última actualización.

Objeto de contenido de email

Campo	Tipo	Descripción
sender_info	object	Objeto de información del remitente — direcciones from y reply_to.
subject	object (map)	Asunto por localidad, p. ej., { "en": "Subject", "default": "Subject" }.
unlayer / pushwoosh / smartcards	object	El contenido del editor. Exactamente uno de estos debe estar establecido — selecciona qué editor produjo (y renderizará) la plantilla. Ver tipos de editor a continuación.

Precaución

El proto también define un tipo de editor raw (HTML por localidad sin estado de editor). La API actualmente lo rechaza en Create/Update con 400 Bad Request: raw content not supported — no lo uses.

Tipos de editor

Tipo	Campo	Subcampos requeridos	Descripción
unlayer	html, localization_data, editor_config	editor_config, localization_data	Editor de bloques de arrastrar y soltar (Unlayer). editor_config es el JSON de diseño de Unlayer.
pushwoosh	html, localization_data	localization_data	Editor propio de Pushwoosh basado en HTML. Recomendado para plantillas creadas programáticamente/API.
smartcards	html, localization_data, content	content, localization_data	Editor de bloques Smart Cards; content es su JSON específico del editor.

En cada tipo, html es la salida renderizada. localization_data es el contenido por localidad propio de ese editor: un objeto con clave por código de localidad (en, es, default, …), donde cada valor es la copia de esa localidad de los campos del editor. Su forma interna es específica del editor y opaca para esta API — la API la almacena y devuelve tal cual. Es requerido en Create/Update para cada tipo (envía {} si no hay nada que localizar).

Nota

Cada vez que la API devuelve content (actualmente solo Get, ya que Create y Update no lo devuelven), garantiza que una localidad se exponga como default: si no enviaste una clave default tú mismo, promueve en (o, en su defecto, la primera clave de localidad que aparezca) a default, renombrándola — cada otra localidad que enviaste se mantiene tal cual. subject recibe el mismo tratamiento. Esto es diferente de Clone, que mantiene solo ese valor de localidad predeterminado y descarta el resto.

Este renombramiento solo se aplica al construir la respuesta — pero no se deshace al escribir. Si tomas una respuesta de Get tal cual y la envías directamente a Update, la clave promovida (p. ej., en) es ahora literalmente default, y Update almacena exactamente lo que envías: la clave original en desaparece a partir de entonces, permanentemente. Si necesitas mantener la clave de localidad original, renombra default de nuevo a ella tú mismo antes de llamar a Update.

El texto dentro de html o un valor de localization_data puede incluir etiquetas de Contenido Dinámico, p. ej., {name|string|there} — esas se resuelven contra las Tags del dispositivo del destinatario cuando el email se envía realmente. Esta API no las resuelve; simplemente almacena y devuelve cualquier texto que pongas allí.

Objeto de información del remitente

Campo	Tipo	Descripción
from	object	{ "email": string, "name": string } — dirección del remitente.
reply_to	object	{ "email": string, "name": string } — dirección de respuesta.

Ambos subcampos email, cuando no están vacíos, deben ser direcciones de email válidas.

Relacionado

Notify

Referencia de payload de email

Referencia de puntos de Customer Journey