API de Templates de E-mail

A API de Templates de E-mail gerencia os templates de e-mail reutilizáveis por trás das predefinições de e-mail de um aplicativo — os mesmos templates que você cria no editor de e-mail do Painel de Controle. Cada template armazena assuntos por localidade, informações do remetente e conteúdo do editor, e é identificado pelo código da predefinição de e-mail à qual está conectado. Use esse código para enviar o template através do Notify (payload de e-mail email_template) ou de um ponto de Envio de e-mail da Customer Journey.

URL Base

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

Todos os endpoints são servidos via HTTPS. As solicitações e respostas usam application/json, a menos que seja indicado o contrário.

Autenticação

Cada solicitação deve incluir um cabeçalho Authorization com seu token da API do Servidor:

Authorization: Api YOUR_API_TOKEN

Convenções

Nomenclatura de campos: corpos de solicitação e parâmetros de consulta/caminho aceitam lowerCamelCase (por exemplo, previewSettings, searchByLabel, includeHtml) — o servidor decodifica qualquer um dos casos. As respostas são sempre codificadas usando os nomes de campo do proto, em snake_case (per_page, email_template, sender_info, preview_settings, e assim por diante). Os exemplos de resposta e a referência de objeto abaixo usam esse caso.
code: cada resposta de template carrega o código de sua predefinição de e-mail conectada, não um ID de template interno. Passe este mesmo código para Get, Update, Delete e para as APIs de mensagens/journey acima.
Campos não preenchidos: as respostas incluem todos os campos, mesmo quando vazios ou com valor zero.

Respostas de erro

Status HTTP	Significado
`400 Bad Request`	Argumento inválido — um campo obrigatório está ausente ou malformado, ou uma pré-condição falhou (por exemplo, excluir um template ainda usado por uma journey).
`401 Unauthorized`	Cabeçalho de Autorização ausente ou inválido.
`403 Forbidden`	O aplicativo ou predefinição não pertence à conta do chamador.
`404 Not Found`	O template, predefinição ou aplicativo não foi encontrado.
`500 Internal Server Error`	Falha inesperada no lado do servidor.

Endpoints

Método	Caminho	Descrição
`POST`	`/api/email_templates`	Criar um novo template de e-mail
`GET`	`/api/email_templates`	Listar os templates de e-mail de um aplicativo
`GET`	`/api/email_templates/{code}`	Obter um único template de e-mail
`PUT`	`/api/email_templates/{code}`	Atualizar um template de e-mail
`DELETE`	`/api/email_templates/{code}`	Excluir um template de e-mail
`POST`	`/api/email_templates:clone`	Clonar um template de e-mail em um aplicativo

Criar

Cria um novo template de e-mail — seu conteúdo do editor mais uma predefinição de e-mail conectada — em um aplicativo, e retorna o código do template gerado.

POST /api/email_templates

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`application`	string	Sim	O código do aplicativo Pushwoosh no qual criar o template.
`name`	string	Sim	Nome do template, 1–255 caracteres.
`content`	object	Sim	O objeto de conteúdo de e-mail.
`label`	string	Não	Rótulo de texto livre, até 255 caracteres.
`categories`	array of strings	Não	Nomes de categoria para marcar o template.
`previewSettings`	object	Não	Configurações de visualização do editor arbitrárias, armazenadas e retornadas como estão.
`system`	boolean	Não	Marca o template como um template de sistema — um recurso interno, por exemplo, um fragmento de bloco sincronizado. Templates de sistema são ocultados de `List` (veja a nota abaixo), mas permanecem acessíveis por código. O padrão é `false`.

Exemplo de solicitação

{
  "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" } }
    }
  }
}

Resposta

Retorna { "email_template": { ... } } — o objeto de template de e-mail criado, mas sem content (este endpoint não o retorna). Chame Get com o code retornado se precisar ler o conteúdo de volta.

Listar

Lista os templates de e-mail de um aplicativo — apenas metadados, sem conteúdo — com paginação, ordenação e filtragem por nome, rótulo ou categoria.

