Integre. Consulte.
Administre.

API Web Matrix

Esta é a interface usada pelo painel. As três operações usam GET e recebem user e password na query string, conforme o contrato desta instalação.

A resposta é JSON. O campo result informa o resultado da operação; HTTP 200, sozinho, não confirma sucesso. Para usar a API no navegador, o Matrix precisa permitir CORS para a origem do painel. A sessão local de 60 minutos é uma regra do painel, não um token emitido pela API.

Respostas e paginação

Exemplo ilustrativo de histórico; os campos disponíveis variam conforme o registro.

{
  "result": "VALID",
  "information": "valid credential",
  "message": [{
    "key": "1791200000000",
    "arrival": "Mon, 05 Oct 26 09:00:00 -0300",
    "client": "mx01.example.com",
    "queueid": "ABC123",
    "sender": "remetente@example.com",
    "recipient": "destinatario@example.com",
    "subject": "Exemplo de mensagem",
    "result": "ACCEPT",
    "filter": "SPF_PASS"
  }],
  "next": "1791199999999"
}

Como percorrer o histórico

1. Consulte /history/ sem begin.
2. Acrescente as mensagens e elimine duplicados pelo identificador.
3. Se houver next, use seu valor como begin, mesmo que o lote tenha poucos ou nenhum registro.
4. Quando next estiver ausente, vazio ou nulo, a consulta terminou. Se o cursor repetir, interrompa e trate como histórico parcial.

O painel usa uma API PHP na mesma origem para manter um SQLite privado por conta, com até três meses de histórico. Após validar o login, as consultas e os filtros usam o banco. Reabrir uma sessão válida mostra os dados salvos antes de sincronizar. Cada lote insere ou atualiza registros por timekey; mensagens ausentes da API permanecem até vencerem.

As credenciais validadas ficam criptografadas no banco privado para permitir atualização diária mesmo após sair do painel. O cron consulta cada conta, percorre os lotes e atualiza os registros. Senha recusada suspende a atualização automática até um novo login válido. A coleta automática não renova o prazo de uso: contas sem acesso ao painel por mais de três meses deixam de ser sincronizadas e são removidas na limpeza.

A sincronização respeita next/begin, com pelo menos cinco segundos entre lotes. Lotes conhecidos são revisados; três lotes vazios, cursor repetido, falha ou mil lotes por execução permitem retomada com indicação de histórico parcial. HTTP 429 respeita Retry-After.

Você pode liberar ou bloquear e-mails já carregados enquanto os próximos lotes chegam. A ação aguarda a operação atual e tem prioridade sobre o próximo lote na mesma aba. Somente a mensagem com ação pendente fica desabilitada. Se o servidor estiver ocupado antes de enviar a ação, o painel aguarda por até 30 segundos; falhas de rede, timeout e resultados incertos não repetem a ação.

Filtros e exportação no painel

Período e servidor filtram o histórico privado no SQLite e são compartilhados entre tabela, cards e gráfico. Hoje e Últimos 7 dias terminam no horário da última atualização; Datas específicas inclui os dias inicial e final no fuso local, sem aceitar datas futuras. Busca e status refinam a tabela e o CSV. O PHP aplica os filtros e a paginação no banco; a interface recebe a página solicitada e as métricas agregadas.

O CSV contém todos os resultados filtrados e informa o período, servidor, busca, status selecionados, horários de atualização/exportação e se o histórico está completo ou parcial. O formato usa UTF-8 com BOM e separador ponto e vírgula. Status original e política aplicada são colunas separadas.

Confirmação das ações

{ "result": "DONE", "information": "sender whitelisted" }

O painel aceita DONE ou VALID por compatibilidade. Após a confirmação, grava a última ação confirmada no SQLite com seu horário, preservando os campos originais. O status histórico, seus filtros e os indicadores permanecem baseados em result/filter; a política é exibida separadamente nos detalhes e no CSV. A última ação permanece entre sessões, separada do resultado histórico atualizado pelo Matrix.

Os códigos adicionais constam no servidor público consultado; a implantação Matrix pode variar. Em erro HTTP, JSON inválido ou timeout, não considere a operação confirmada. Após timeout de uma ação, consulte o histórico antes de repeti-la: o servidor pode já ter processado a chamada.

API SSH / cliente SPFBL

“API SSH” aqui significa executar /usr/local/bin/spfbl em um servidor acessível por SSH. O cliente faz a comunicação com o serviço SPFBL configurado nesse servidor. Não é um endpoint HTTP.

1. Acesse um servidor que já tenha o cliente instalado e configurado.
2. Verifique a versão com /usr/local/bin/spfbl version e consulte /usr/local/bin/spfbl --help.
3. Escolha um comando de usuário ou administrador conforme as permissões da sua instalação.

O catálogo abaixo cobre o helper v2.17 fornecido. [argumento] significa opcional; alternativas aparecem como operações separadas. O usuário SSH não é necessariamente a conta Matrix. Ser root no servidor não garante autorização administrativa no Matrix.

Exemplos práticos

Referência completa do cliente

Expanda um grupo para ver sintaxe, finalidade, argumentos e exemplos. Os exemplos alteram dados quando executados; confira a operação indicada.

Como interpretar a saída

As respostas do cliente são texto, não o JSON da API Web. Leia a saída e o código de término de cada comando. Não há uma tabela universal de códigos: por exemplo, block find pode retornar código 1 quando encontra um registro. A disponibilidade e os privilégios dependem da configuração do serviço.

Fontes e compatibilidade

Referência Web baseada nas chamadas deste painel e no servidor HTTP oficial. Referência SSH baseada no helper fornecido pelo administrador e no cliente público SPFBL v2.17, e no serviço administrativo oficial, consultados em 05/10/2026.

As configurações do cliente e do Matrix podem diferir do código público. Os exemplos não foram executados em produção. A versão desta documentação acompanha o painel; a versão do cliente é independente.