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

Log de entrega

Consulta o histórico de e-mails enviados, as estatísticas do dia, o detalhe de cada tentativa e o reenvio de falhas.

Cada e-mail que a plataforma tenta enviar gera uma linha no log de entrega: para quem foi, com qual modelo, qual o assunto, o corpo renderizado, o status e, se falhou, o motivo. É a primeira parada quando um cliente diz que "não recebeu o e-mail".

O log é grande (uma loja ativa acumula centenas de milhares de linhas), por isso a lista é paginada e filtrável. Use os filtros em vez de varrer tudo.

Listar o log

GET/api/v1/admin/email-logsAdmin

Listar tentativas de envio, mais novas primeiro

Devolve uma página do log, da mais recente para a mais antiga. Todos os filtros são opcionais e se combinam com E.

Parâmetros de consulta

statusstring

queuedsentfailedbounced

Filtra por status. Aceita a palavra ou a letra (q, s, f, b).

emailstring

Parte do e-mail do destinatário, sem diferenciar maiúsculas.

event_typestring

Igualdade exata com o evento que originou o envio, por exemplo cart.abandoned, order.created, crm.campaign.

date_fromstring

Início, YYYY-MM-DD (ou RFC 3339). Inclui o instante informado.

date_tostring

Fim, só YYYY-MM-DD. O dia entra por inteiro, até 23:59:59 UTC. Um valor com horário falha.

searchstring

Busca livre em e-mail, assunto, código do modelo, evento e nome do destinatário.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

De 1 a 100. Valores fora da faixa voltam para 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/email-logs?status=failed&date_from=2026-10-01&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Página do log

json

{
  "logs": [
    {
      "id": "042f7983-7fa7-4c5d-933f-e5a1b164b88e",
      "template_slug": "abandoned_cart",
      "recipient_email": "maria.souza@example.com",
      "recipient_name": "",
      "subject": "Seu carrinho na Loja Exemplo ainda está reservado",
      "body": "<!DOCTYPE html>...",
      "status": "failed",
      "event_type": "cart.abandoned",
      "user_id": "32cf33c3-5e4d-424c-ba67-7582f7fa163a",
      "error_message": "smtp: autenticação recusada (530)",
      "retry_count": 0,
      "created_at": "2026-10-11T21:03:49.022134Z"
    }
  ],
  "total": 416467,
  "page": 1,
  "per_page": 20,
  "total_pages": 20824
}

Campos da resposta

logs[].iduuid

Id da linha do log. Use nas rotas de detalhe e reenvio.

logs[].template_slugstring

Código do modelo usado. Vazio em mensagens avulsas.

logs[].recipient_emailstring

Destinatário.

logs[].recipient_namestring

Nome do destinatário, quando conhecido. Pode ser vazio.

logs[].subjectstring

Assunto já renderizado.

logs[].bodystring

HTML renderizado. Pesado: em listas grandes prefira ler só o necessário.

logs[].statusstring

queuedsentfailedbounced

Situação da tentativa.

logs[].event_typestring

Evento de negócio que originou o envio.

logs[].order_iduuid

Pedido relacionado. Ausente quando não há.

logs[].user_iduuid

Usuário destinatário. Ausente para visitantes.

logs[].error_messagestring

Causa da falha. Vazio quando status não é failed.

logs[].retry_countinteger

Quantas novas tentativas já ocorreram.

logs[].sent_atstring

Quando foi entregue ao provedor, RFC 3339. Ausente se nunca foi.

logs[].created_atstring

Quando a linha foi criada, RFC 3339, UTC.

totalinteger

Total de linhas que casam com os filtros.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página efetivo.

total_pagesinteger

Total de páginas.

Estatísticas do dia

GET/api/v1/admin/email-logs/statsAdmin

Totais de envio e de falha de hoje

Uma chamada barata para um painel de saúde: quantos e-mails saíram e falharam hoje, quantos esperam na fila e quantas linhas o log tem no total. Não tem parâmetros.

bash

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

200Estatísticas

json

{ "sent_today": 128, "failed_today": 3, "queue_size": 0, "total_all": 480289 }

Campos da resposta

