API de Modelos de E-mail

A API de Modelos de E-mail gerencia os modelos de e-mail reutilizáveis por trás das predefinições de e-mail de uma aplicação — os mesmos modelos que você constrói no editor de e-mail do Painel de Controle. Cada modelo 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 modelo através do Notify (payload de e-mail email_template) ou de um ponto Enviar e-mail da Customer Journey.

URL Base

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

Todos os endpoints são servidos sobre 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 o seu token da API do Servidor:

Authorization: Api SEU_TOKEN_DE_API

Convenções

Nomenclatura de campos: os corpos das solicitações e os parâmetros de consulta/caminho aceitam lowerCamelCase (por exemplo, previewSettings, searchByLabel, includeHtml) — o servidor decodifica ambos os formatos. 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 formato.
code: cada resposta de modelo carrega o código da sua predefinição de e-mail conectada, não um ID de modelo interno. Passe este mesmo código para Get, Update, Delete e para as APIs de mensagens/jornada 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 modelo ainda usado por uma jornada).
`401 Unauthorized`	Cabeçalho `Authorization` ausente ou inválido.
`403 Forbidden`	A aplicação ou predefinição não pertence à conta do chamador.
`404 Not Found`	O modelo, predefinição ou aplicação 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 modelo de e-mail
`GET`	`/api/email_templates`	Listar os modelos de e-mail de uma aplicação
`GET`	`/api/email_templates/{code}`	Obter um único modelo de e-mail
`PUT`	`/api/email_templates/{code}`	Atualizar um modelo de e-mail
`DELETE`	`/api/email_templates/{code}`	Excluir um modelo de e-mail
`POST`	`/api/email_templates:clone`	Clonar um modelo de e-mail em uma aplicação

Criar

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

POST /api/email_templates

Corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`application`	string	Sim	O código da aplicação Pushwoosh para criar o modelo.
`name`	string	Sim	Nome do modelo, 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 de strings	Não	Nomes de categorias para marcar o modelo.
`previewSettings`	object	Não	Configurações arbitrárias de visualização do editor, armazenadas e retornadas como estão.
`system`	boolean	Não	Marca o modelo como um modelo de sistema — um recurso interno, por exemplo, um fragmento de bloco sincronizado. Modelos de sistema são ocultos 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": "E-mail de boas-vindas",
  "label": "onboarding",
  "categories": ["ciclo de vida"],
  "content": {
    "senderInfo": {
      "from": { "email": "ola@acme.com", "name": "Acme" },
      "replyTo": { "email": "suporte@acme.com", "name": "Suporte Acme" }
    },
    "subject": { "en": "Bem-vindo à Acme!", "default": "Bem-vindo à Acme!" },
    "pushwoosh": {
      "html": "<html><body>Bem-vindo, {name|string|aí}!</body></html>",
      "localizationData": { "default": { "name": "aí" } }
    }
  }
}

Resposta

Retorna { "email_template": { ... } } — o objeto de modelo 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 modelos de e-mail de uma aplicação — 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 da aplicação para listar os modelos.
`orderBy`	string	Não	`NAME` (padrão), `CREATED` ou `UPDATED`.
`orderDirection`	string	Não	`ASC` (padrão) ou `DESC`.
`page`	integer	Não	Índice da 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 modelo ou seu código — qualquer uma das correspondências é 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	Usa correspondência exata em vez de substring para `searchByLabel`.
`searchByCategory`	array de 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 de objetos	A página atual de objetos de modelo 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 modelos que correspondem aos filtros, em todas as páginas.

Exemplo de resposta

{
  "email_templates": [
    { "code": "AAAAA-BBBBB", "name": "E-mail de boas-vindas", "label": "onboarding", "categories": ["ciclo de vida"] }
  ],
  "page": 0,
  "per_page": 100,
  "total": 1
}

Get

Retorna um único modelo de e-mail pelo 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 modelo (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 modelo.

Resposta

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

Atualizar

Atualiza um modelo 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 modelo 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 o conteúdo armazenado por completo. Omita para deixar o conteúdo inalterado.
`label`	string	Não	Novo rótulo. Sempre sobrescrito — omita ou envie `""` para limpá-lo.
`categories`	array de strings	Não	Novo conjunto completo de nomes de categorias. 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": "E-mail de boas-vindas v2",
  "label": "onboarding",
  "content": {
    "senderInfo": { "from": { "email": "ola@acme.com", "name": "Acme" } },
    "subject": { "default": "Bem-vindo à Acme — atualizado!" },
    "pushwoosh": {
      "html": "<html>...</html>",
      "localizationData": {}
    }
  }
}

Resposta

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

Excluir

Exclui um modelo 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 modelo a ser excluído.

Resposta

Um objeto vazio em caso de sucesso: {}.

Clonar

Clona um modelo de e-mail — seu conteúdo e predefinição — em uma aplicação 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 modelo (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 da aplicação de destino. Pode ser a mesma aplicação ou uma diferente pertencente à mesma conta.
`name`	string	Não	Nome para o clone, 1–255 caracteres. O padrão é o nome do modelo de origem.

Exemplo de solicitação

{
  "emailPresetCode": "AAAAA-BBBBB",
  "application": "YYYYY-YYYYY",
  "name": "E-mail de boas-vindas (cópia)"
}

Resposta

Campo	Tipo	Descrição
`email_preset_code`	string	O `code` do novo modelo — 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 ambos os formatos na entrada.

Objeto de modelo de e-mail

Campo	Tipo	Descrição
`code`	string	Código da predefinição de e-mail conectada. Identifica este modelo em todos os outros lugares da API.
`name`	string	Nome do modelo.
`label`	string	Rótulo de texto livre.
`categories`	array de strings	Nomes das categorias.
`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 arbitrárias de visualização do editor.
`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": "Assunto", "default": "Assunto" }`.
`unlayer` / `pushwoosh` / `smartcards`	object	O conteúdo do editor. Exatamente um destes deve ser definido — ele seleciona qual editor produziu (e renderizará) o modelo. 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 modelos 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 do próprio 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 estrutura 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. O subject recebe o mesmo tratamento. Isso é diferente do Clone, que mantém apenas esse 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 o Update armazena exatamente o que você envia: a chave en original desaparece 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 de localization_data pode incluir tags de Conteúdo Dinâmico, por exemplo, {name|string|aí} — 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