Skysnag | Référence de l'API

Démarrage rapide

Trois étapes pour votre première requête authentifiée.

Demander l'accès à l'API — Soumettre depuis Demandes d'accès à l'API. Un administrateur active l'accès à l'API sur votre compte.
Créer un jeton à portée limitée — Ouvrez Jetons d'API, sélectionnez les autorisations et copiez immédiatement le jeton complet (affiché une seule fois).
Envoyer des requêtes authentifiées — Inclure X-Api-Token: sk_snag_… dans chaque appel protégé.

cURL — vérification de l'état (sans authentification)

curl -s "https://developers.skysnag.com/api/v1/health" \
  -H "Accept: application/json"

Collection Postman

Importez une collection prête à l'emploi et un environnement pour explorer tous les endpoints v1 dans Postman.

Télécharger la collection — Skysnag-API-v1.postman_collection.json
Télécharger l'environnement — Skysnag-API-v1.postman_environment.json (prérempli avec l'URL de base de cette application : https://developers.skysnag.com/api/v1)
Importer les deux fichiers dans Postman → Importer → faites glisser les fichiers JSON ou sélectionnez-les.
Configurez votre jeton — Dans l'environnement, définissez api_token sur votre jeton complet issu de Jetons d'API.
Exécuter les requêtes — Commencez par System → Health, puis Authentication → Get Me.

Télécharger la collection Télécharger l'environnement

Authentification

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

En-tête	Valeur	Lorsque
`X-Api-Token`	Full token (`sk_snag_`…)	Tous les terminaux protégés

cURL — requête authentifiée

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

Testez l'API dans votre navigateur

Collez un jeton pour activer la console Essayez-le sur les points de terminaison Obtenir ci‑dessous (lecture seule). Les requêtes sont exécutées contre votre compte en production sur https://developers.skysnag.com/api/v1. Le jeton est stocké uniquement dans ce navigateur (localStorage) et n'est jamais envoyé ailleurs que vers cette API.

Aucune clé définie

URL de base et en-têtes

Tous les chemins v1 sont relatifs à l'URL de base indiquée ci-dessous.

Local / préproduction https://developers.skysnag.com/api/v1

Production https://api.skysnag.com/v1

En-tête	Valeur	Notes
Accepter	application/json	Toujours
Type de contenu	application/json	lors de l'envoi d'un corps
`X-Api-Token`	Votre jeton d'API	Points de terminaison protégés
X-Request-Id	UUID (facultatif)	Corréler les journaux ; affiché dans les erreurs

Réponses

Success payloads are wrapped in a data envelope.

JSON — enveloppe de succès

{
  "data": { ... }
}

JSON — GET /health

{
  "data": {
    "status": "ok",
    "version": "v1"
  }
}

Erreurs

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

JSON — enveloppe d'erreur

{
  "error": {
    "code": "missing_api_token",
    "message": "API token is required...",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

HTTP	Code	Description
401	Jeton API manquant	X-Api-Token non fourni
401	Jeton d'API invalide	Jeton inconnu, révoqué ou expiré.
403	Accès à l'API désactivé	Le compte n'a pas accès à l'API
403	Plan API non éligible	Forfait Comply ou d'essai — passer à Protect ou Suite
403	Autorisations insuffisantes	Le jeton n'a pas la portée requise
422	Erreur de validation	Corps de la requête invalide
404	Introuvable	Ressource non trouvée
429	Erreur HTTP	Limite de requêtes dépassée
500	Erreur interne	Erreur de serveur inattendue

Pagination de la liste

List endpoints return pagination metadata alongside data.

Paramètre	Type	Par défaut	Description
page	Entier	1	Numéro de page (à partir de 1)
limite	Entier	varie	Éléments par page (max. 100)

JSON — réponse paginée

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 120,
    "has_more": true
  }
}

Limites de débit

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

