API v1 JSON Autenticação por token REST

Referência da API

Crie integrações para o Skysnag com tokens de API com permissões limitadas. Autentique-se com X-Api-Token Cabeçalho — não é autenticação Bearer. Todas as respostas são JSON com formatos de erro previsíveis.

Entrar Início rápido Coleção do Postman Arquivo de ambiente
https://developers.skysnag.com/api/v1
X-Api-Token
sk_snag_…
60 requisições/min

Início rápido

Três passos para sua primeira solicitação autenticada.

  1. Solicitar acesso à API — Enviar de Solicitações de acesso à API. Um administrador habilita o acesso à API na sua conta.
  2. Criar um token com escopo — Abra Tokens de API, selecione os escopos e copie o token completo imediatamente (exibido apenas uma vez).
  3. Enviar solicitações autenticadas — Incluir X-Api-Token: sk_snag_… em cada chamada protegida.
cURL — verificação de integridade (sem autenticação) 
curl -s "https://developers.skysnag.com/api/v1/health" \
  -H "Accept: application/json"

Coleção do Postman

Importe uma coleção e um ambiente prontos para explorar todos os endpoints v1 no Postman.

  1. Descarregar a coleção — Skysnag-API-v1.postman_collection.json
  2. Fazer o download do ambiente — Skysnag-API-v1.postman_environment.json (pré-preenchido com a URL base deste aplicativo: https://developers.skysnag.com/api/v1)
  3. Importar ambos os arquivos no Postman → Importar → arraste os arquivos JSON ou selecione-os.
  4. Defina o seu token — No ambiente, defina api_token para o seu token completo de Tokens de API.
  5. Executar solicitações — Comece com System → Health, depois Authentication → Get Me.
Descarregar coleção Baixar ambiente

Autenticação

Protected endpoints require a personal API token in a dedicated header. Do not use Authorization: Bearer.

CabeçalhoValorQuando
X-Api-Token Full token (sk_snag_…) Todos os endpoints protegidos
cURL — requisição autenticada 
curl -s "https://developers.skysnag.com/api/v1/auth/me" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
Experimente a API no seu navegador

Cole um token para habilitar o console Experimente nos endpoints Obter abaixo (somente leitura). As requisições são executadas contra sua conta em produção em https://developers.skysnag.com/api/v1. O token é armazenado apenas neste navegador (localStorage) e nunca é enviado para outro lugar além desta API.

Chave não definida

URL base e cabeçalhos

Todos os caminhos v1 são relativos à URL base indicada abaixo.

https://developers.skysnag.com/api/v1
https://api.skysnag.com/v1
CabeçalhoValorNotas
Aceitarapplication/jsonSempre
Tipo de conteúdoapplication/jsonao enviar um corpo
X-Api-TokenO seu token de APIPontos finais protegidos
X-Request-IdUUID (opcional)Correlacionar logs; refletido em erros

Respostas

Success payloads are wrapped in a data envelope.

JSON — envelope de sucesso 
{
  "data": { ... }
}
JSON — GET /health 
{
  "data": {
    "status": "ok",
    "version": "v1"
  }
}

Erros

Errors return a stable code, human message, and request_id for support.

JSON — envelope de erro 
{
  "error": {
    "code": "missing_api_token",
    "message": "API token is required...",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
HTTPCódigoDescrição
401Falta o token da APIX-Api-Token não fornecido
401Token de API inválidoToken desconhecido, revogado ou expirado.
403Acesso à API desativadoA conta não tem acesso à API
403Plano de API não elegívelPlano Comply ou de avaliação — atualizar para Protect ou Suite
403Permissões insuficientesO token não possui o escopo necessário
422Erro de validaçãoCorpo da requisição inválido
404Não encontradoRecurso não encontrado
429Erro HTTPLimite de solicitações excedido
500Erro internoErro de servidor inesperado

Paginação da lista

List endpoints return pagination metadata alongside data.

ParâmetroTipoPadrãoDescrição
páginaInteiro1Número da página (começa em 1)
limiteInteirovariaItens por página (máx. 100)
JSON — resposta paginada 
{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 120,
    "has_more": true
  }
}

Limites de taxa

Each token is limited to 60 requests per minute by default.

Quando o limite for excedido, a API retorna HTTP 429. Implemente um backoff exponencial. Contacte o suporte para limites mais elevados.

Permissões

Tokens recebem permissões com escopo. Endpoints rejeitam solicitações quando o escopo necessário está ausente.

API v1 scopes

EscopoDescrição
account:readRead account and token metadata
me:readRead current user profile, permissions, domains, and security
me:writeUpdate current user profile
users:readList account users and domain access
users:writeCreate, update, and delete account users
tokens:readList active API tokens
tokens:writeCreate and revoke API tokens
domains:readList and read domains
domains:writeCreate, update, and delete domains

Legacy scopes

Válido para tokens existentes de integrações mais antigas. Não é necessário para os novos endpoints de autenticação v1.

EscopoDescrição
email-trust:readRead DMARC/SPF/BIMI trust data
reports:readRead aggregate and compliance reports
integrations:readRead integration settings
integrations:writeManage integrations

Referência da API

Documentação dos endpoints da superfície v1 atual.

Verificação de saúde.

GET /health

Verificação pública do estado. Autenticação não necessária.

CampoTipoDescrição
data.statusstringok quando alcançável
data.versionstringVersão da API (v1)
HTTP 
curl -s "https://developers.skysnag.com/api/v1/health" \
  -H "Accept: application/json"
GET /auth/scopes

Retorna escopos atribuíveis agrupados por v1 e legacy. Não é necessária autenticação.

cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/scopes" \
  -H "Accept: application/json"
JSON — resposta 
{
  "data": {
    "v1": [{"id": "account:read", "description": "...", "group": "v1"}],
    "legacy": [{"id": "domains:read", "description": "...", "group": "legacy"}]
  }
}
GET /auth/me account:read

Retorna a conta autenticada e os metadados para o token utilizado. Alias de GET /account.

cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/me" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"

API do usuário atual

Ler e atualizar o usuário autenticado. Esquemas: users, roles, teams, user_regions, domain_accesses, webauthn_credentials, password_securities.

GET /me me:read

Perfil de usuário atual.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
GET /me/permissions me:read

Permissões efetivas derivadas da função do usuário e das configurações da conta.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me/permissions" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
GET /me/domains me:read

Domínios visíveis para o usuário atual. Suporta page e limit.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me/domains?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
GET /me/security me:read

Status de segurança da autenticação multifator (MFA) e da passkey do usuário atual.

cURL 
curl -s "https://developers.skysnag.com/api/v1/me/security" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
PATCH /me me:write

Atualize o perfil do usuário atual.

CampoTipoDescrição
NomestringNome de exibição (máx. 50 caracteres)
IdiomastringCódigo de idioma preferido
cURL 
curl -s "https://developers.skysnag.com/api/v1/me" \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here" \
  -d '{
    "name": "Updated Name"
  }'

API de gerenciamento de usuários

Gerenciar membros da equipe da conta. Exige que a conta autenticada seja a proprietária da equipe. Esquemas: users, roles, teams, domain_accesses, password_securities, webauthn_credentials, user_detail_changes_history.

GET /roles users:read

Liste as funções que podem ser atribuídas ao convidar ou atualizar membros da equipa. Proprietário, Administrador e Editor estão excluídos.

GET /roles/{role_id} users:read

Obter detalhes de um único papel atribuível.

GET /users users:read

Listar usuários da conta na equipe atual.

POST /users users:write

Criar um convite para um membro da conta. Por padrão, um e-mail de convite é enviado.

GET /users/{user_id} users:read

Obter detalhes do usuário.

PATCH /users/{user_id} users:write

Atualizar dados do usuário.

DELETE /users/{user_id} users:write

Excluir um membro da equipe.

PATCH /users/{user_id}/status users:write

Alternar o status do usuário. Corpo: {"enabled": true}

PATCH /users/{user_id}/role users:write

Alterar função. Corpo: {"role_id": 5}

PATCH /users/{user_id}/enforce-2fa users:write

Alternar a aplicação da autenticação de dois fatores (2FA). Corpo: {"enabled": true}

POST /users/{user_id}/reinvite-user users:write

Reenviar o e-mail de convite da conta para um membro da equipe existente.

GET /users/{user_id}/domains users:read

Listar acessos a domínios de um usuário.

API de gestão de domínios

Gerenciar domínios da conta. Operações de escrita requerem a conta do proprietário da equipe. Esquemas: domains, domain_groups, domain_accesses, domain_states, domain_snapshot, parked_domains, license_domain, domains_services, cloudflare_records.

GET /domains domains:read

Lista os domínios visíveis para a conta. Suporta page e limit.

POST /domains domains:write

Criar um domínio. Corpo: {"fqdn": "example.com", "parent_domain_id": null}

POST /domains/bulk domains:write

Adicionar domínios em lote. Corpo: {"domains": ["example.com", "example.org"]}. Retorna um ID de trabalho.

GET /domains/bulk/{job_id} domains:read

Obter o estado do trabalho de adição em massa e os resultados por domínio.

GET /domains/{domain_id} domains:read

Obter detalhes do domínio, incluindo DNS e estado de verificação.

PATCH /domains/{domain_id} domains:write

Editar metadados do domínio (grupo, status, status de integração, domínio pai)

DELETE /domains/{domain_id} domains:write

Excluir um domínio e os registros hospedados relacionados.

POST /domains/{domain_id}/verify domains:write

Verificar os registros DNS do domínio. Campos opcionais do corpo: dmarc_record, spf_record, bimi_record, tls_rpt_record, mta_sts_record.

POST /domains/{domain_id}/check-dns domains:write

Executar uma consulta/verificação DNS e armazenar o resultado para recuperação posterior.

GET /domains/{domain_id}/dns-fetch-result domains:read

Recupera o último resultado de busca DNS armazenado pelo check-dns (em cache por 7 dias). O corpo da resposta do check-dns já inclui o resultado completo; use este endpoint para recuperá‑lo mais tarde sem executar novamente a verificação.

GET /domains/{domain_id}/status domains:read

Obter estado de verificação dos protocolos (DMARC, SPF, MTA-STS, TLS-RPT, BIMI).

GET /domains/{domain_id}/services domains:read

Obter serviços de envio de e-mail anexados.

PATCH /domains/{domain_id}/services domains:write

Substituir serviços anexados. Corpo: {"service_ids": [1, 2]}

API de grupos de domínios

Organizar domínios em grupos. Os grupos pertencem à equipe da conta; é necessário um proprietário da equipe para operações de escrita.

GET /domain-groups domains:read

Listar grupos de domínios da conta com o número de domínios.

POST /domain-groups domains:write

Criar um grupo de domínios. Corpo: {"name": "Production", "status": "active"} (status opcional).

GET /domain-groups/{group_id} domains:read

Obter um único grupo de domínios.

PATCH /domain-groups/{group_id} domains:write

Editar um grupo de domínios. Corpo: {"name": "New name", "status": "active"} (ambos opcionais).

DELETE /domain-groups/{group_id} domains:write

Eliminar um grupo de domínios. Os domínios membros são removidos do grupo, não eliminados.

GET /domain-groups/{group_id}/domains domains:read

Listar domínios em um grupo (paginado)

POST /domain-groups/{group_id}/domains domains:write

Adicionar um domínio ao grupo. Corpo: {"domain_id": 123}.

DELETE /domain-groups/{group_id}/domains/{domain_id} domains:write

Remover um domínio do grupo (o domínio deixará de pertencer ao grupo)

API DMARC hospedada

Gerencie os registros DNS DMARC hospedados pela Skysnag, a política de aplicação, o histórico e as recomendações para um domínio. É necessário ser proprietário da equipe para realizar operações de escrita.

GET /domains/{domain_id}/hosted-dmarc domains:read

Retorna o nome do registro hospedado, o valor, o estado de ativação e a política atual.

POST /domains/{domain_id}/hosted-dmarc domains:write

Provisionar o registro TXT DMARC hospedado pela Skysnag para o domínio.

PATCH /domains/{domain_id}/hosted-dmarc domains:write

Atualizar tags DMARC avançadas: p, sp, pct, adkim, aspf, rua, ruf, etc.

DELETE /domains/{domain_id}/hosted-dmarc domains:write

Remover o registro DMARC hospedado do DNS da Skysnag.

GET /domains/{domain_id}/dmarc-policy domains:read

Leia a política DMARC efetiva e as configurações de tags analisadas.

PATCH /domains/{domain_id}/dmarc-policy domains:write

Atualizar apenas a aplicação da política. Corpo: {"policy": "quarantine"} ou {"p": "reject"}

GET /domains/{domain_id}/dmarc/history domains:read

Registros de atividade e instantâneos DMARC. Suporta page e limit.

POST /domains/{domain_id}/dmarc/recommendation domains:read

Nível de aplicação sugerido com base nas estatísticas de alinhamento e no período de monitoramento.

API SPF hospedada

Gerencie registros SPF hospedados pela Skysnag, inclusões (include), ações de autorização de IP e flattening para um domínio. É necessário ser proprietário da equipe para operações de escrita.

GET /domains/{domain_id}/hosted-spf domains:read

Retorna o nome/valor do registro SPF hospedado, o registro a publicar no seu domínio, o estado de ativação, o qualificador terminal all e o número de consultas.

POST /domains/{domain_id}/hosted-spf domains:write

Configure o registo SPF hospedado pela Skysnag para o domínio.

PATCH /domains/{domain_id}/hosted-spf domains:write

Editar configurações avançadas de SPF. Corpo: {"all": "~all"} (uma das opções -all, ~all, ?all, +all).

DELETE /domains/{domain_id}/hosted-spf domains:write

Desative o SPF hospedado e remova o registro do DNS do Skysnag.

GET /domains/{domain_id}/spf/history domains:read

Registros de atividade SPF e instantâneos de registros. Suporta page e limit.

GET /domains/{domain_id}/spf/includes domains:read

Listar os includes SPF configurados para o domínio.

POST /domains/{domain_id}/spf/includes domains:write

Adicionar um include SPF. Corpo: {"include_content": "_spf.google.com"}

DELETE /domains/{domain_id}/spf/includes/{include_id} domains:write

Remover um include SPF do registro hospedado.

GET /domains/{domain_id}/spf/ip-actions domains:read

Lista de ações de autorização de IP SPF (Permitir / Rejeitar).

POST /domains/{domain_id}/spf/ip-actions domains:write

Autorizar ou bloquear um IP. Body: {"ip": "203.0.113.10", "type": "Allow"} (type = Allow ou Reject).

POST /domains/{domain_id}/spf/flatten domains:read

Gera um registro SPF achatado resolvendo includes em intervalos de IP. Retorna o registro achatado, as listas IPv4/IPv6 e a contagem de consultas DNS em relação ao limite.

API de BIMI / VMC

Gerenciar registros BIMI, logotipos SVG, certificados VMC e verificações de prontidão. É necessário o proprietário da equipe para operações de gravação.

GET /bimi/registrations account:read

Listar solicitações de registro BIMI de parceiros para a equipe de contas.

GET /domains/{domain_id}/bimi domains:read

Retorna detalhes do registro BIMI, alvos DNS, status do logotipo/VMC e resultados da inspeção SVG.

POST /domains/{domain_id}/bimi domains:write

Provisionar BIMI hospedado para o domínio.

PATCH /domains/{domain_id}/bimi domains:write

Re-sincronizar ou editar BIMI. Republica a partir dos arquivos enviados, ou forneça record_value para uma substituição manual.

DELETE /domains/{domain_id}/bimi domains:write

Excluir a configuração BIMI, os arquivos hospedados e o registro do Route53.

POST /domains/{domain_id}/bimi/svg-convert domains:read

Converter e validar SVG para BIMI Tiny PS. Corpo: {"svg_content": "<svg...>"}

GET /domains/{domain_id}/bimi/vmc domains:read

Análise VMC completa (DNS, cadeia de certificados, validação). Use refresh=true na consulta para ignorar o cache.

POST /domains/{domain_id}/bimi/vmc/inspect domains:read

Inspecionar um certificado PEM sem fazer upload. Corpo: {"pem": "-----BEGIN CERTIFICATE-----..."}

GET /domains/{domain_id}/bimi/readiness domains:read

Lista de verificação de prontidão BIMI/VMC com pontuação, status do protocolo e aprovado/reprovado por verificação

API do MTA-STS

Gerenciar MTA-STS e TLS-RPT hospedados para um domínio. Operações de escrita exigem o proprietário da equipe.

GET /domains/{domain_id}/mta-sts domains:read

Retorna o status do MTA-STS, o modo de política, os destinos CNAME do cliente, os registros DNS hospedados e os metadados da verificação de sincronização.

GET /domains/{domain_id}/mta-sts/web-file domains:read

Retorna o conteúdo do arquivo de política MTA-STS servido em https://mta-sts.{domain}/.well-known/mta-sts.txt.

POST /domains/{domain_id}/mta-sts/setup domains:write

Provisionar registros MTA-STS e TLS-RPT hospedados. Cria uma política padrão (mode: none) a partir dos registros MX ativos quando necessário.

PATCH /domains/{domain_id}/mta-sts/policy domains:write

Atualize a política MTA-STS. Forneça o texto bruto policy ou campos estruturados: mode, max_age e nomes de host mx opcionais.

PATCH /domains/{domain_id}/mta-sts/mode domains:write

Atualizar apenas o modo da política. Corpo: {\"mode\": \"none|testing|enforce\"}. Os registros MX são atualizados a partir do DNS ao vivo.

POST /domains/{domain_id}/mta-sts/reset domains:write

Redefinir a política para os valores padrão: mode: none, registros MX atuais, max_age: 604800.

POST /domains/{domain_id}/mta-sts/check domains:read

Execute a validação MTA-STS e TLS-RPT através do serviço de verificação. Corpo opcional: verify_dns, require_caa, deploy_policy (padrão true ao verificar DNS).

API de TLS-RPT

Configurar o TLS-RPT hospedado e consultar os relatórios TLS recebidos. É necessário o proprietário da equipe para operações de escrita.

GET /domains/{domain_id}/tls-rpt domains:read

Retorna a configuração TLS-RPT, os alvos DNS, o estado de verificação e a contagem total de relatórios.

POST /domains/{domain_id}/tls-rpt/setup domains:write

Provisionar um TLS-RPT hospedado no Route53 com o endereço de relatório da Skysnag.

PATCH /domains/{domain_id}/tls-rpt domains:write

Republicar o registro TLS-RPT hospedado. Corpo opcional: record_value (deve começar com v=TLSRPTv1).

GET /domains/{domain_id}/tls-rpt/reports domains:read

Relatórios TLS paginados. Filtros: policy_domain, policy_mode, start_date, end_date.

GET /domains/{domain_id}/tls-rpt/reports/{report_id} domains:read

Obter um único relatório TLS pelo ID do banco de dados ou UUID do relatório.

GET /domains/{domain_id}/tls-rpt/by-source domains:read

Agrega sessões TLS agrupadas pelo IP do MTA remetente. Suporta os mesmos filtros de data e de política.

GET /domains/{domain_id}/tls-rpt/by-result domains:read

Consolidar sessões com falha agrupadas por tipo de resultado TLS.

GET /domains/{domain_id}/tls-rpt/failures domains:read

Resumo de falhas TLS com totais de sucessos/falhas e detalhamento por código de motivo da falha.

GET /domains/{domain_id}/tls-rpt/failure-details domains:read

Linhas paginadas com falhas TLS (contagens de falha diferentes de zero ou códigos de motivo de falha)

API de pontuação de saúde e segurança do domínio

Read-only domain health, email security score, mail volume, sending services, failing sources, and cached dashboard data. All endpoints are scoped to {domain_id} and require domains:read. Volume/source endpoints accept optional start_date/end_date (YYYY-MM-DD, default last 30 days).

Obter estado do domínio

get /domains/{domain_id}/health domains:read

Instantâneo da integridade atual do domínio: um mapa de aprovação/queda por protocolo, um rótulo qualitativo result, o provedor de e-mail detectado e o registro DMARC ativo. Obtido a partir da última varredura do Domain Guard; quando não há varredura, recorre-se às verificações em tempo real (o campo source indica qual).

Devoluções

source (guard_history | live), result, mail_provider, um mapa protocols de valores booleanos, protocols_passing/total_protocols, o dmarc_record e scanned_at.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/health" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "source": "guard_history",
    "result": "Protected",
    "mail_provider": "Google Workspace",
    "protocols": {
      "dmarc": true,
      "spf": true,
      "mta_sts": true,
      "tls_rpt": true,
      "bimi": false
    },
    "protocols_passing": 4,
    "total_protocols": 5,
    "dmarc_record": "v=DMARC1; p=reject; rua=mailto:rua@example.com",
    "scanned_at": "2026-06-16T03:00:00Z"
  }
}