GET /api/email_templates

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`application`	string	Sim	O código do aplicativo para o qual listar os templates.
`orderBy`	string	Não	`NAME` (padrão), `CREATED` ou `UPDATED`.
`orderDirection`	string	Não	`ASC` (padrão) ou `DESC`.
`page`	integer	Não	Índice de página baseado em zero.
`perPage`	integer	Não	Tamanho da página. O padrão é `100` quando omitido ou `0`. Este endpoint não impõe um máximo explícito.
`searchByName`	string	Não	Correspondência de substring (`like %value%`) com o nome do template ou seu código — qualquer correspondência é suficiente.
`searchByLabel`	string	Não	Correspondência de substring no rótulo (`like %label%`), ou correspondência exata quando `strictSearchByLabel` é `true`.
`strictSearchByLabel`	boolean	Não	Usar correspondência exata em vez de substring para `searchByLabel`.
`searchByCategory`	array of strings	Não	Repita o parâmetro para filtrar por várias categorias, por exemplo, `?searchByCategory=lifecycle&searchByCategory=promo`.

Resposta

Campo	Tipo	Descrição
`email_templates`	array of objects	A página atual de objetos de template de e-mail. `content` é `null` em todos os itens.
`page`	integer	O índice da página retornada.
`per_page`	integer	O tamanho da página usado para esta resposta.
`total`	integer	Número total de templates que correspondem aos filtros, em todas as páginas.

Exemplo de resposta

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

Obter

Retorna um único template de e-mail por seu código, incluindo informações do remetente, assuntos por localidade e o conteúdo completo do editor.

GET /api/email_templates/{code}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`code`	string	O código do template (o código da predefinição de e-mail conectada).

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`includeHtml`	boolean	Não	Se deve retornar o `html` renderizado junto com o conteúdo do editor. O padrão é `true`. Defina como `false` para ignorá-lo — geralmente representa mais da metade do payload, e o conteúdo do editor já descreve o template.

Resposta

Retorna { "email_template": { ... } }, o objeto de template de e-mail completo.

Atualizar

Atualiza um template de e-mail existente por código, sobrescrevendo os campos fornecidos.

PUT /api/email_templates/{code}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`code`	string	O código do template a ser atualizado.

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`name`	string	Não	Novo nome, 1–255 caracteres. Omita para manter o nome atual.
`content`	object	Não	Novo objeto de conteúdo de e-mail, substituindo completamente o conteúdo armazenado. Omita para deixar o conteúdo inalterado.
`label`	string	Não	Novo rótulo. Sempre sobrescrito — omita ou envie `""` para limpá-lo.
`categories`	array of strings	Não	Novo conjunto completo de nomes de categoria. Omita para deixar as categorias inalteradas; envie `[]` para limpá-las.
`previewSettings`	object	Não	Novas configurações de visualização. Omita para deixar inalterado.

Exemplo de solicitação

{
  "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": {}
    }
  }
}

Resposta

Retorna { "email_template": { ... } } — o objeto de template de e-mail atualizado, também sem content. Chame Get se precisar ler o conteúdo de volta.

Excluir

Exclui um template de e-mail e sua predefinição conectada por código, removendo o conteúdo armazenado.

DELETE /api/email_templates/{code}

Parâmetros de caminho

Parâmetro	Tipo	Descrição
`code`	string	O código do template a ser excluído.

Resposta

Um objeto vazio em caso de sucesso: {}.

Clonar

Clona um template de e-mail — seu conteúdo e predefinição — em um aplicativo de destino, opcionalmente com um novo nome.

POST /api/email_templates:clone

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`emailPresetCode`	string	Sim	O `code` do template (conforme retornado por `Create`, `Get`, `List` ou `Update`) a ser clonado. Nomeado `emailPresetCode` aqui porque é o código da predefinição de e-mail conectada — veja Convenções.
`application`	string	Sim	Código do aplicativo de destino. Pode ser o mesmo aplicativo ou um diferente pertencente à mesma conta.
`name`	string	Não	Nome para o clone, 1–255 caracteres. O padrão é o nome do template de origem.

Exemplo de solicitação

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

Resposta

Campo	Tipo	Descrição
`email_preset_code`	string	O `code` do novo template — o mesmo identificador que `Get`/`Update`/`Delete` chamam de `code`.