Lorsque le seuil est dépassé, l'API renvoie HTTP 429. Mettez en œuvre un backoff exponentiel. Contactez le support pour obtenir des limites supérieures.

Autorisations

Les jetons se voient attribuer des autorisations avec une portée. Les points de terminaison rejettent les requêtes lorsque la portée requise est absente.

API v1 scopes

Périmètre	Description
`account:read`	Read account and token metadata
`me:read`	Read current user profile, permissions, domains, and security
`me:write`	Update current user profile
`users:read`	List account users and domain access
`users:write`	Create, update, and delete account users
`tokens:read`	List active API tokens
`tokens:write`	Create and revoke API tokens
`domains:read`	List and read domains
`domains:write`	Create, update, and delete domains

Legacy scopes

Valide pour les jetons existants des intégrations plus anciennes. Non requis pour les nouveaux points de terminaison d'authentification v1.

Périmètre	Description
`email-trust:read`	Read DMARC/SPF/BIMI trust data
`reports:read`	Read aggregate and compliance reports
`integrations:read`	Read integration settings
`integrations:write`	Manage integrations

Référence de l'API

Documentation des points de terminaison de la surface v1 actuelle.

Contrôle de santé

GET /health

Vérification publique de l'état. Aucune authentification requise.

Champ	Type	Description
`data.status`	string	`ok` si joignable
`data.version`	string	Version de l'API (`v1`)

HTTP

curl -s "https://developers.skysnag.com/api/v1/health" \
  -H "Accept: application/json"

GET /auth/scopes

Renvoie les scopes assignables regroupés par v1 et legacy. Aucune authentification requise.

cURL

curl -s "https://developers.skysnag.com/api/v1/auth/scopes" \
  -H "Accept: application/json"

JSON — réponse

{
  "data": {
    "v1": [{"id": "account:read", "description": "...", "group": "v1"}],
    "legacy": [{"id": "domains:read", "description": "...", "group": "legacy"}]
  }
}

GET /auth/me account:read

Renvoie le compte authentifié et les métadonnées du jeton utilisé. 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 de l'utilisateur actuel

Lire et mettre à jour l'utilisateur authentifié. Schémas : users, roles, teams, user_regions, domain_accesses, webauthn_credentials, password_securities.

GET /me me:read

Profil utilisateur actuel.

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

Autorisations effectives dérivées du rôle de l'utilisateur et des paramètres du compte.

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

Domaines visibles pour l'utilisateur actuel. Prend en charge page et 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

Statut de sécurité de l'authentification multifacteur (MFA) et de la passkey pour l'utilisateur actuel.

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

Mettez à jour le profil de l'utilisateur actuel.

Champ	Type	Description
Nom	string	Nom d'affichage (max. 50 caractères)
`Langue`	string	Code de langue préféré

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 gestion des utilisateurs

Gérer les membres de l'équipe du compte. Exige que le compte authentifié soit le propriétaire de l'équipe. Schémas : users, roles, teams, domain_accesses, password_securities, webauthn_credentials, user_detail_changes_history.

GET /roles users:read

Listez les rôles pouvant être attribués lors de l'invitation ou de la mise à jour des membres de l'équipe. Propriétaire, Administrateur et Éditeur sont exclus.

GET /roles/{role_id} users:read

Obtenir les détails d'un seul rôle assignable.

GET /users users:read

Lister les utilisateurs du compte dans l'équipe actuelle.

POST /users users:write

Créer une invitation pour un membre du compte. Par défaut, un e-mail d'invitation est envoyé.

GET /users/{user_id} users:read

Obtenir les détails de l'utilisateur.

PATCH /users/{user_id} users:write

Mettre à jour les informations de l'utilisateur.

DELETE /users/{user_id} users:write

Supprimer un membre de l'équipe.

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

Basculer l'état de l'utilisateur. Corps : {"enabled": true}

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

Modifier le rôle. Corps : {"role_id": 5}

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