Obter histórico do estado do sistema

get /domains/{domain_id}/health/history domains:read

Histórico paginado de instantâneos de integridade do Domain Guard, do mais recente para o mais antigo. Cada linha registra o estado de sucesso/falha do protocolo e o rótulo de resultado no momento da varredura, permitindo visualizar a proteção ao longo do tempo.

Parâmetros de consulta

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • page: OPCIONAL integer

    Número da página, baseado em 1 (padrão: 1).

  • limit: OPCIONAL integer

    Itens por página (1–100, padrão 25).

Devoluções

Um array paginado de linhas de snapshot (id, result, mail_provider, mapa protocols, protocols_passing/total_protocols, scanned_at) além de pagination.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/health/history?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": [
    {
      "id": 8841,
      "result": "Protected",
      "mail_provider": "Google Workspace",
      "protocols": { "dmarc": true, "spf": true, "mta_sts": true, "tls_rpt": true, "bimi": false },
      "protocols_passing": 4,
      "total_protocols": 5,
      "scanned_at": "2026-06-16T03:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Obter pontuação de segurança

get /domains/{domain_id}/security-score domains:read

A pontuação atual de segurança de e-mail (0–10) com uma interpretação legível por humanos e uma mensagem. Calculada sob demanda a partir de resultados em cache de verificadores externos, portanto a primeira chamada após uma falta de cache pode ser mais lenta. Retorna 503 score_unavailable se não puder ser calculada.

Devoluções

score, max_score (10), interpretation (por exemplo excellent), uma message e computed_at.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/security-score" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "score": 9,
    "max_score": 10,
    "interpretation": "excellent",
    "message": "Your domain is well protected against spoofing and phishing.",
    "computed_at": "2026-06-16T12:30:00Z"
  }
}

