API atual/Referência completa/Newsletter

GETResumo da newsletter

Uma chamada só com inscritos, campanhas recentes e estatísticas para a tela inicial.

Atalho para montar a tela inicial da newsletter com uma única chamada: a primeira página de inscritos, as 5 campanhas mais recentes e os totais.

GET/api/v1/admin/newsletterAdmin

Devolve inscritos, campanhas recentes e estatísticas

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

pageintegerpadrão: 1

Página de inscritos, a partir de 1.

limitintegerpadrão: 20

Inscritos por página, 1 a 100; fora disso vale 20.

Exemplo de requisição

bash

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

Resposta

200Resumo

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": 3437,
    "page": 1,
    "limit": 20
  },
  "campaigns": {
    "items": [
      {
        "id": "b2247714-08c6-4ad9-b644-748eae7baa70",
        "subject": "Black Friday chegou",
        "html_body": "<h1>Ofertas</h1><p>Até 50% off.</p>",
        "text_body": "Ofertas: até 50% off.",
        "status": "R",
        "recipients": 0,
        "sent": 0,
        "failed": 0,
        "scheduled_at": "2026-11-27T12:00:00Z",
        "created_at": "2026-10-11T21:05:13.511196Z",
        "updated_at": "2026-10-11T21:05:13.511196Z"
      }
    ],
    "total": 26,
    "page": 1,
    "limit": 5
  },
  "stats": {
    "total_active": 2550,
    "this_month": 12,
    "unsubscribed": 817
  }
}

Campos da resposta

subscribersobject

Primeira página de inscritos (items, total, page, limit).

campaignsobject

As 5 campanhas mais recentes, no mesmo formato da lista de campanhas.

statsobject

Totais.

total_activeinteger

Inscritos ativos.

this_monthinteger

Inscritos ativos que entraram neste mês.

unsubscribedinteger

Quem cancelou.

Erros

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

Veja também

GETResumo da newsletter

Uma chamada só com inscritos, campanhas recentes e estatísticas para a tela inicial.

Atalho para montar a tela inicial da newsletter com uma única chamada: a primeira página de inscritos, as 5 campanhas mais recentes e os totais.

GET/api/v1/admin/newsletterAdmin

Devolve inscritos, campanhas recentes e estatísticas

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

pageintegerpadrão: 1

Página de inscritos, a partir de 1.

limitintegerpadrão: 20

Inscritos por página, 1 a 100; fora disso vale 20.

Exemplo de requisição

bash

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

Resposta

200Resumo

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": 3437,
    "page": 1,
    "limit": 20
  },
  "campaigns": {
    "items": [
      {
        "id": "b2247714-08c6-4ad9-b644-748eae7baa70",
        "subject": "Black Friday chegou",
        "html_body": "<h1>Ofertas</h1><p>Até 50% off.</p>",
        "text_body": "Ofertas: até 50% off.",
        "status": "R",
        "recipients": 0,
        "sent": 0,
        "failed": 0,
        "scheduled_at": "2026-11-27T12:00:00Z",
        "created_at": "2026-10-11T21:05:13.511196Z",
        "updated_at": "2026-10-11T21:05:13.511196Z"
      }
    ],
    "total": 26,
    "page": 1,
    "limit": 5
  },
  "stats": {
    "total_active": 2550,
    "this_month": 12,
    "unsubscribed": 817
  }
}

Campos da resposta

subscribersobject

Primeira página de inscritos (items, total, page, limit).

campaignsobject

As 5 campanhas mais recentes, no mesmo formato da lista de campanhas.

statsobject

Totais.

total_activeinteger

Inscritos ativos.

this_monthinteger

Inscritos ativos que entraram neste mês.

unsubscribedinteger

Quem cancelou.

Erros

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