Basculer l'application de l'authentification à deux facteurs (2FA). Corps: {"enabled": true}

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

Renvoyer l'e-mail d'invitation au compte à un membre d'équipe existant.

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

Lister les accès aux domaines pour un utilisateur.

API de gestion des domaines

Gérer les domaines du compte. Les opérations d'écriture nécessitent le compte du propriétaire de l'équipe. Schémas : domains, domain_groups, domain_accesses, domain_states, domain_snapshot, parked_domains, license_domain, domains_services, cloudflare_records.

GET /domains domains:read

Liste les domaines visibles par le compte. Prend en charge page et limit.

POST /domains domains:write

Créer un domaine. Corps : {"fqdn": "example.com", "parent_domain_id": null}

POST /domains/bulk domains:write

Ajouter des domaines en masse. Corps : {"domains": ["example.com", "example.org"]}. Retourne un ID de tâche.

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

Obtenir le statut de la tâche d'ajout en masse et les résultats par domaine.

GET /domains/{domain_id} domains:read

Obtenir les détails du domaine, y compris le DNS et l'état de vérification.

PATCH /domains/{domain_id} domains:write

Modifier les métadonnées du domaine (groupe, statut, statut d'intégration, domaine parent)

DELETE /domains/{domain_id} domains:write

Supprimer un domaine et les enregistrements hébergés associés.

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

Vérifier les enregistrements DNS du domaine. Champs facultatifs dans le corps : dmarc_record, spf_record, bimi_record, tls_rpt_record, mta_sts_record.

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

Effectuer une requête/contrôle DNS et stocker le résultat pour consultation ultérieure.

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

Récupère le dernier résultat de récupération DNS stocké par check-dns (mis en cache pendant 7 jours). Le corps de la réponse de check-dns contient déjà le résultat complet ; utilisez ce point de terminaison pour le récupérer plus tard sans relancer la vérification.

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

Obtenir le statut de vérification des protocoles (DMARC, SPF, MTA-STS, TLS-RPT, BIMI).

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

Obtenir les services d'envoi d'e-mails associés.

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

Remplacer les services attachés. Corps : {"service_ids": [1, 2]}

API des groupes de domaines

Organiser les domaines en groupes. Les groupes appartiennent à l'équipe du compte ; un propriétaire d'équipe est requis pour les opérations d'écriture.

GET /domain-groups domains:read

Lister les groupes de domaines du compte avec le nombre de domaines.

POST /domain-groups domains:write

Créer un groupe de domaines. Corps : {"name": "Production", "status": "active"} (status optionnel).

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

Récupérer un seul groupe de domaines.

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

Modifier un groupe de domaines. Corps : {"name": "New name", "status": "active"} (les deux facultatifs).

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

Supprimer un groupe de domaines. Les domaines membres sont retirés du groupe, pas supprimés.

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

Lister les domaines d'un groupe (avec pagination)

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

Ajouter un domaine au groupe. Corps : {"domain_id": 123}.

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

Supprimer un domaine du groupe (le domaine ne sera plus associé au groupe)

API DMARC hébergée

Gérez les enregistrements DNS DMARC hébergés par Skysnag, la politique d'application, l'historique et les recommandations pour un domaine. Un propriétaire d'équipe est requis pour effectuer des opérations d'écriture.

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

Renvoie le nom de l'enregistrement hébergé, sa valeur, son état d'activation et la politique actuelle.

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

Ajouter l'enregistrement TXT DMARC hébergé par Skysnag pour le domaine.

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

Mettre à jour les balises DMARC avancées : p, sp, pct, adkim, aspf, rua, ruf, etc.

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

Supprimer l'enregistrement DMARC hébergé du DNS de Skysnag.

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

Lisez la politique DMARC effective et les paramètres des balises analysés.

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

Mettre à jour uniquement l'application de la politique. Corps : {"policy": "quarantine"} ou {"p": "reject"}

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

Journaux d'activité et instantanés DMARC. Prend en charge page et limit.

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

Niveau d'application suggéré basé sur les statistiques d'alignement et la période de surveillance.

API SPF hébergée

Gérez les enregistrements SPF hébergés par Skysnag, les includes, les actions d'autorisation IP et le flattening pour un domaine. Un propriétaire de l'équipe est requis pour les opérations d'écriture.

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

Renvoie le nom/valeur de l'enregistrement SPF hébergé, l'enregistrement à publier sur votre domaine, le statut d'activation, le qualificateur terminal all et le nombre de requêtes.

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

Configurez l'enregistrement SPF hébergé par Skysnag pour le domaine.

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

Modifier les paramètres SPF avancés. Corps : {"all": "~all"} (l'une des options -all, ~all, ?all, +all).

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

Désactivez le SPF hébergé et supprimez l'enregistrement du DNS de Skysnag.

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

Journaux d'activité SPF et instantanés d'enregistrements. Prend en charge page et limit.

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

Lister les includes SPF configurés pour le domaine.

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

Ajouter un include SPF. Corps : {"include_content": "_spf.google.com"}

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

Supprimer un include SPF de l'enregistrement hébergé.

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

Liste des actions d'autorisation des IP SPF (Autoriser / Refuser).

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

Autoriser ou bloquer une IP. Body: {"ip": "203.0.113.10", "type": "Allow"} (type = Allow ou Reject).

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

Génère un enregistrement SPF aplati en résolvant les includes en plages d'IP. Renvoie l'enregistrement aplati, les listes IPv4/IPv6 et le nombre de requêtes DNS par rapport à la limite.

API BIMI / VMC

Gérer les enregistrements BIMI, les logos SVG, les certificats VMC et les vérifications de préparation. Le propriétaire de l'équipe est requis pour les opérations d'écriture.

GET /bimi/registrations account:read

Lister les demandes d'enregistrement BIMI des partenaires pour l'équipe des comptes.

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

Retourne les détails de l'enregistrement BIMI, les cibles DNS, le statut du logo/VMC et les résultats de l'inspection SVG.

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

Provisionner BIMI hébergé pour le domaine.

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

Resynchroniser ou modifier BIMI. Republie à partir des fichiers téléchargés, ou transmettez record_value pour un remplacement manuel.

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

Supprimer la configuration BIMI, les fichiers hébergés et l'enregistrement Route53.

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

Convertir et valider le SVG pour BIMI Tiny PS. Corps: {"svg_content": "<svg...>"}

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

Téléversez le logo BIMI (SVG) ou le certificat VMC (PEM) en tant que file multipart.

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

Analyse VMC complète (DNS, chaîne de certificats, validation). Ajoutez refresh=true dans la requête pour contourner le cache.

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

Inspecter un certificat PEM sans le téléverser. Corps: {"pem": "-----BEGIN CERTIFICATE-----..."}

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

Liste de contrôle de préparation BIMI/VMC avec score, statut du protocole et réussite/échec par contrôle

API MTA-STS

Gérer le MTA-STS et TLS-RPT hébergés pour un domaine. Le propriétaire de l'équipe est requis pour les opérations d'écriture.

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

Renvoie l'état MTA-STS, le mode de la politique, les cibles CNAME du client, les enregistrements DNS hébergés et les métadonnées de la vérification de synchronisation.

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

Renvoie le contenu du fichier de politique MTA-STS servi à l'adresse https://mta-sts.{domain}/.well-known/mta-sts.txt.

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

Fournir des enregistrements MTA-STS et TLS-RPT hébergés. Crée une politique par défaut (mode: none) à partir des enregistrements MX actifs si nécessaire.

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

Mettez à jour la politique MTA-STS. Fournissez le texte brut policy ou les champs structurés : mode, max_age et éventuellement les noms d'hôte mx.

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

Mettre à jour uniquement le mode de la politique. Corps : {\"mode\": \"none|testing|enforce\"}. Les enregistrements MX sont rafraîchis depuis le DNS en direct.

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

Réinitialiser la politique aux valeurs par défaut : mode: none, enregistrements MX actuels, max_age: 604800.

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

Exécutez la validation MTA-STS et TLS-RPT via le service de vérification. Corps optionnel : verify_dns, require_caa, deploy_policy (par défaut true lors de la vérification DNS).

API TLS-RPT

Configurer le TLS‑RPT hébergé et consulter les rapports TLS reçus. Le propriétaire de l'équipe est requis pour les opérations d'écriture.

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

Renvoie la configuration TLS-RPT, les cibles DNS, l'état de vérification et le nombre total de rapports.

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

Mettre en place un TLS-RPT hébergé dans Route53 avec l'adresse de rapport de Skysnag.

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

Republier l'enregistrement TLS-RPT hébergé. Corps optionnel : record_value (doit commencer par v=TLSRPTv1).

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

Rapports TLS paginés. Filtres : policy_domain, policy_mode, start_date, end_date.

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

Obtenir un seul rapport TLS via l'ID de la base de données ou l'UUID du rapport.

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

Agrège les sessions TLS groupées par l'IP du MTA expéditeur. Prend en charge les mêmes filtres de date et de politique.

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

Agréger les sessions échouées regroupées par type de résultat TLS.

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

Résumé des échecs TLS avec totaux réussites/échecs et répartition par code de motif d'échec.

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

Lignes paginées avec échecs TLS (nombre d'échecs non nul ou codes de raison d'échec)

API du score de santé et de sécurité du domaine

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).

Obtenir l'état du domaine

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

Aperçu actuel de la santé du domaine : une cartographie succès/échec par protocole, une étiquette qualitative result, le fournisseur de messagerie détecté et l’enregistrement DMARC en direct. Issu du dernier scan Domain Guard ; en l’absence de scan, les vérifications en direct sont utilisées (le source indique la source).

Retours

source (guard_history | live), result, mail_provider, une map protocols de valeurs booléennes, protocols_passing/total_protocols, le dmarc_record et scanned_at.

Exemple

curl -s "https://developers.skysnag.com/api/v1/domains/123/health" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"

Réponse

{
  "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"
  }
}

Obtenir l'historique de l'état du système

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

Historique paginé des instantanés de santé de Domain Guard, du plus récent au plus ancien. Chaque ligne capture l'état réussite/échec du protocole et le libellé du résultat au moment de l'analyse, vous permettant de suivre l'évolution de la protection dans le temps.

Paramètres de requête

start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
page: FACULTATIF integer

Numéro de page, indexé à partir de 1 (par défaut : 1).
limit: FACULTATIF integer

Éléments par page (1–100, par défaut 25).

Retours

Un tableau paginé de lignes de snapshot (id, result, mail_provider, la map protocols, protocols_passing/total_protocols, scanned_at) ainsi que pagination.

Exemple

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"

Réponse

{
  "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
  }
}