Obter histórico da pontuação de segurança

get /domains/{domain_id}/security-score/history domains:read

Uma série de pontuação de segurança derivada calculada a partir de instantâneos do Domain Guard, onde derived_score = passing protocols / 5 × 10. Use-a para uma linha de tendência quando você não precisar da pontuação completa do live-checker.

Parâmetros de consulta

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • limit: OPCIONAL integer

    Número máximo de linhas a retornar (1–100, padrão: 10).

Devoluções

max_score, uma note explicativa e um array history de pontos (derived_score, protocols_passing/total_protocols, result, scanned_at).
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/security-score/history?limit=30" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "max_score": 10,
    "note": "Derived from Domain Guard protocol coverage.",
    "history": [
      {
        "derived_score": 8,
        "protocols_passing": 4,
        "total_protocols": 5,
        "result": "Protected",
        "scanned_at": "2026-06-16T03:00:00Z"
      }
    ]
  }
}

Obter volume de e-mails

get /domains/{domain_id}/mail-volume domains:read

Histórico diário do volume de e‑mail derivado de dados agregados DMARC: contagens de entregues / em quarentena / rejeitados e resultado DMARC (sucesso/fracasso) por dia, além de totais consolidados para todo o período.

Parâmetros de consulta

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

Devoluções

Um objeto totals e um array timeline, cada entrada indexada por date com volume e contagens de aprovados/reprovados.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/mail-volume?start_date=2026-05-01&end_date=2026-06-01" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "start_date": "2026-05-01",
    "end_date": "2026-06-01",
    "totals": {
      "total": 18432,
      "delivered": 18010,
      "quarantined": 280,
      "rejected": 142,
      "dmarc_pass": 17980,
      "dmarc_fail": 452
    },
    "timeline": [
      {
        "date": "2026-06-01",
        "total": 612,
        "delivered": 600,
        "quarantined": 8,
        "rejected": 4,
        "dmarc_pass": 600,
        "dmarc_fail": 12
      }
    ]
  }
}

