API publique

Référence de l'API REST /api/v1 de l'outil de délivrabilité SEKOIA : domaines, scans, alertes et webhooks sortants.

Télécharger la description OpenAPI (JSON)Version 1.0.0 - OpenAPI 3.0.3

Authentification

Chaque requête porte l'en-tête Authorization: Bearer sk_live_.... Un administrateur de l'organisation crée les clés sur la page API et webhooks ; la clé complète n'est affichée qu'une fois.

Une clé est rattachée à une organisation et a une portée : lecture seule (viewer) ou lecture et scans (member).

Appelez l'API depuis un serveur, jamais depuis un navigateur ou une application mobile : la clé serait exposée.

Adresse de base : https://email.sekoia.ca/api/v1

curl -H "Authorization: Bearer sk_live_..." \
  https://email.sekoia.ca/api/v1/domains

Limites de débit

120 requêtes par minute et par clé (en-têtes X-RateLimit-Limit et X-RateLimit-Remaining), 20 scans par minute et par clé, 600 requêtes par minute et par adresse IP. Au-delà, l'API répond 429 avec l'en-tête Retry-After (en secondes).

Erreurs

Les erreurs ont toutes la même forme. Le code est stable et destiné à vos programmes ; le message est en français, ou en anglais si l'en-tête Accept-Language commence par « en ».

{
  "error": {
    "code": "apiKeyInvalid",
    "message": "Clé d'API invalide ou révoquée"
  }
}

Routes

get
/domains

Lister les domaines

Domaines de l'organisation, plus récents d'abord, avec le dernier scan. Portée minimale : viewer.

Clé d'API requise.

Réponses

  • 200 Liste des domaines
  • 401 Clé absente (`apiKeyMissing`) ou invalide, révoquée (`apiKeyInvalid`)
  • 402 Forfait insuffisant : API non comprise dans le forfait de l'organisation (`planFeatureApi`) ou limite de domaines atteinte (`planLimitDomains`, `POST /domains`)
  • 429 Limite de débit atteinte (`tooManyRequests`)
  • 500 Erreur interne (`internal`)

post
/domains

Ajouter un domaine

Ajoute un domaine à l'organisation et le scanne aussitôt (réponse synchrone, quelques secondes). Avec `scan: false`, le domaine est ajouté sans scan : le premier scan est fait par le monitoring. Portée minimale : member. Compte dans la limite de scans.

Clé d'API requise.

Corps JSON : CreateDomainRequest

Réponses

  • 201 Domaine ajouté (et scan si demandé)
  • 400 Requête invalide (codes `invalidJson`, `invalidRequest`, `domainRequired`, `domainInvalid`, `apiSinceInvalid`...)
  • 401 Clé absente (`apiKeyMissing`) ou invalide, révoquée (`apiKeyInvalid`)
  • 402 Forfait insuffisant : API non comprise dans le forfait de l'organisation (`planFeatureApi`) ou limite de domaines atteinte (`planLimitDomains`, `POST /domains`)
  • 403 Portée de la clé insuffisante (`apiKeyScope`)
  • 409 Domaine déjà suivi (code `apiDomainExists`)
  • 429 Limite de débit atteinte (`tooManyRequests`)
  • 500 Erreur interne (`internal`)

post
/domains/{domain}/scan

Scanner un domaine

Scan complet (SPF, DKIM, DMARC, listes noires, vérifications avancées) d'un domaine déjà suivi. Réponse synchrone. Déclenche l'événement `scan.completed`. Portée minimale : member. Compte dans la limite de scans.

Clé d'API requise.

Paramètres

  • domain (chemin, obligatoire) - Nom de domaine suivi par l'organisation (ex. exemple.ca).

Corps JSON : ScanRequest (facultatif)

