Obtener el formato de las plantillas de email

GET/v1/mail-templates/format

Para desarrolladores

Descripción

Devuelve la especificación del documento que una plantilla guarda en config: la explicación del formato y las reglas que revisa la validación, su JSON Schema 2020-12 (la estructura, el tipo y el valor por defecto de cada campo) y la lista de tipos de módulo. A pedido incluye también un ejemplo del anidamiento (skeleton): la página, una fila de contenido y el pie con los tres enlaces especiales.

Es la referencia para escribir o modificar el config que se envía a POST /v1/mail-templates y a PATCH /v1/mail-templates/{template_id}, y para leer los findings que devuelve POST /v1/mail-templates/validate. La misma especificación está publicada en Formato de plantillas.

Guía relacionada

• Plantillas por API — Cree y edite plantillas desde su integración.
• Plantillas de email — Cree y reutilice el contenido de sus envíos.

Autenticación

Authorizationbearer tokenheaderobligatorio

API key con scope templates:read. Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Request

Query params:

langstring, enum: `es | en`

Idioma del texto de format. Por defecto es. El resto de la respuesta es igual en los dos idiomas, incluidos los campos, los valores, los códigos de validación y los niveles (error, warning). Un valor fuera de la lista responde 422.

includestring, enum: `skeleton`

Con skeleton, la respuesta trae el ejemplo del anidamiento en skeleton. Sin él, skeleton es null.

schemastring, enum: `full | structure`

full (por defecto) entrega el schema completo. structure entrega solo el anidamiento (página, filas, columnas y el sobre de cada módulo); el schema de cada tipo de módulo se consulta en GET /v1/mail-templates/format/modules/{kind}.

Response

200 OKDevuelve un objeto con los campos que siguen.

formatstringsiempre presente

Especificación del documento, en Markdown y en el idioma pedido en lang: estructura de filas, columnas y módulos, identificadores (uuid), tipos de módulo, tipos de campo y la tabla de reglas de validación con su nivel.

schemaobjectsiempre presente

JSON Schema 2020-12 del documento. Es cerrado: un campo que no figura en él se rechaza. El default de cada campo es el valor con que se guarda cuando el documento lo omite; un campo con x-initial y sin default hereda del nivel de arriba y no es obligatorio.

skeletonobject | nullsiempre presente

Ejemplo del anidamiento, válido y sin advertencias, con los valores iniciales de cada bloque escritos (los colores con que el editor crea un bloque nuevo). null salvo con include=skeleton.

modulesobject[]siempre presente

Tipos de módulo disponibles.

kindstringsiempre presente

Nombre corto del tipo. Es el valor que se usa en GET /v1/mail-templates/format/modules/{kind}.

typestringsiempre presente

Valor de type de un módulo de este tipo en el documento.

content_keystringsiempre presente

Clave de descriptor donde va el contenido del módulo.

Errores

Código	Cuándo
422	lang, include o schema tienen un valor fuera de su lista. En errors[], un ítem con el pointer del parámetro (/lang, /include, /schema) y code literal_error.

Detalle en Errores genéricos.

Notas

• La respuesta es la misma para toda instancia y cambia solo cuando cambia el formato. Puede guardarla en caché del lado de su integración.
• Un campo que el documento omite se guarda con su default, si lo tiene. Es el mismo valor con que se dibuja, así que el correo no cambia; lo que cambia es que config, al leerlo de vuelta, trae el campo escrito. Un campo que hereda (con x-initial y sin default) no se escribe: queda ausente y toma el valor de la fila o de la página.
• El schema sirve para validar del lado de su integración con cualquier validador de JSON Schema 2020-12. La validación del servidor revisa además reglas que un schema no expresa (identificadores únicos, ancho de las columnas, enlaces obligatorios del pie), así que use POST /v1/mail-templates/validate antes de guardar.
• Para empezar, parta de un documento que existe: una plantilla de la biblioteca o el config de una plantilla suya. El skeleton sirve cuando no queda claro cómo se anidan filas, columnas y módulos, o cuando la validación informa un error de estructura.
• El recorrido completo, desde leer el formato hasta guardar una plantilla, está en Plantillas por API.

Request

curl -X GET "https://$API_HOST/v1/mail-templates/format?lang=en" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"format": "# El formato del documento de plantilla\n\n…",
"schema": {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:fidelizador:template-document",
  "if": {
    "…": "…"
  },
  "then": {
    "$ref": "#/$defs/raw_document"
  },
  "else": {
    "$ref": "#/$defs/document"
  },
  "$defs": {
    "row": {
      "…": "…"
    },
    "module_button": {
      "…": "…"
    },
    "color": {
      "…": "…"
    }
  }
},
"skeleton": null,
"modules": [
  {
    "kind": "heading",
    "type": "fidelizador-modules-heading",
    "content_key": "heading"
  },
  {
    "kind": "menu",
    "type": "fidelizador-modules-menu",
    "content_key": "menuItemsList"
  }
]
}