Lista de serviços de envio

get /domains/{domain_id}/sending-services domains:read

Enviando fontes com volume, métricas DMARC, uma percentagem de compliance e um status de compliant, partial ou failing. O indicador is_registered_threat marca fontes conhecidas por serem maliciosas.

Parâmetros de consulta

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • limit: OPCIONAL integer

    Número máximo de linhas a retornar (1–100, padrão: 10).

Devoluções

Um array de services, cada um com source_name, o objeto de métricas, compliance, status e is_registered_threat.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/sending-services?limit=10" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "services": [
      {
        "source_name": "Google",
        "total_count": 12040,
        "dmarc": { "pass": 12010, "fail": 30 },
        "compliance": 99.75,
        "status": "compliant",
        "is_registered_threat": false
      }
    ]
  }
}

Listar fontes com falha

get /domains/{domain_id}/failed-sources domains:read

Fontes que falharam no alinhamento do DMARC durante o período, ordenadas pelo volume de falhas. Estas são as fontes de maior prioridade a investigar — remetentes legítimos que precisam corrigir a autenticação ou falsificadores.

Parâmetros de consulta

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • limit: OPCIONAL integer

    Número máximo de linhas a retornar (1–100, padrão: 10).

Devoluções

Um array de failed_sources com a mesma estrutura que sending-services, ordenado por volume de falhas em ordem decrescente.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/failed-sources?limit=10" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "failed_sources": [
      {
        "source_name": "Unknown",
        "total_count": 420,
        "dmarc": { "pass": 0, "fail": 420 },
        "compliance": 0,
        "status": "failing",
        "is_registered_threat": true
      }
    ]
  }
}

