API atual/Referência completa/E-mail: envio, layout e logs

Fragmentos de e-mail

Lista, cria, altera e apaga os trechos de HTML reutilizáveis que os modelos de e-mail incluem pelo código.

Um fragmento (snippet) é um trecho de HTML com nome e código, guardado uma vez e reaproveitado em vários modelos. O exemplo clássico é a tabela de itens do pedido ou o aviso legal do rodapé: em vez de copiar o HTML em cada modelo, o modelo escreve {{snippet "email_footer"}} e a plataforma troca pelo conteúdo no envio. Mudar o fragmento muda todos os modelos que o usam.

A loja já vem com fragmentos de sistema (email_header, email_footer, order_items_table). Você pode editá-los, mas não apagá-los.

Listar fragmentos

GET/api/v1/admin/email-snippetsAdmin

Listar todos os fragmentos

Devolve todos os fragmentos, sem paginação, os de sistema primeiro e depois por code. Não tem parâmetros.

bash

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

200Fragmentos retornados

json

{
  "total": 2,
  "snippets": [
    {
      "id": "5a12424f-a039-456a-a98f-e1eaa93ea323",
      "code": "email_footer",
      "name": "Email Footer",
      "content": "<p>Este email foi enviado automaticamente por {{store_name}}.</p>",
      "snippet_type": "mail",
      "is_system": true,
      "status": "A",
      "language": "pt-BR",
      "created_at": "2026-04-29T09:19:51.299525Z",
      "updated_at": "2026-07-19T13:12:07.810435Z"
    }
  ]
}

Campos da resposta

totalinteger

Quantidade de fragmentos no vetor.

snippets[].iduuid

Id do fragmento.

snippets[].codestring

Código usado pelos modelos para incluir o fragmento.

snippets[].namestring

Nome para exibição no painel.

snippets[].contentstring

HTML do trecho, com marcadores {{...}}.

snippets[].snippet_typestring

Categoria. Fragmentos de e-mail usam mail.

snippets[].is_systemboolean

true para fragmentos que vêm com a plataforma. Não podem ser apagados.

snippets[].statusstring

AD

Letra de status: A ativo, D desativado.

snippets[].languagestring

Idioma do fragmento (pt-BR por padrão).

snippets[].created_atstring

RFC 3339, UTC.

snippets[].updated_atstring

RFC 3339, UTC.

Criar um fragmento

POST/api/v1/admin/email-snippetsAdmin

Criar um fragmento

Cria um fragmento próprio (is_system: false). Exige manage_email ou manage_settings.

Corpo da requisição

codestringobrigatório

Código do fragmento, por exemplo aviso_troca. É o texto que o modelo escreve entre aspas em {{snippet "..."}}. Escolha um código sem espaços.

namestringobrigatório

Nome de exibição.

contentstring

HTML do trecho.

snippet_typestringpadrão: mail

Categoria do fragmento.

statusstringpadrão: A

AD

Aceita a letra ou a palavra (active, disabled). Vazio vira A.

languagestringpadrão: pt-BR

Idioma do fragmento. Só pode ser definido na criação.

bash

curl -X POST "$BASE_URL/api/v1/admin/email-snippets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"aviso_troca","name":"Aviso de troca","content":"<p>Trocas em até 7 dias.</p>"}'

201Fragmento criado

json

{
  "id": "9ab550c5-209f-4efe-9a87-c9568e147636",
  "code": "aviso_troca",
  "name": "Aviso de troca",
  "content": "<p>Trocas em até 7 dias.</p>",
  "snippet_type": "mail",
  "is_system": false,
  "status": "A",
  "language": "pt-BR",
  "created_at": "2026-10-11T21:10:00.000000Z",
  "updated_at": "2026-10-11T21:10:00.000000Z"
}

Alterar um fragmento

PUT/api/v1/admin/email-snippets/{id}Admin

Alterar um fragmento

Atualiza só os campos que você enviar com valor. É uma atualização parcial: um campo omitido ou vazio é ignorado, então não dá para limpar content por esta rota. Aceita também fragmentos de sistema. Exige manage_email ou manage_settings.

Parâmetros de caminho

iduuidobrigatório

Id do fragmento.

Corpo da requisição

codestring

Novo código. Os modelos que usam o código antigo deixam de encontrá-lo.

namestring

Novo nome.

contentstring

Novo HTML.

snippet_typestring

Nova categoria.

statusstring

AD

Novo status. Letra ou palavra.

bash

curl -X PUT "$BASE_URL/api/v1/admin/email-snippets/9ab550c5-209f-4efe-9a87-c9568e147636" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"<p>Trocas em até 30 dias.</p>"}'

200Fragmento atualizado

A resposta é o fragmento completo, no mesmo formato da criação. Se o corpo não tiver nenhum campo com valor, a resposta é 200 com o corpo null e nada é gravado.

Apagar um fragmento

DELETE/api/v1/admin/email-snippets/{id}Admin

Apagar um fragmento próprio

Remove definitivamente um fragmento criado por você. Fragmentos de sistema não são apagados. Os modelos que ainda o incluem passam a renderizar sem o trecho, sem erro. Exige manage_email ou manage_settings.

Parâmetros de caminho

iduuidobrigatório

Id do fragmento.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/email-snippets/9ab550c5-209f-4efe-9a87-c9568e147636" \
  -H "Authorization: Bearer $TOKEN"

200Fragmento apagado

json

