VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/E-mail: envio, layout e logs

Layout do e-mail

Lê, pré-visualiza, altera e restaura o cabeçalho e o rodapé que envolvem todos os e-mails da loja.

O layout é a moldura comum a todos os e-mails: um HTML de cabeçalho (header) e um de rodapé (footer), por idioma. Alterá-lo muda a aparência de todos os modelos de uma vez, sem editar modelo por modelo. A loja nasce com um par para pt-BR e outro para en.

Os dois HTMLs são linhas de tabela (<tr>...</tr>), porque a plataforma os encaixa dentro de uma <table> central de 600 px. Aceitam os marcadores {{store_name}}, {{store_url}}, {{logo_url}}, {{support_email}} e {{current_year}}, preenchidos no envio com os dados da loja.

Listar os layouts

GET/api/v1/admin/email-layoutAdmin

Listar cabeçalhos e rodapés

Devolve todos os layouts da loja, ordenados por tipo e idioma. Não tem parâmetros.

200Layouts retornados

Campos da resposta

countinteger
Quantidade de layouts no vetor.
layouts[].iduuid
Id do layout.
layouts[].typestring
headerfooter
Posição do trecho.
layouts[].languagestring
pt-BRen
Idioma do layout.
layouts[].is_activeboolean
Se o layout está em uso.
layouts[].body_htmlstring
HTML do trecho, com marcadores {{...}}.
layouts[].created_atstring
RFC 3339, UTC.
layouts[].updated_atstring
RFC 3339, UTC.

Pré-visualizar

GET/api/v1/admin/email-layout/previewAdmin

Pré-visualizar um layout com dados de exemplo

Devolve o HTML de um dos layouts, já com os marcadores trocados por dados de exemplo (Venddor Store, https://example.com...), embrulhado numa página mínima para abrir no navegador. A prévia mostra o layout salvo; ela não aceita rascunho.

Parâmetros de consulta

typestringpadrão: header
headerfooter
Qual trecho mostrar.
languagestringpadrão: pt-BR
pt-BRen
Idioma do layout.
200Prévia gerada

Campos da resposta

htmlstring
Documento HTML completo da prévia.

Alterar um layout

PUT/api/v1/admin/email-layout/{type}Admin

Substituir o HTML do cabeçalho ou do rodapé

Troca o HTML do layout do idioma indicado. Se aquele tipo e idioma ainda não existirem, a plataforma cria o registro. A alteração vale para os próximos envios; e-mails já enviados não mudam. Exige manage_email ou manage_settings.

Parâmetros de caminho

typestringobrigatório
headerfooter
Qual trecho alterar.

Parâmetros de consulta

languagestringpadrão: pt-BR
Idioma do layout. Qualquer código é aceito na gravação, mas só pt-BR e en têm padrão para restaurar.

Corpo da requisição

body_htmlstringobrigatório
HTML novo, não vazio. Deve ser um trecho <tr>...</tr>.
200Layout atualizado

Restaurar o padrão

POST/api/v1/admin/email-layout/{type}/resetAdmin

Voltar o layout ao HTML original da plataforma

Descarta sua edição e grava de volta o HTML padrão da plataforma para aquele tipo e idioma. Não tem corpo. Exige manage_email ou manage_settings.

Parâmetros de caminho

typestringobrigatório
headerfooter
Qual trecho restaurar.

Parâmetros de consulta

languagestringpadrão: pt-BR
pt-BRen
Idioma a restaurar. Outro idioma responde 500, porque não há padrão para ele.
200Layout restaurado

Erros

StatusQuandoCorpo de exemplo
400type não é header nem footer (em qualquer das quatro rotas).{"error":"type must be 'header' or 'footer'"}
400PUT com corpo inválido.{"error":"invalid request body","detail":"..."}
400PUT com body_html vazio.{"error":"body_html is required"}
401Sem token ou token expirado.{"error":"invalid or expired token"}
403Módulo email-notifications desligado, ou sem privilégio.{"error":"module_disabled","module":"email-notifications"}
500Reset em idioma sem padrão, ou prévia de layout inexistente.{"error":"failed to reset email layout","detail":"no default layout found for type=footer language=fr"}
A edição vale para todos os e-mails

O layout não tem rascunho nem histórico. Antes de trocar o HTML, guarde o body_html atual (do GET). Se algo der errado, reset volta ao padrão da plataforma, não à sua versão anterior.

Teste no seu cliente de e-mail

Clientes de e-mail ignoram CSS moderno. Use tabelas e estilos em linha, como o padrão faz, e mande um teste de verdade com Enviar e-mail.

Veja também

  • Fragmentos
  • Enviar e-mail
  • E-mail da loja
Anterior
Enviar e-mail
Próxima
Fragmentos de e-mail
Nesta página
  • Listar os layouts
  • Pré-visualizar
  • Alterar um layout
  • Restaurar o padrão
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/admin/email-layout" \
  -H "Authorization: Bearer $TOKEN"
bash
curl "$BASE_URL/api/v1/admin/email-layout/preview?type=footer&language=en" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X PUT "$BASE_URL/api/v1/admin/email-layout/footer?language=pt-BR" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"body_html":"<tr><td style=\"padding:16px;text-align:center\">{{store_name}} - {{current_year}}</td></tr>"}'
bash
curl -X POST "$BASE_URL/api/v1/admin/email-layout/footer/reset?language=pt-BR" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "count": 4,
  "layouts": [
    {
      "id": "1c89edfb-483f-49c0-acee-92f53fc925f2",
      "type": "footer",
      "language": "en",
      "is_active": true,
      "body_html": "<!-- Email Footer -->\n<tr>\n  <td style=\"padding:0;\">...</td>\n</tr>",
      "created_at": "2026-04-29T09:19:51.299525Z",
      "updated_at": "2026-07-19T13:12:07.810435Z"
    }
  ]
}
json
{
  "html": "<!DOCTYPE html>\n<html>\n<head><title>Email Layout Preview - footer</title><meta charset=\"UTF-8\"></head>\n<body>...</body>\n</html>"
}
json
{ "status": "updated", "type": "footer" }
json
{ "status": "reset", "type": "footer" }