Réponses

  • 201 Scan terminé
  • 400 Requête invalide (codes `invalidJson`, `invalidRequest`, `domainRequired`, `domainInvalid`, `apiSinceInvalid`...)
  • 401 Clé absente (`apiKeyMissing`) ou invalide, révoquée (`apiKeyInvalid`)
  • 402 Forfait insuffisant : API non comprise dans le forfait de l'organisation (`planFeatureApi`) ou limite de domaines atteinte (`planLimitDomains`, `POST /domains`)
  • 403 Portée de la clé insuffisante (`apiKeyScope`)
  • 404 Ressource absente de l'organisation (`domainNotFound`, `scanNotFound`)
  • 429 Limite de débit atteinte (`tooManyRequests`)
  • 500 Erreur interne (`internal`)

get
/domains/{domain}/dmarc

Rapports DMARC agrégés

Statistiques des rapports DMARC agrégés (RFC 7489) reçus à l'adresse de réception du domaine (`address`, créée depuis l'interface, page DMARC du domaine) : volume et taux de pass (DKIM ou SPF aligné) sur 7, 30 et 90 jours, tendance quotidienne, sources d'envoi par IP (PTR, fournisseur, pays, classement `authorized`, `review` ou `unauthorized`, 50 principales), rapporteurs. Les rapports arrivent en général 24 à 48 h après l'envoi des courriels et sont conservés 13 mois. Paramètre `days` invalide : 400 (code `dmarcDaysInvalid`). Portée minimale : viewer.

Clé d'API requise.

Paramètres

  • domain (chemin, obligatoire) - Nom de domaine suivi par l'organisation (ex. exemple.ca).
  • days (requête) - Période du détail (tendance, sources, rapporteurs) : 7, 30 (défaut) ou 90 jours.

Réponses

  • 200 Statistiques DMARC
  • 400 Requête invalide (codes `invalidJson`, `invalidRequest`, `domainRequired`, `domainInvalid`, `apiSinceInvalid`...)
  • 401 Clé absente (`apiKeyMissing`) ou invalide, révoquée (`apiKeyInvalid`)
  • 402 Forfait insuffisant : API non comprise dans le forfait de l'organisation (`planFeatureApi`) ou limite de domaines atteinte (`planLimitDomains`, `POST /domains`)
  • 404 Ressource absente de l'organisation (`domainNotFound`, `scanNotFound`)
  • 429 Limite de débit atteinte (`tooManyRequests`)
  • 500 Erreur interne (`internal`)

get
/domains/{domain}/postmaster

Données Google Postmaster Tools

