API legada/Referência completa/Assinantes da newsletter

Listar assinantes

Lista os e-mails inscritos na newsletter, com busca por texto e paginação.

Lista os assinantes, dos mais novos para os mais antigos. Use para exportar a base para uma ferramenta de e-mail marketing ou para achar o UUID de um e-mail antes de removê-lo.

O parâmetro email não é uma igualdade: ele procura o texto dentro do e-mail ou do nome, sem diferenciar maiúsculas.

GET/api/v1.0/subscribersAdmin

Listar assinantes

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 100. De 101 a 250 volta com 20 itens (e params.items_per_page repete o valor pedido). Acima de 250, menor que 1 ou texto vira 10.

emailstring

Texto contido no e-mail ou no nome do assinante. Sem diferenciar maiúsculas.

GET/api/subscribersAdmin

Mesma operação, caminho alternativo

Mesmo comportamento, parâmetros e resposta de GET /api/v1.0/subscribers. Use este caminho se o seu cliente já foi escrito para ele. Nesta forma sem versão o subscriber_id sai como número decimal em string, mas o caminho /{id} só aceita o UUID.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1.0/subscribers?email=@example.com&items_per_page=50" \
  -u "$EMAIL:$API_KEY"

Resposta

200Assinantes retornados

json

{
  "subscribers": [
    {
      "subscriber_id": "43053e7f-c17b-4c8a-8009-649f1c0cef85",
      "email": "maria.souza@example.com",
      "name": "Maria Souza",
      "status": "A",
      "timestamp": 1791753743
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 3437 }
}

Campos da resposta

subscribersarray

Assinantes da página. Cada item tem os campos abaixo.

paramsobject

page, items_per_page e total_items (total que atende à busca, em todas as páginas).

subscribers[].subscriber_idstring

Id do assinante (UUID em /api/v1.0; decimal em /api).

subscribers[].emailstring

E-mail.

subscribers[].namestring

Nome, ou vazio.

subscribers[].statusstring

APUB

A ativo, P pendente, U cancelou, B suprimido por bounce.

subscribers[].timestampinteger

Criação, Unix (segundos).

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	A credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: admin scope required"}`

Veja também

Listar assinantes

Lista os e-mails inscritos na newsletter, com busca por texto e paginação.

Lista os assinantes, dos mais novos para os mais antigos. Use para exportar a base para uma ferramenta de e-mail marketing ou para achar o UUID de um e-mail antes de removê-lo.

O parâmetro email não é uma igualdade: ele procura o texto dentro do e-mail ou do nome, sem diferenciar maiúsculas.

GET/api/v1.0/subscribersAdmin

Listar assinantes

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1.

items_per_pageintegerpadrão: 10

Itens por página, de 1 a 100. De 101 a 250 volta com 20 itens (e params.items_per_page repete o valor pedido). Acima de 250, menor que 1 ou texto vira 10.

emailstring

Texto contido no e-mail ou no nome do assinante. Sem diferenciar maiúsculas.

GET/api/subscribersAdmin

Mesma operação, caminho alternativo

Exemplo de requisição

bash

curl "$BASE_URL/api/v1.0/subscribers?email=@example.com&items_per_page=50" \
  -u "$EMAIL:$API_KEY"

Resposta

200Assinantes retornados

json

{
  "subscribers": [
    {
      "subscriber_id": "43053e7f-c17b-4c8a-8009-649f1c0cef85",
      "email": "maria.souza@example.com",
      "name": "Maria Souza",
      "status": "A",
      "timestamp": 1791753743
    }
  ],
  "params": { "page": 1, "items_per_page": 10, "total_items": 3437 }
}

Campos da resposta

subscribersarray

Assinantes da página. Cada item tem os campos abaixo.

paramsobject

page, items_per_page e total_items (total que atende à busca, em todas as páginas).

subscribers[].subscriber_idstring

Id do assinante (UUID em /api/v1.0; decimal em /api).

subscribers[].emailstring

E-mail.

subscribers[].namestring

Nome, ou vazio.

subscribers[].statusstring

APUB

A ativo, P pendente, U cancelou, B suprimido por bounce.

subscribers[].timestampinteger

Criação, Unix (segundos).

Erros

Status	Quando	Corpo de exemplo
401	Sem credencial.	`{"status":401,"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>."}`
401	E-mail ou chave de API inválidos.	`{"status":401,"message":"Invalid credentials"}`
403	A credencial é válida, mas o usuário não é administrador.	`{"status":403,"message":"Forbidden: admin scope required"}`