sent_todayinteger

E-mails entregues ao provedor hoje.

failed_todayinteger

E-mails que falharam hoje.

queue_sizeinteger

E-mails aguardando na fila agora.

total_allinteger

Linhas no log, de todas as datas.

Consultar uma tentativa

GET/api/v1/admin/email-logs/{id}Admin

Detalhe de uma tentativa de envio

Devolve a linha completa do log, no mesmo formato de cada item de logs[], inclusive o corpo renderizado.

Parâmetros de caminho

iduuidobrigatório

Id da linha do log.

bash

curl "$BASE_URL/api/v1/admin/email-logs/042f7983-7fa7-4c5d-933f-e5a1b164b88e" \
  -H "Authorization: Bearer $TOKEN"

Reenviar uma falha

POST/api/v1/admin/email-logs/{id}/resendAdmin

Reenviar um e-mail que falhou

Tenta entregar de novo uma mensagem com status failed ou bounced, com o mesmo destinatário, assunto e corpo. A linha vai para queued, a entrega é tentada na hora e a mesma linha passa a sent (com retry_count mais 1) ou volta a failed. Não cria linha nova. Exige manage_email ou manage_settings.

Parâmetros de caminho

iduuidobrigatório

Id da linha do log.

bash

curl -X POST "$BASE_URL/api/v1/admin/email-logs/042f7983-7fa7-4c5d-933f-e5a1b164b88e/resend" \
  -H "Authorization: Bearer $TOKEN"

200Reenvio feito

json

{ "message": "Email re-queued for delivery" }

Erros

Status	Quando	Corpo de exemplo
400	Reenvio de linha que não está `failed` nem `bounced`.	`{"error":"failed to resend email","detail":"... can only resend failed or bounced emails (current status: sent)"}`
400	Reenvio cuja nova tentativa também falhou.	`{"error":"failed to resend email","detail":"resend email 042f...: ..."}`
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"}`
404	Id válido que não existe.	`{"error":"email log not found"}`
500	`{id}` que não é um UUID no detalhe, ou falha ao ler o log.	`{"error":"failed to get email log","detail":"o valor \"abc\" não é um uuid válido..."}`
503	Serviço de log indisponível no servidor.	`{"error":"email log service unavailable"}`

Mensagens de detail que o servidor devolve em português (como a do UUID inválido) chegam exatamente assim.

Veja também

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

Log de entrega

Consulta o histórico de e-mails enviados, as estatísticas do dia, o detalhe de cada tentativa e o reenvio de falhas.

O log é grande (uma loja ativa acumula centenas de milhares de linhas), por isso a lista é paginada e filtrável. Use os filtros em vez de varrer tudo.

Listar o log

GET/api/v1/admin/email-logsAdmin

Listar tentativas de envio, mais novas primeiro

Devolve uma página do log, da mais recente para a mais antiga. Todos os filtros são opcionais e se combinam com E.

Parâmetros de consulta

statusstring

queuedsentfailedbounced

Filtra por status. Aceita a palavra ou a letra (q, s, f, b).

emailstring

Parte do e-mail do destinatário, sem diferenciar maiúsculas.

event_typestring

Igualdade exata com o evento que originou o envio, por exemplo cart.abandoned, order.created, crm.campaign.

date_fromstring

Início, YYYY-MM-DD (ou RFC 3339). Inclui o instante informado.

date_tostring

Fim, só YYYY-MM-DD. O dia entra por inteiro, até 23:59:59 UTC. Um valor com horário falha.

searchstring

Busca livre em e-mail, assunto, código do modelo, evento e nome do destinatário.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

De 1 a 100. Valores fora da faixa voltam para 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/email-logs?status=failed&date_from=2026-10-01&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Página do log

json

{
  "logs": [
    {
      "id": "042f7983-7fa7-4c5d-933f-e5a1b164b88e",
      "template_slug": "abandoned_cart",
      "recipient_email": "maria.souza@example.com",
      "recipient_name": "",
      "subject": "Seu carrinho na Loja Exemplo ainda está reservado",
      "body": "<!DOCTYPE html>...",
      "status": "failed",
      "event_type": "cart.abandoned",
      "user_id": "32cf33c3-5e4d-424c-ba67-7582f7fa163a",
      "error_message": "smtp: autenticação recusada (530)",
      "retry_count": 0,
      "created_at": "2026-10-11T21:03:49.022134Z"
    }
  ],
  "total": 416467,
  "page": 1,
  "per_page": 20,
  "total_pages": 20824
}