Obtenir le score de sécurité

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

Le score actuel de sécurité des e-mails (0–10) avec une interprétation et un message lisibles par un humain. Calculé à la demande à partir de résultats mis en cache de vérificateurs externes, le premier appel après une absence dans le cache peut donc être plus lent. Renvoie 503 score_unavailable s'il ne peut pas être calculé.

Retours

score, max_score (10), interpretation (par ex. excellent), un message et computed_at.

Exemple

curl -s "https://developers.skysnag.com/api/v1/domains/123/security-score" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"

Réponse

{
  "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"
  }
}

Obtenir l'historique du score de sécurité

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

Une série de score de sécurité dérivée calculée à partir des instantanés de Domain Guard, où derived_score = passing protocols / 5 × 10. Utilisez-la comme courbe de tendance lorsque vous n'avez pas besoin du score complet du live-checker.

Paramètres de requête

start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
limit: FACULTATIF integer

Nombre maximum de lignes à renvoyer (1–100, valeur par défaut : 10).

Retours

max_score, une note explicative et un tableau history de points (derived_score, protocols_passing/total_protocols, result, scanned_at).

Exemple

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"

Réponse

{
  "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"
      }
    ]
  }
}

Obtenir le volume des e-mails

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

Historique quotidien du volume de courriels dérivé des données agrégées DMARC : décomptes livrés / mis en quarantaine / rejetés et résultat DMARC (pass/échec) par jour, ainsi que totaux consolidés pour l’ensemble de la période.

