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.

bash

curl "$BASE_URL/api/v1/admin/email-layout" \
  -H "Authorization: Bearer $TOKEN"

200Layouts retornados

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

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.

bash

curl "$BASE_URL/api/v1/admin/email-layout/preview?type=footer&language=en" \
  -H "Authorization: Bearer $TOKEN"

200Prévia gerada

json

{
  "html": "<!DOCTYPE html>\n<html>\n<head><title>Email Layout Preview - footer</title><meta charset=\"UTF-8\"></head>\n<body>...</body>\n</html>"
}

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>.

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

200Layout atualizado

json

{ "status": "updated", "type": "footer" }

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.

bash

curl -X POST "$BASE_URL/api/v1/admin/email-layout/footer/reset?language=pt-BR" \
  -H "Authorization: Bearer $TOKEN"

200Layout restaurado

json

{ "status": "reset", "type": "footer" }

Erros

Status	Quando	Corpo de exemplo
400	`type` não é `header` nem `footer` (em qualquer das quatro rotas).	`{"error":"type must be 'header' or 'footer'"}`
400	`PUT` com corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`PUT` com `body_html` vazio.	`{"error":"body_html is required"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Módulo `email-notifications` desligado, ou sem privilégio.	`{"error":"module_disabled","module":"email-notifications"}`
500	Reset 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"}`

Veja também

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.

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.

bash

curl "$BASE_URL/api/v1/admin/email-layout" \
  -H "Authorization: Bearer $TOKEN"

200Layouts retornados

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

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

Parâmetros de consulta

typestringpadrão: header

headerfooter

Qual trecho mostrar.

languagestringpadrão: pt-BR

pt-BRen

Idioma do layout.

bash

curl "$BASE_URL/api/v1/admin/email-layout/preview?type=footer&language=en" \
  -H "Authorization: Bearer $TOKEN"

200Prévia gerada

json

{
  "html": "<!DOCTYPE html>\n<html>\n<head><title>Email Layout Preview - footer</title><meta charset=\"UTF-8\"></head>\n<body>...</body>\n</html>"
}

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é

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>.

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

200Layout atualizado

json

{ "status": "updated", "type": "footer" }

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.

bash

curl -X POST "$BASE_URL/api/v1/admin/email-layout/footer/reset?language=pt-BR" \
  -H "Authorization: Bearer $TOKEN"

200Layout restaurado

json

{ "status": "reset", "type": "footer" }

Erros

Status	Quando	Corpo de exemplo
400	`type` não é `header` nem `footer` (em qualquer das quatro rotas).	`{"error":"type must be 'header' or 'footer'"}`
400	`PUT` com corpo inválido.	`{"error":"invalid request body","detail":"..."}`
400	`PUT` com `body_html` vazio.	`{"error":"body_html is required"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	Módulo `email-notifications` desligado, ou sem privilégio.	`{"error":"module_disabled","module":"email-notifications"}`
500	Reset 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"}`