Obter cache do painel

get /domains/{domain_id}/dashboard-cache domains:read

Retorna o payload do snapshot do painel pré-computado para o domínio, se existir. Esta é a forma mais rápida de renderizar um painel sem recalcular os agregados. Quando nenhum snapshot existe, cached é false e data é null.

Parâmetros de consulta

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

Devoluções

cached (booleano), cached_at, a janela solicitada e o payload de snapshot data (ou null).
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dashboard-cache" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "cached": true,
    "cached_at": "2026-06-16T03:05:00Z",
    "start_date": "2026-05-17",
    "end_date": "2026-06-16",
    "data": { "summary": { "total_count": 18432 } }
  }
}

API de linha do tempo do DNS

Read-only DNS connect/disconnect timeline, current records, record-value history, change events, and stored snapshots. All endpoints are scoped to {domain_id} and require domains:read. Filterable by record_type and start_date/end_date (YYYY-MM-DD).

Obter a linha do tempo do DNS

get /domains/{domain_id}/dns/timeline domains:read

Um resumo de estado por protocolo (estado atual, carimbos de data/hora da última conexão/desconexão e contagens de conexões), além dos eventos de conexão/desconexão mais recentes. Esta é a vista principal de como cada registro de protocolo se conectou e desconectou ao longo do tempo.

