Public API

Reference for the /api/v1 REST API of the SEKOIA deliverability tool: domains, scans, alerts and outgoing webhooks.

Download the OpenAPI description (JSON)Version 1.0.0 - OpenAPI 3.0.3

Detailed route descriptions are in French.

Authentication

Each request carries the Authorization: Bearer sk_live_... header. An organization administrator creates keys on the API and webhooks page; the full key is shown only once.

A key belongs to one organization and has a scope: read only (viewer) or read and scan (member).

Call the API from a server, never from a browser or mobile app: the key would be exposed.

Base URL: https://email.sekoia.ca/api/v1

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

Rate limits

120 requests per minute per key (X-RateLimit-Limit and X-RateLimit-Remaining headers), 20 scans per minute per key, 600 requests per minute per IP address. Beyond that, the API responds 429 with a Retry-After header (in seconds).

Errors

All errors share the same shape. The code is stable and meant for your programs; the message is in French, or in English if the Accept-Language header starts with "en".

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

Routes

get
/domains

List domains

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

API key required.

Responses

  • 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

Add a domain

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.

API key required.

JSON body: CreateDomainRequest

Responses

  • 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

Scan a domain

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.

API key required.

Parameters

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

JSON body: ScanRequest (optional)

Responses

  • 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

DMARC aggregate reports

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.

API key required.

Parameters

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

Responses

  • 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

Google Postmaster Tools data

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.

API key required.

Parameters

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

Responses

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

Get a scan

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

API key required.

Parameters

  • id (path, required) - Identifiant du scan (UUID).

Responses

  • 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

List alerts

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

API key required.

Parameters

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

Responses

  • 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

OpenAPI description

Ce document (OpenAPI 3.0.3), sans authentification.

No authentication.

Responses

  • 200 Document OpenAPI

Outgoing webhooks

Add an https:// URL and choose the events on the API and webhooks page. Each event is sent as a POST with a JSON body.

  • scan.completed - Scan completedEnvoyé après chaque scan enregistré (manuel, API ou monitoring).
  • alert.created - Alert createdEnvoyé pour chaque alerte créée par le monitoring (baisse de score, changement DNS, liste noire...).
  • dmarc.new_source - New DMARC sending sourceEnvoyé 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`.

Example body

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

Verify the signature

The X-Sekoia-Signature header is "sha256=" followed by the hex HMAC-SHA256 of the string timestamp.body, computed with the webhook's whsec_... secret. The timestamp is in X-Sekoia-Timestamp (Unix seconds). Compute the HMAC over the raw received body, compare in constant time and reject timestamps older than 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);
}

Respond with 2xx within 5 seconds. Redirects are not followed and there is no automatic retry: the X-Sekoia-Delivery identifier lets you ignore duplicates.

Public API - documentation - SEKOIA