Paramètres de requête

start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.

Retours

Un objet totals et un tableau timeline, chaque entrée indexée par date contenant le volume ainsi que le nombre de réussites/échecs.

Exemple

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"

Réponse

{
  "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
      }
    ]
  }
}

Liste des services d'envoi

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

Envoi des sources avec volume, métriques DMARC, un pourcentage de compliance et un status de compliant, partial ou failing. Le marqueur is_registered_threat signale les sources connues comme malveillantes.

Paramètres de requête

start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
limit: FACULTATIF integer

Nombre maximum de lignes à renvoyer (1–100, valeur par défaut : 10).

Retours

Un tableau de services, chacun avec source_name, l'objet de métriques, compliance, status et is_registered_threat.

Exemple

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"

Réponse

{
  "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
      }
    ]
  }
}

Lister les sources échouées

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

Sources ayant échoué à l'alignement DMARC sur la période, classées par volume d'échecs. Ce sont les sources prioritaires à investiguer — soit des expéditeurs légitimes dont l'authentification doit être corrigée, soit des usurpateurs.

Paramètres de requête

start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
limit: FACULTATIF integer

Nombre maximum de lignes à renvoyer (1–100, valeur par défaut : 10).

Retours

Un tableau de failed_sources ayant la même structure que sending-services, trié par volume d'échecs décroissant.