Parâmetros de consulta

  • record_type: OPCIONAL string

    Filtre eventos por um dos seguintes: dmarc, spf, mta_sts, tls_rpt, bimi.

  • action: OPCIONAL string

    Filtrar por connected ou disconnected.

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • limit: OPCIONAL integer

    Número máximo de linhas a retornar (1–100, padrão: 10).

Devoluções

Um summary indexado por protocolo e um array events (id, record_type, action, record_value, status_before/status_after, occurred_at).
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/timeline?limit=50" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "summary": {
      "dmarc": {
        "current_status": "connected",
        "last_connected": "2026-05-02T10:15:00Z",
        "last_disconnected": null,
        "connection_count": 2,
        "disconnection_count": 1
      }
    },
    "events": [
      {
        "id": 5521,
        "record_type": "dmarc",
        "action": "connected",
        "record_value": "v=DMARC1; p=reject; rua=mailto:rua@example.com",
        "status_before": "disconnected",
        "status_after": "connected",
        "occurred_at": "2026-05-02T10:15:00Z"
      }
    ]
  }
}

Obter a configuração DNS atual

get /domains/{domain_id}/dns/current domains:read

O estado atual de cada registro de protocolo: status de conexão, indicador de verificação, carimbos de data/hora da última conexão/desconexão e o último valor conhecido do registro. O SPF adicionalmente informa seu lookup_count de DNS (o limite de 10 consultas DNS é relevante para a validade).

