API de plantillas de correo electrónico

La API de plantillas de correo electrónico gestiona las plantillas de correo electrónico reutilizables que se encuentran detrás de los preajustes de correo electrónico de una aplicación, las mismas plantillas que usted crea en el editor de correo electrónico del Panel de Control. Cada plantilla almacena asuntos por configuración regional, información del remitente y contenido del editor, y se identifica por el código del preajuste de correo electrónico al que está conectada. Utilice ese código para enviar la plantilla a través de Notify (carga útil de correo electrónico email_template) o un punto de Customer Journey Enviar correo electrónico.

URL base

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

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

Autenticación

Cada solicitud debe incluir un encabezado Authorization con su 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 formas. Las respuestas siempre se codifican utilizando los nombres de campo del proto, en snake_case (per_page, email_template, sender_info, preview_settings, etc.). Los ejemplos de respuesta y la referencia de objetos a continuación utilizan esa forma.
• code: cada respuesta de plantilla lleva el código de su preajuste de correo electrónico conectado, no un ID de plantilla interno. Pase este mismo código a Get, Update, Delete y a las API de mensajería/journey mencionadas anteriormente.
• Campos no poblados: las respuestas incluyen todos los campos, incluso cuando están vacíos o tienen valor cero.

Respuestas de error

Estado HTTP	Significado
400 Bad Request	Argumento no válido: falta un campo obligatorio o está mal formado, o una precondición falló (por ejemplo, eliminar una plantilla que todavía está siendo utilizada por un journey).
401 Unauthorized	Encabezado Authorization faltante o no válido.
403 Forbidden	La aplicación o el preajuste no pertenecen 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 correo electrónico
GET	/api/email_templates	Listar las plantillas de correo electrónico de una aplicación
GET	/api/email_templates/{code}	Obtener una única plantilla de correo electrónico
PUT	/api/email_templates/{code}	Actualizar una plantilla de correo electrónico
DELETE	/api/email_templates/{code}	Eliminar una plantilla de correo electrónico
POST	/api/email_templates:clone	Clonar una plantilla de correo electrónico en una aplicación

Crear

Crea una nueva plantilla de correo electrónico (su contenido de editor más un preajuste de correo electrónico 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 se creará la plantilla.
name	string	Sí	Nombre de la plantilla, de 1 a 255 caracteres.
content	object	Sí	El objeto de contenido de correo electrónico.
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, por ejemplo, un fragmento de bloque sincronizado. Las plantillas de sistema están ocultas de List (ver nota a continuación), pero siguen siendo 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 correo electrónico creado, pero sin content (este endpoint no lo devuelve). Llame a Get con el code devuelto si necesita leer el contenido de vuelta.

Listar

Lista las plantillas de correo electrónico 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 las 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%) con el nombre de la plantilla o su código; cualquiera de las dos coincidencias es suficiente.
searchByLabel	string	No	Coincidencia de subcadena en la etiqueta (like %label%), o coincidencia exacta cuando strictSearchByLabel es true.
strictSearchByLabel	boolean	No	Utiliza coincidencia exacta en lugar de subcadena para searchByLabel.
searchByCategory	array of strings	No	Repita el parámetro para filtrar por varias categorías, por ejemplo, ?searchByCategory=lifecycle&searchByCategory=promo.

Nota

Las plantillas de sistema (creadas con system: true) nunca se devuelven en List, independientemente de los filtros.

Respuesta

Campo	Tipo	Descripción
email_templates	array of objects	La página actual de objetos de plantilla de correo electrónico. 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 correo electrónico por su código, incluyendo la información del remitente, los asuntos por configuración regional 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 correo electrónico 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ézcalo en false para omitirlo; generalmente representa más de la mitad de la carga útil, y el contenido del editor ya describe la plantilla.

Respuesta

Devuelve { "email_template": { ... } }, el objeto de plantilla de correo electrónico completo.

Actualizar

Actualiza una plantilla de correo electrónico 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, de 1 a 255 caracteres. Omita para mantener el nombre actual.
content	object	No	Nuevo objeto de contenido de correo electrónico, reemplazando el contenido almacenado por completo. Omita para dejar el contenido sin cambios.
label	string	No	Nueva etiqueta. Siempre se sobrescribe; omita o envíe "" para borrarla.
categories	array of strings	No	Nuevo conjunto completo de nombres de categorías. Omita para dejar las categorías sin cambios; envíe [] para borrarlas.
previewSettings	object	No	Nuevas configuraciones de vista previa. Omita 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 correo electrónico actualizado, también sin content. Llame a Get si necesita leer el contenido de vuelta.

Eliminar

Elimina una plantilla de correo electrónico 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 en pausa; elimine o redirija 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 correo electrónico (su contenido y preajuste) en una aplicación de destino, opcionalmente con un nuevo nombre.

POST /api/email_templates:clone

Nota

Solo se conserva el asunto de la configuración regional default (o en, utilizado como alternativa) 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. Se llama emailPresetCode aquí porque es el código del preajuste de correo electrónico conectado; consulte 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, de 1 a 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 del proto en snake_case (consulte Convenciones). Cuando envía 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 formas en la entrada.

Objeto de plantilla de correo electrónico

Campo	Tipo	Descripción
code	string	Código del preajuste de correo electrónico 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 las categorías.
content	object	El objeto de contenido de correo electrónico. 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 correo electrónico

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

Precaución

El proto también define un tipo de editor raw (HTML por configuración regional sin estado de editor). Actualmente, la API lo rechaza en Create/Update con 400 Bad Request: raw content not supported; no lo utilice.

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 mediante programación/API.
smartcards	html, localization_data, content	content, localization_data	Editor de bloques de Smart Cards; content es su JSON específico del editor.

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

Nota

Cada vez que la API devuelve content (actualmente solo en Get, ya que Create y Update no lo devuelven), garantiza que una configuración regional se expone como default: si no envió una clave default usted mismo, promueve en (o, en su defecto, la primera clave de configuración regional que aparezca) a default, renombrándola; todas las demás configuraciones regionales que envió se mantienen tal cual. subject recibe el mismo tratamiento. Esto es diferente de Clone, que solo conserva ese valor de configuración regional predeterminado y descarta el resto.

Este cambio de nombre solo se aplica al construir la respuesta, pero no se deshace al escribir. Si toma una respuesta de Get tal cual y la envía directamente a Update, la clave promovida (por ejemplo, en) ahora es literalmente default, y Update almacena exactamente lo que envía: la clave en original desaparece a partir de entonces, permanentemente. Si necesita conservar la clave de configuración regional original, cámbiele el nombre de default a su valor original usted mismo antes de llamar a Update.

El texto dentro de html o un valor de localization_data puede incluir etiquetas de Contenido Dinámico, por ejemplo, {name|string|there}; estas se resuelven con las etiquetas del dispositivo del destinatario cuando se envía realmente el correo electrónico. Esta API no las resuelve; simplemente almacena y devuelve cualquier texto que usted ponga 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 correo electrónico válidas.

Relacionado

Notify

Email payload reference

Customer Journey point reference