Exemple

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"

Réponse

{
  "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
      }
    ]
  }
}

Récupérer le cache du tableau de bord

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

Renvoie la charge utile (payload) de l'instantané du tableau de bord précalculé pour le domaine, si elle existe. C'est le moyen le plus rapide d'afficher un tableau de bord sans recalculer les agrégats. Lorsqu'aucun instantané n'existe, cached vaut false et data vaut null.

Paramètres de requête

start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.

Retours

cached (booléen), cached_at, la fenêtre demandée et la charge utile de l'instantané data (ou null).

Exemple

curl -s "https://developers.skysnag.com/api/v1/domains/123/dashboard-cache" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"

Réponse

{
  "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 chronologie 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).

Obtenir la chronologie du DNS

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

Un résumé d'état par protocole (état actuel, horodatages des dernières connexions/déconnexions et nombre de connexions) ainsi que les événements récents de connexion/déconnexion. Il s'agit de la vue principale montrant comment chaque enregistrement de protocole s'est connecté et déconnecté au fil du temps.

Paramètres de requête

record_type: FACULTATIF string

Filtrer les événements selon l'un des éléments suivants : dmarc, spf, mta_sts, tls_rpt, bimi.
action: FACULTATIF string

Filtrer par connected ou disconnected.
start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
limit: FACULTATIF integer

Nombre maximum de lignes à renvoyer (1–100, valeur par défaut : 10).

Retours

Un summary indexé par protocole et un tableau events (id, record_type, action, record_value, status_before/status_after, occurred_at).

Exemple

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"

Réponse

{
  "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"
      }
    ]
  }
}

Obtenir la configuration DNS actuelle

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

L'état actuel de chaque enregistrement de protocole : statut de connexion, indicateur de vérification, horodatages de dernière connexion/déconnexion et la dernière valeur connue de l'enregistrement. SPF rapporte en outre son lookup_count DNS (la limite de 10 requêtes DNS est importante pour la validité).

