VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Newsletter

Inscritos

Lista, consulta e apaga os inscritos da newsletter.

Listar inscritos

Devolve os inscritos, do mais recente para o mais antigo, com as estatísticas gerais ao lado. Quem ainda não confirmou o e-mail aparece como P, e só A recebe campanhas.

GET/api/v1/admin/newsletter/subscribersAdmin

Lista os inscritos da newsletter

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Leitura exige view_newsletter, manage_newsletter ou manage_content.

Parâmetros de consulta

statusstring
activependingunsubscribedbounced
Filtra pelo estado.
searchstring
Texto contido no e-mail ou no nome.
pageintegerpadrão: 1
Página, a partir de 1.
limitintegerpadrão: 20
Itens por página, 1 a 100; fora disso vale 20.

Exemplo de requisição (Listar inscritos)

bash
curl "$BASE_URL/api/v1/admin/newsletter/subscribers?status=active&limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar inscritos)

200Inscritos
json
{
  "subscribers": {
    "items": [
      {
        "id": "a0719d30-0e5b-44cb-86c8-fa160cf2fb92",
        "email": "maria.souza@example.com",
        "name": "Maria Souza",
        "status": "A",
        "source": "storefront_block",
        "ip_address": "203.0.113.10",
        "subscribed_at": "2026-09-21T21:11:00.638673Z",
        "created_at": "2026-09-21T21:11:00.638673Z",
        "subscriber_id": "a0719d30-0e5b-44cb-86c8-fa160cf2fb92",
        "timestamp": 1790025060
      }
    ],
    "total": 2550,
    "page": 1,
    "limit": 20
  },
  "stats": {
    "total_active": 2550,
    "this_month": 12,
    "unsubscribed": 817
  }
}

Campos da resposta

subscribersobject

Página de resultados.

itemsarray

Inscritos da página.

iduuid
Identificador do inscrito.
emailstring
E-mail (dado pessoal).
namestring
Nome, quando informado.
statusstring
Letra do estado: A ativo, P aguardando confirmação, U cancelou, B e-mail devolvido (bounce).
sourcestring
De onde veio a inscrição (storefront_block, register_consent, onsite:popup, onsite:wheel...).
ip_addressstring
IP no momento da inscrição.
subscribed_atstring
Inscrição, RFC 3339.
unsubscribed_atstring
Cancelamento, RFC 3339. Ausente se nunca cancelou.
created_atstring
Criação do registro, RFC 3339.
totalinteger
Total que atende ao filtro.
pageinteger
Página devolvida.
limitinteger
Itens por página usados.
statsobject

Totais gerais (não dependem do filtro). Pode faltar se o cálculo falhar.

total_activeinteger
Inscritos ativos.
this_monthinteger
Inscritos ativos que entraram neste mês.
unsubscribedinteger
Quem cancelou.

Erros (Listar inscritos)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_newsletter","manage_newsletter","manage_content"]}
500Falha de banco.{"error":"failed to list subscribers","detail":"..."}
Campos repetidos

Cada inscrito também traz subscriber_id e timestamp, campos que repetem outros valores.

Consultar inscrito

Devolve um inscrito.

GET/api/v1/admin/newsletter/subscribers/{id}Admin

Devolve um inscrito pelo id

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Leitura exige view_newsletter, manage_newsletter ou manage_content.

Parâmetros de caminho

iduuidobrigatório
Identificador do inscrito.

Exemplo de requisição (Consultar inscrito)

bash
curl "$BASE_URL/api/v1/admin/newsletter/subscribers/a0719d30-0e5b-44cb-86c8-fa160cf2fb92" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar inscrito)

200Inscrito
json
{
  "id": "a0719d30-0e5b-44cb-86c8-fa160cf2fb92",
  "email": "maria.souza@example.com",
  "name": "Maria Souza",
  "status": "A",
  "source": "storefront_block",
  "ip_address": "203.0.113.10",
  "subscribed_at": "2026-09-21T21:11:00.638673Z",
  "created_at": "2026-09-21T21:11:00.638673Z",
  "subscriber_id": "a0719d30-0e5b-44cb-86c8-fa160cf2fb92",
  "timestamp": 1790025060
}

Campos da resposta

iduuid
Identificador do inscrito.
emailstring
E-mail (dado pessoal).
namestring
Nome, quando informado.
statusstring
Letra do estado: A ativo, P aguardando confirmação, U cancelou, B e-mail devolvido (bounce).
sourcestring
De onde veio a inscrição (storefront_block, register_consent, onsite:popup, onsite:wheel...).
ip_addressstring
IP no momento da inscrição.
subscribed_atstring
Inscrição, RFC 3339.
unsubscribed_atstring
Cancelamento, RFC 3339. Ausente se nunca cancelou.
created_atstring
Criação do registro, RFC 3339.

Erros (Consultar inscrito)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_newsletter","manage_newsletter","manage_content"]}
404Não existe inscrito com esse id.{"error":"subscriber not found"}
500O id não é um UUID válido (500, não 404).{"detail":"o valor \"xx\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie.","error":"failed to get subscriber"}

Apagar inscrito

Remove o registro do inscrito (por exemplo a pedido dele, para atender à LGPD). A pessoa pode se inscrever de novo depois. Para apenas parar os envios sem perder o histórico, não há rota: o cancelamento é feito pelo próprio inscrito pelo link do e-mail.

DELETE/api/v1/admin/newsletter/subscribers/{id}Admin

Apaga um inscrito

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Exige manage_newsletter ou manage_content.

Parâmetros de caminho

iduuidobrigatório
Identificador do inscrito.

Exemplo de requisição (Apagar inscrito)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/newsletter/subscribers/a0719d30-0e5b-44cb-86c8-fa160cf2fb92" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar inscrito)

200Inscrito apagado
json
{
  "message": "subscriber deleted"
}

Erros (Apagar inscrito)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_newsletter","manage_content"]}
404Não existe inscrito com esse id.{"error":"subscriber not found"}
500O id não é um UUID válido (500, não 404).{"detail":"o valor \"xx\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie.","error":"failed to delete subscriber"}
Exclusão definitiva

Não há como restaurar.

Veja também

  • Exportar inscritos
  • Campanhas
Anterior
Resumo da newsletter
Próxima
Exportar inscritos
Nesta página
  • Listar inscritos
  • Exemplo de requisição (Listar inscritos)
  • Resposta (Listar inscritos)
  • Erros (Listar inscritos)
  • Consultar inscrito
  • Exemplo de requisição (Consultar inscrito)
  • Resposta (Consultar inscrito)
  • Erros (Consultar inscrito)
  • Apagar inscrito
  • Exemplo de requisição (Apagar inscrito)
  • Resposta (Apagar inscrito)
  • Erros (Apagar inscrito)
  • Veja também