Données Gmail publiées par Google Postmaster Tools pour le domaine, synchronisées chaque jour quand un administrateur a connecté un compte Google (page de l'organisation) : taux de spam signalé, authentification SPF, DKIM et DMARC, erreurs de livraison, conformité calculée par Google, réputation (meilleur effort). Tous les taux sont en pourcentage de 0 à 100. Google publie avec 1 à 2 jours de retard et seulement au-delà d'un volume quotidien suffisant vers Gmail. Sans connexion : `connected` = false et série vide. Paramètre `days` invalide : 400 (code `postmasterDaysInvalid`). Portée minimale : viewer.

Clé d'API requise.

Paramètres

  • domain (chemin, obligatoire) - Nom de domaine suivi par l'organisation (ex. exemple.ca).
  • days (requête) - Période de la série : 7, 30 (défaut) ou 90 jours.

Réponses

  • 200 Données Postmaster Tools
  • 400 Requête invalide (codes `invalidJson`, `invalidRequest`, `domainRequired`, `domainInvalid`, `apiSinceInvalid`...)
  • 401 Clé absente (`apiKeyMissing`) ou invalide, révoquée (`apiKeyInvalid`)
  • 402 Forfait insuffisant : API non comprise dans le forfait de l'organisation (`planFeatureApi`) ou limite de domaines atteinte (`planLimitDomains`, `POST /domains`)
  • 404 Ressource absente de l'organisation (`domainNotFound`, `scanNotFound`)
  • 429 Limite de débit atteinte (`tooManyRequests`)
  • 500 Erreur interne (`internal`)

get
/scans/{id}

Lire un scan

Un scan de l'organisation (manuel, API ou monitoring). Portée minimale : viewer.

Clé d'API requise.

Paramètres

  • id (chemin, obligatoire) - Identifiant du scan (UUID).

Réponses

  • 200 Scan
  • 401 Clé absente (`apiKeyMissing`) ou invalide, révoquée (`apiKeyInvalid`)
  • 402 Forfait insuffisant : API non comprise dans le forfait de l'organisation (`planFeatureApi`) ou limite de domaines atteinte (`planLimitDomains`, `POST /domains`)
  • 404 Ressource absente de l'organisation (`domainNotFound`, `scanNotFound`)
  • 429 Limite de débit atteinte (`tooManyRequests`)
  • 500 Erreur interne (`internal`)

get
/alerts

Lister les alertes

Alertes de l'organisation, plus récentes d'abord. Portée minimale : viewer.

Clé d'API requise.

Paramètres

  • domain (requête) - Filtre sur un domaine.
  • since (requête) - Alertes créées à partir de cette date (ISO 8601).
  • limit (requête) - Nombre maximal d'alertes (50 par défaut, 200 au maximum).

Réponses

  • 200 Liste des alertes
  • 400 Requête invalide (codes `invalidJson`, `invalidRequest`, `domainRequired`, `domainInvalid`, `apiSinceInvalid`...)
  • 401 Clé absente (`apiKeyMissing`) ou invalide, révoquée (`apiKeyInvalid`)
  • 402 Forfait insuffisant : API non comprise dans le forfait de l'organisation (`planFeatureApi`) ou limite de domaines atteinte (`planLimitDomains`, `POST /domains`)
  • 429 Limite de débit atteinte (`tooManyRequests`)
  • 500 Erreur interne (`internal`)

get
/openapi.json

Description OpenAPI

Ce document (OpenAPI 3.0.3), sans authentification.

Sans authentification.

Réponses

  • 200 Document OpenAPI

Webhooks sortants

Ajoutez une adresse https:// et choisissez les événements sur la page API et webhooks. Chaque événement est envoyé en POST avec un corps JSON.

  • scan.completed - Scan terminéEnvoyé après chaque scan enregistré (manuel, API ou monitoring).
  • alert.created - Alerte crééeEnvoyé pour chaque alerte créée par le monitoring (baisse de score, changement DNS, liste noire...).
  • dmarc.new_source - Nouvelle source d'envoi DMARCEnvoyé quand un rapport DMARC agrégé révèle une nouvelle source d'envoi : IP jamais vue pour le domaine qui dépasse 1 % de son volume sur 30 jours (une seule fois par IP et par domaine). L'alerte correspondante déclenche aussi `alert.created`.

Exemple de corps

{
  "id": "0b8f0c1e-6a52-4c3e-9a5e-2f3f1d2c4b10",
  "type": "scan.completed",
  "createdAt": "2026-10-15T12:00:00.000Z",
  "data": {
    "scanId": "5c9d7f5e-1b2a-4c3d-8e9f-0a1b2c3d4e5f",
    "domain": "exemple.ca",
    "score": 82,
    "status": "bon",
    "scoreIncomplete": false,
    "scoringVersion": 3,
    "issuesCount": 2,
    "source": "monitoring",
    "createdAt": "2026-10-15T12:00:00.000Z"
  }
}

Vérifier la signature

L'en-tête X-Sekoia-Signature vaut « sha256= » suivi du HMAC-SHA256, en hexadécimal, de la chaîne horodatage.corps, calculé avec le secret whsec_... du webhook. L'horodatage est dans X-Sekoia-Timestamp (secondes Unix). Calculez le HMAC sur le corps brut reçu, comparez en temps constant et refusez un horodatage de plus de 5 minutes.

import crypto from 'node:crypto';

// rawBody : corps brut reçu (chaîne), avant JSON.parse
export function verifySekoia(rawBody, headers, secret) {
  const timestamp = headers['x-sekoia-timestamp'] || '';
  const signature = headers['x-sekoia-signature'] || '';
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!/^\d+$/.test(timestamp) || age > 300) return false;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Répondez 2xx en moins de 5 secondes. Les redirections ne sont pas suivies et il n'y a pas de nouvel essai automatique : l'identifiant X-Sekoia-Delivery permet d'ignorer un doublon.

API publique - documentation - SEKOIA