Retours

Une map protocols indexée par protocole, chaque entrée contenant current_status, verified, status, last_connected/last_disconnected et record_value.

Exemple

curl -s "https://developers.skysnag.com/api/v1/domains/123/dns/current" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"

Réponse

{
  "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
      }
    }
  }
}

Obtenir l'historique DNS

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

Un historique unifié, paginé et chronologique des valeurs des enregistrements — fusionnant les instantanés DMARC et SPF pour que vous puissiez voir exactement ce que chaque enregistrement contenait à chaque instant. Les lignes SPF incluent lookup_count.

Paramètres de requête

record_type: FACULTATIF string

Limiter à dmarc ou spf (par défaut : les deux).
start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
page: FACULTATIF integer

Numéro de page, indexé à partir de 1 (par défaut : 1).
limit: FACULTATIF integer

Éléments par page (1–100, par défaut 25).

Retours

Un tableau paginé de lignes d'historique (record_type, record_value, occurred_at ; pour SPF, ajout de lookup_count) ainsi que pagination.

Exemple

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"

Réponse

{
  "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
  }
}

Lister les modifications DNS

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

Un flux paginé d'événements de connexion/déconnexion de changement sur tous les protocoles, avec la transition d'état (status_before → status_after). Utilisez ceci pour un flux d'activité de type audit de la santé DNS.

Paramètres de requête

record_type: FACULTATIF string

L'un des dmarc, spf, mta_sts, tls_rpt, bimi.
action: FACULTATIF string

Filtrer par connected ou disconnected.
start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
page: FACULTATIF integer

Numéro de page, indexé à partir de 1 (par défaut : 1).
limit: FACULTATIF integer

Éléments par page (1–100, par défaut 25).

Retours

Un tableau paginé d'événements de modification (id, record_type, action, record_value, status_before/status_after, occurred_at) ainsi que pagination.

Exemple

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"

Réponse

{
  "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
  }
}

Lister les instantanés DNS

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

Les lignes de snapshot brutes stockées, regroupées par type d'enregistrement. Contrairement à /dns/history (qui fusionne et pagine), cela renvoie séparément les tableaux de snapshots sous-jacents dmarc et spf.

Paramètres de requête

record_type: FACULTATIF string

Limiter à dmarc ou spf (par défaut : les deux).
start_date: FACULTATIF string Â· date

Début inclusif de la fenêtre (YYYY-MM-DD). Par défaut : il y a 30 jours.
end_date: FACULTATIF string Â· date

Fin de la fenêtre inclusive (YYYY-MM-DD). Par défaut : aujourd'hui.
limit: FACULTATIF integer

Nombre maximum de lignes à renvoyer (1–100, valeur par défaut : 10).

Retours

Un tableau dmarc et un tableau spf de lignes d'instantané (id, record_value, occurred_at ; SPF ajoute lookup_count).

Exemple

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"

Réponse

{
  "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 des journaux d'audit

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

Chaque endpoint de cette section renvoie des lignes de cette forme. action est un libellé stable et lisible par des humains pour l'opération ; request_id correspond au request_id renvoyé dans l'enveloppe de réponse de l'appel original.

Objet du journal d'audit

{
  "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"
}

Lister les journaux d'audit

get /audit-logs account:read

Journaux d'audit paginés pour le compte, du plus récent au plus ancien. Combinez les filtres pour affiner le flux — par ex., toutes les opérations d'écriture ayant échoué dans une plage de dates.

Paramètres de requête

method: FACULTATIF string

Méthode HTTP, par ex. POST.
action: FACULTATIF string

Libellé d'action exact, par exemple : domain.hosted_spf.update.
path: FACULTATIF string

Correspondance de sous-chaîne dans le chemin de la requête.
status_code: FACULTATIF integer

Code d'état HTTP exact, p. ex. 200.
status_class: FACULTATIF string

Famille de codes d'état : 2xx, 3xx, 4xx, 5xx.
ip_address: FACULTATIF string

Adresse IP exacte du client
token_id: FACULTATIF integer

Filtrer sur un seul jeton d'API.
q: FACULTATIF string

Recherche en texte libre sur l'action, le chemin et l'adresse IP.
start_date: FACULTATIF string Â· date

Début de la fenêtre inclusif (YYYY-MM-DD).
end_date: FACULTATIF string Â· date

Date de fin incluse (YYYY-MM-DD).
page: FACULTATIF integer

Numéro de page (par défaut : 1).
limit: FACULTATIF integer

Éléments par page (1–100, par défaut 25).

Retours

Un tableau paginé de objets du journal d'audit et un objet pagination.

Exemple

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"

Réponse

{
  "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
  }
}