Devoluções

Um mapa protocols indexado por protocolo, cada entrada com current_status, verified, status, last_connected/last_disconnected e record_value.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/current" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "protocols": {
      "dmarc": {
        "current_status": "connected",
        "verified": true,
        "status": "valid",
        "last_connected": "2026-05-02T10:15:00Z",
        "last_disconnected": null,
        "record_value": "v=DMARC1; p=reject; rua=mailto:rua@example.com"
      },
      "spf": {
        "current_status": "connected",
        "verified": true,
        "record_value": "v=spf1 include:_spf.google.com -all",
        "lookup_count": 3
      }
    }
  }
}

Obter histórico de DNS

get /domains/{domain_id}/dns/history domains:read

Um histórico unificado, paginado e cronológico dos valores dos registos — combinando instantâneos DMARC e SPF para que possa ver exatamente o que cada registo continha em cada momento. As linhas SPF incluem lookup_count.

Parâmetros de consulta

  • record_type: OPCIONAL string

    Limitar a dmarc ou spf (padrão: ambos).

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • page: OPCIONAL integer

    Número da página, baseado em 1 (padrão: 1).

  • limit: OPCIONAL integer

    Itens por página (1–100, padrão 25).

Devoluções

Um array paginado de linhas de histórico (record_type, record_value, occurred_at; SPF adiciona lookup_count) além de pagination.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/history?record_type=spf&page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": [
    {
      "record_type": "spf",
      "record_value": "v=spf1 include:_spf.google.com -all",
      "lookup_count": 3,
      "occurred_at": "2026-05-02T10:15:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Listar alterações de DNS

get /domains/{domain_id}/dns/changes domains:read

Um feed paginado de eventos de conexão/desconexão de alteração em todos os protocolos, com a transição de estado (status_before → status_after). Use isto para um feed de atividade em estilo auditoria da saúde do DNS.

Parâmetros de consulta

  • record_type: OPCIONAL string

    Um dos dmarc, spf, mta_sts, tls_rpt, bimi.

  • action: OPCIONAL string

    Filtrar por connected ou disconnected.

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • page: OPCIONAL integer

    Número da página, baseado em 1 (padrão: 1).

  • limit: OPCIONAL integer

    Itens por página (1–100, padrão 25).

Devoluções

Um array paginado de eventos de alteração (id, record_type, action, record_value, status_before/status_after, occurred_at) além de pagination.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/changes?action=disconnected&page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": [
    {
      "id": 5520,
      "record_type": "spf",
      "action": "disconnected",
      "record_value": null,
      "status_before": "connected",
      "status_after": "disconnected",
      "occurred_at": "2026-04-28T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Listar instantâneos DNS

get /domains/{domain_id}/dns/snapshots domains:read

As linhas brutas de snapshot armazenadas, agrupadas por tipo de registro. Ao contrário de /dns/history (que mescla e pagina), isso retorna separadamente os arrays de snapshot subjacentes dmarc e spf.

Parâmetros de consulta

  • record_type: OPCIONAL string

    Limitar a dmarc ou spf (padrão: ambos).

  • start_date: OPCIONAL string · date

    Início inclusivo da janela (YYYY-MM-DD). Por padrão, há 30 dias.

  • end_date: OPCIONAL string · date

    Fim da janela inclusiva (YYYY-MM-DD). Por padrão, hoje.

  • limit: OPCIONAL integer

    Número máximo de linhas a retornar (1–100, padrão: 10).

Devoluções

Um array dmarc e um array spf de linhas de instantâneo (id, record_value, occurred_at; SPF adiciona lookup_count).
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/snapshots?limit=50" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "domain_id": 123,
    "fqdn": "example.com",
    "dmarc": [
      {
        "id": 331,
        "record_value": "v=DMARC1; p=reject; rua=mailto:rua@example.com",
        "occurred_at": "2026-05-02T10:15:00Z"
      }
    ],
    "spf": [
      {
        "id": 902,
        "record_value": "v=spf1 include:_spf.google.com -all",
        "lookup_count": 3,
        "occurred_at": "2026-05-02T10:15:00Z"
      }
    ]
  }
}