Campos da resposta

logs[].iduuid

Id da linha do log. Use nas rotas de detalhe e reenvio.

logs[].template_slugstring

Código do modelo usado. Vazio em mensagens avulsas.

logs[].recipient_emailstring

Destinatário.

logs[].recipient_namestring

Nome do destinatário, quando conhecido. Pode ser vazio.

logs[].subjectstring

Assunto já renderizado.

logs[].bodystring

HTML renderizado. Pesado: em listas grandes prefira ler só o necessário.

logs[].statusstring

queuedsentfailedbounced

Situação da tentativa.

logs[].event_typestring

Evento de negócio que originou o envio.

logs[].order_iduuid

Pedido relacionado. Ausente quando não há.

logs[].user_iduuid

Usuário destinatário. Ausente para visitantes.

logs[].error_messagestring

Causa da falha. Vazio quando status não é failed.

logs[].retry_countinteger

Quantas novas tentativas já ocorreram.

logs[].sent_atstring

Quando foi entregue ao provedor, RFC 3339. Ausente se nunca foi.

logs[].created_atstring

Quando a linha foi criada, RFC 3339, UTC.

totalinteger

Total de linhas que casam com os filtros.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página efetivo.

total_pagesinteger

Total de páginas.

Estatísticas do dia

GET/api/v1/admin/email-logs/statsAdmin

Totais de envio e de falha de hoje

Uma chamada barata para um painel de saúde: quantos e-mails saíram e falharam hoje, quantos esperam na fila e quantas linhas o log tem no total. Não tem parâmetros.

bash

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

200Estatísticas

json

{ "sent_today": 128, "failed_today": 3, "queue_size": 0, "total_all": 480289 }

Campos da resposta

sent_todayinteger

E-mails entregues ao provedor hoje.

failed_todayinteger

E-mails que falharam hoje.

queue_sizeinteger

E-mails aguardando na fila agora.

total_allinteger

Linhas no log, de todas as datas.

Consultar uma tentativa

GET/api/v1/admin/email-logs/{id}Admin

Detalhe de uma tentativa de envio

Devolve a linha completa do log, no mesmo formato de cada item de logs[], inclusive o corpo renderizado.

Parâmetros de caminho

iduuidobrigatório

Id da linha do log.

bash

curl "$BASE_URL/api/v1/admin/email-logs/042f7983-7fa7-4c5d-933f-e5a1b164b88e" \
  -H "Authorization: Bearer $TOKEN"

Reenviar uma falha

POST/api/v1/admin/email-logs/{id}/resendAdmin

Reenviar um e-mail que falhou

Parâmetros de caminho

iduuidobrigatório

Id da linha do log.

bash

curl -X POST "$BASE_URL/api/v1/admin/email-logs/042f7983-7fa7-4c5d-933f-e5a1b164b88e/resend" \
  -H "Authorization: Bearer $TOKEN"

200Reenvio feito

json

{ "message": "Email re-queued for delivery" }

Erros

Status	Quando	Corpo de exemplo
400	Reenvio de linha que não está `failed` nem `bounced`.	`{"error":"failed to resend email","detail":"... can only resend failed or bounced emails (current status: sent)"}`
400	Reenvio cuja nova tentativa também falhou.	`{"error":"failed to resend email","detail":"resend email 042f...: ..."}`
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"}`
404	Id válido que não existe.	`{"error":"email log not found"}`
500	`{id}` que não é um UUID no detalhe, ou falha ao ler o log.	`{"error":"failed to get email log","detail":"o valor \"abc\" não é um uuid válido..."}`
503	Serviço de log indisponível no servidor.	`{"error":"email log service unavailable"}`

Mensagens de detail que o servidor devolve em português (como a do UUID inválido) chegam exatamente assim.