Rechercher dans les journaux d'audit

post /audit-logs/search account:read

Recherchez les journaux d'audit via un corps JSON en utilisant les mêmes filtres que l'endpoint de liste. Préférez cette méthode à la liste par query-string lorsque vous devez passer method en tant que tableau ou construire des requêtes longues et structurées.

Paramètres du corps (JSON)

q: FACULTATIF string

Recherche en texte libre sur l'action, le chemin et l'adresse IP.
method: FACULTATIF string | array

Une seule méthode ou un tableau, par exemple ["POST","PATCH","DELETE"].
action: FACULTATIF string

Libellé exact de l'action.
path: FACULTATIF string

Correspondance de sous-chaîne dans le chemin de la requête.
status_code: FACULTATIF integer

Statut HTTP exact.
status_class: FACULTATIF string

2xx, 3xx, 4xx ou 5xx.
ip_address: FACULTATIF string

Adresse IP exacte du client
token_id: FACULTATIF integer

Filtrer sur un seul jeton d'API.
start_date: FACULTATIF string Â· date

Début de la fenêtre inclusif (YYYY-MM-DD).
end_date: FACULTATIF string Â· date

Date de fin incluse (YYYY-MM-DD).
page: FACULTATIF integer

Numéro de page (par défaut : 1).
limit: FACULTATIF integer

Éléments par page (1–100, par défaut 25).

Retours

Même payload paginé que GET /audit-logs.

Demander

curl -s "https://developers.skysnag.com/api/v1/audit-logs/search" \
  -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Token: sk_snag_your_token" \
  -d '{
    "q": "domains",
    "method": ["POST", "PATCH", "DELETE"],
    "status_class": "2xx",
    "start_date": "2026-05-01",
    "end_date": "2026-06-01"
  }'

Réponse

{
  "data": [
    {
      "id": 90122,
      "action": "domain.hosted_spf.update",
      "method": "PATCH",
      "path": "/api/v1/domains/123/hosted-spf",
      "status_code": 200,
      "created_at": "2026-06-16T11:02:33Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 312,
    "has_more": true
  }
}

Obtenir le journal d'audit

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

Récupère une seule entrée du journal d'audit par ID, limitée au compte. Retourne 404 not_found si l'entrée n'appartient pas au compte authentifié.

Paramètres de chemin

log_id: requis integer

L'identifiant de l'entrée du journal d'audit.

Retours

Un seul objet de journal d'audit.

Exemple

curl -s "https://developers.skysnag.com/api/v1/audit-logs/90122" \
  -H "Accept: application/json" \
  -H "X-Api-Token: sk_snag_your_token"

Réponse

{
  "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"
  }
}

Gestion des jetons

GET /auth/tokens tokens:read

Liste les jetons actifs du compte. Prend en charge page et 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

Créer un jeton. La valeur complète est renvoyée une seule fois dans data.plain_text.

Champ	Type	Description
`nom` requis	string	Étiquette du jeton
`autorisations` requis	Tableau de chaînes	Depuis `GET /auth/scopes`
Expire dans {n} jours	Entier	Optionnel 1–365 jours

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
  }'