Referência de objeto

Os nomes dos campos abaixo correspondem ao que Get, List, Update e Create realmente retornam — nomes de campo do proto em snake_case (veja Convenções). Quando você envia essas mesmas estruturas de volta em um corpo de solicitação (Create, Update), a forma lowerCamelCase usada nos exemplos de solicitação acima também funciona; o servidor aceita qualquer um dos casos na entrada.

Objeto de template de e-mail

Campo	Tipo	Descrição
`code`	string	Código da predefinição de e-mail conectada. Identifica este template em todos os outros lugares da API.
`name`	string	Nome do template.
`label`	string	Rótulo de texto livre.
`categories`	array of strings	Nomes de categoria.
`content`	object	O objeto de conteúdo de e-mail. Preenchido apenas por `Get`; `null` nas respostas de `Create`, `List` e `Update`.
`preview_settings`	object	Configurações de visualização do editor arbitrárias.
`created`	string (RFC 3339)	Timestamp de criação.
`updated`	string (RFC 3339)	Timestamp da última atualização.

Objeto de conteúdo de e-mail

Campo	Tipo	Descrição
`sender_info`	object	Objeto de informações do remetente — endereços `from` e `reply_to`.
`subject`	object (map)	Assunto por localidade, por exemplo, `{ "en": "Subject", "default": "Subject" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	O conteúdo do editor. Exatamente um destes deve ser definido — ele seleciona qual editor produziu (e renderizará) o template. Veja tipos de editor abaixo.

Tipos de editor

Tipo	Campo	Subcampos obrigatórios	Descrição
`unlayer`	`html`, `localization_data`, `editor_config`	`editor_config`, `localization_data`	Editor de blocos de arrastar e soltar (Unlayer). `editor_config` é o JSON de design do Unlayer.
`pushwoosh`	`html`, `localization_data`	`localization_data`	Editor próprio da Pushwoosh baseado em HTML. Recomendado para templates criados programaticamente/via API.
`smartcards`	`html`, `localization_data`, `content`	`content`, `localization_data`	Editor de blocos Smart Cards; `content` é seu JSON específico do editor.

Em todos os tipos, html é a saída renderizada. localization_data é o conteúdo por localidade próprio daquele editor: um objeto com chaves de código de localidade (en, es, default, …), onde cada valor é a cópia daquela localidade dos campos do editor. Sua forma interna é específica do editor e opaca para esta API — a API a armazena e retorna como está. É obrigatório em Create/Update para todos os tipos (envie {} se não houver nada para localizar).

Sempre que a API retorna content (atualmente apenas em Get, já que Create e Update não o retornam), ela garante que uma localidade seja exposta como default: se você não enviou uma chave default, ela promove en (ou, na falta desta, a primeira chave de localidade que aparecer) para default, renomeando-a — todas as outras localidades que você enviou são mantidas como estão. subject recebe o mesmo tratamento. Isso é diferente de Clone, que mantém apenas aquele valor de localidade padrão e descarta o resto.

Essa renomeação é aplicada apenas ao construir a resposta — mas não é desfeita na escrita. Se você pegar uma resposta de Get como está e enviá-la diretamente para Update, a chave promovida (por exemplo, en) agora é literalmente default, e Update armazena exatamente o que você envia: a chave en original desaparece a partir de então, permanentemente. Se precisar manter a chave de localidade original, renomeie default de volta para ela antes de chamar Update.

O texto dentro de html ou de um valor localization_data pode incluir tags de Conteúdo Dinâmico, por exemplo, {name|string|there} — elas são resolvidas com base nas Tags do dispositivo do destinatário quando o e-mail é efetivamente enviado. Esta API não as resolve; ela apenas armazena e retorna qualquer texto que você colocar lá.

Objeto de informações do remetente

Campo	Tipo	Descrição
`from`	object	`{ "email": string, "name": string }` — endereço do remetente.
`reply_to`	object	`{ "email": string, "name": string }` — endereço de resposta.

Ambos os subcampos email, quando não vazios, devem ser endereços de e-mail válidos.

Relacionados

Notify

Referência de payload de e-mail

Referência de ponto da Customer Journey