API de registros de auditoria

Read-only account API audit logs — every mutating API request (POST/PUT/PATCH/DELETE) plus sensitive reads are recorded with method, path, status, IP, token, and timestamp. Scoped to the token owner's account and require the account:read scope.

The audit log object

Cada endpoint nesta seção retorna linhas deste formato. action é um rótulo estável e legível por humanos para a operação; request_id corresponde ao request_id ecoado no envelope de resposta da chamada original.

Objeto do registro de auditoria 
{
  "id": 90122,
  "request_id": "req_8f2c1a4e",
  "action": "domain.hosted_spf.update",
  "method": "PATCH",
  "path": "/api/v1/domains/123/hosted-spf",
  "status_code": 200,
  "ip_address": "203.0.113.24",
  "token_id": 12,
  "token_name": "CI deploy token",
  "user_id": 45,
  "team_id": 9,
  "created_at": "2026-06-16T11:02:33Z"
}

Listar registros de auditoria

get /audit-logs account:read

Registos de auditoria paginados para a conta, do mais recente para o mais antigo. Combine filtros para restringir o feed — por ex., todas as operações de escrita falhadas num intervalo de datas.

Parâmetros de consulta

  • method: OPCIONAL string

    Método HTTP, por exemplo POST.

  • action: OPCIONAL string

    Rótulo de ação exato, por exemplo: domain.hosted_spf.update.

  • path: OPCIONAL string

    Correspondência de substring no caminho da solicitação.

  • status_code: OPCIONAL integer

    Status HTTP exato, por exemplo 200.

  • status_class: OPCIONAL string

    Família de status: 2xx, 3xx, 4xx, 5xx.

  • ip_address: OPCIONAL string

    IP exato do cliente

  • token_id: OPCIONAL integer

    Filtrar para um único token de API.

  • q: OPCIONAL string

    Pesquisa de texto livre em ação, caminho e endereço IP.

  • start_date: OPCIONAL string · date

    Início da janela inclusivo (YYYY-MM-DD).

  • end_date: OPCIONAL string · date

    Término da janela inclusivo (YYYY-MM-DD).

  • page: OPCIONAL integer

    Número da página (padrão: 1).

  • limit: OPCIONAL integer

    Itens por página (1–100, padrão 25).

Devoluções

Um array paginado de objetos de registro de auditoria e um objeto pagination.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/audit-logs?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": [
    {
      "id": 90122,
      "request_id": "req_8f2c1a4e",
      "action": "domain.hosted_spf.update",
      "method": "PATCH",
      "path": "/api/v1/domains/123/hosted-spf",
      "status_code": 200,
      "ip_address": "203.0.113.24",
      "token_id": 12,
      "token_name": "CI deploy token",
      "user_id": 45,
      "team_id": 9,
      "created_at": "2026-06-16T11:02:33Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Obter registro de auditoria

get /audit-logs/{log_id} account:read

Busca uma única entrada do registro de auditoria por ID, vinculada à conta. Retorna 404 not_found se a entrada não pertencer à conta autenticada.

Parâmetros de caminho

  • log_id: obrigatório integer

    O identificador da entrada do registo de auditoria.

Devoluções

Um único objeto de registro de auditoria.
Exemplo 
curl -s "https://developers.skysnag.com/api/v1/audit-logs/90122" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"
Resposta 
{
  "data": {
    "id": 90122,
    "request_id": "req_8f2c1a4e",
    "action": "domain.hosted_spf.update",
    "method": "PATCH",
    "path": "/api/v1/domains/123/hosted-spf",
    "status_code": 200,
    "ip_address": "203.0.113.24",
    "token_id": 12,
    "token_name": "CI deploy token",
    "user_id": 45,
    "team_id": 9,
    "created_at": "2026-06-16T11:02:33Z"
  }
}

Gerenciamento de tokens

GET /auth/tokens tokens:read

Lista os tokens ativos da conta. Suporta page e limit.

cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/tokens?page=1&limit=25" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here"
POST /auth/tokens tokens:write

Criar um token. O valor completo é retornado apenas uma vez em data.plain_text.

CampoTipoDescrição
nome obrigatóriostringRótulo do token
escopos obrigatórioArray de stringsDe GET /auth/scopes
Expira em {n} diasInteiroOpcional 1–365 dias
cURL 
curl -s "https://developers.skysnag.com/api/v1/auth/tokens" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: sk_snag_your_token_here" \
  -d '{
    "name": "CI token",
    "scopes": ["account:read"],
    "expires_in_days": 90
  }'

Precisa de ajuda? Entre em contato support@skysnag.com e incluir o request_id de qualquer resposta de erro. Baixar a coleção do Postman testar endpoints de forma interativa