{ "status": "deleted" }

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido (criação e alteração).	`{"error":"invalid request body","detail":"..."}`
400	Criação sem `code` ou sem `name`.	`{"error":"code and name are 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	`code` já existe, `status` desconhecido, id inexistente na alteração, ou tentativa de apagar um fragmento de sistema ou inexistente.	`{"error":"failed to delete email snippet","detail":"snippet not found or is a system snippet: 5a12424f-..."}`

Veja também

API atual/Referência completa/E-mail: envio, layout e logs

Fragmentos de e-mail

Lista, cria, altera e apaga os trechos de HTML reutilizáveis que os modelos de e-mail incluem pelo código.

A loja já vem com fragmentos de sistema (email_header, email_footer, order_items_table). Você pode editá-los, mas não apagá-los.

Listar fragmentos

GET/api/v1/admin/email-snippetsAdmin

Listar todos os fragmentos

Devolve todos os fragmentos, sem paginação, os de sistema primeiro e depois por code. Não tem parâmetros.

bash

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

200Fragmentos retornados

json

{
  "total": 2,
  "snippets": [
    {
      "id": "5a12424f-a039-456a-a98f-e1eaa93ea323",
      "code": "email_footer",
      "name": "Email Footer",
      "content": "<p>Este email foi enviado automaticamente por {{store_name}}.</p>",
      "snippet_type": "mail",
      "is_system": true,
      "status": "A",
      "language": "pt-BR",
      "created_at": "2026-04-29T09:19:51.299525Z",
      "updated_at": "2026-07-19T13:12:07.810435Z"
    }
  ]
}

Campos da resposta

totalinteger

Quantidade de fragmentos no vetor.

snippets[].iduuid

Id do fragmento.

snippets[].codestring

Código usado pelos modelos para incluir o fragmento.

snippets[].namestring

Nome para exibição no painel.

snippets[].contentstring

HTML do trecho, com marcadores {{...}}.

snippets[].snippet_typestring

Categoria. Fragmentos de e-mail usam mail.

snippets[].is_systemboolean

true para fragmentos que vêm com a plataforma. Não podem ser apagados.

snippets[].statusstring

AD

Letra de status: A ativo, D desativado.

snippets[].languagestring

Idioma do fragmento (pt-BR por padrão).

snippets[].created_atstring

RFC 3339, UTC.

snippets[].updated_atstring

RFC 3339, UTC.

Criar um fragmento

POST/api/v1/admin/email-snippetsAdmin

Criar um fragmento

Cria um fragmento próprio (is_system: false). Exige manage_email ou manage_settings.

Corpo da requisição

codestringobrigatório

Código do fragmento, por exemplo aviso_troca. É o texto que o modelo escreve entre aspas em {{snippet "..."}}. Escolha um código sem espaços.

namestringobrigatório

Nome de exibição.

contentstring

HTML do trecho.

snippet_typestringpadrão: mail

Categoria do fragmento.

statusstringpadrão: A

AD

Aceita a letra ou a palavra (active, disabled). Vazio vira A.

languagestringpadrão: pt-BR

Idioma do fragmento. Só pode ser definido na criação.

bash

curl -X POST "$BASE_URL/api/v1/admin/email-snippets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"code":"aviso_troca","name":"Aviso de troca","content":"<p>Trocas em até 7 dias.</p>"}'

201Fragmento criado

json

{
  "id": "9ab550c5-209f-4efe-9a87-c9568e147636",
  "code": "aviso_troca",
  "name": "Aviso de troca",
  "content": "<p>Trocas em até 7 dias.</p>",
  "snippet_type": "mail",
  "is_system": false,
  "status": "A",
  "language": "pt-BR",
  "created_at": "2026-10-11T21:10:00.000000Z",
  "updated_at": "2026-10-11T21:10:00.000000Z"
}

Alterar um fragmento

PUT/api/v1/admin/email-snippets/{id}Admin

Alterar um fragmento

Parâmetros de caminho

iduuidobrigatório

Id do fragmento.

Corpo da requisição

codestring

Novo código. Os modelos que usam o código antigo deixam de encontrá-lo.

namestring

Novo nome.

contentstring

Novo HTML.

snippet_typestring

Nova categoria.

statusstring

AD

Novo status. Letra ou palavra.

bash

curl -X PUT "$BASE_URL/api/v1/admin/email-snippets/9ab550c5-209f-4efe-9a87-c9568e147636" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"<p>Trocas em até 30 dias.</p>"}'

200Fragmento atualizado

A resposta é o fragmento completo, no mesmo formato da criação. Se o corpo não tiver nenhum campo com valor, a resposta é 200 com o corpo null e nada é gravado.

Apagar um fragmento

DELETE/api/v1/admin/email-snippets/{id}Admin

Apagar um fragmento próprio

Parâmetros de caminho

iduuidobrigatório

Id do fragmento.

bash

curl -X DELETE "$BASE_URL/api/v1/admin/email-snippets/9ab550c5-209f-4efe-9a87-c9568e147636" \
  -H "Authorization: Bearer $TOKEN"

200Fragmento apagado

json

{ "status": "deleted" }

Erros

Status	Quando	Corpo de exemplo
400	Corpo inválido (criação e alteração).	`{"error":"invalid request body","detail":"..."}`
400	Criação sem `code` ou sem `name`.	`{"error":"code and name are 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	`code` já existe, `status` desconhecido, id inexistente na alteração, ou tentativa de apagar um fragmento de sistema ou inexistente.	`{"error":"failed to delete email snippet","detail":"snippet not found or is a system snippet: 5a12424f-..."}`