API reference

https://api.useksar.com · 0.1.0 · x-api-key

Detailed descriptions are in French for now; field names and codes are the same.

POST/v1/check-email

Vérifier une adresse e-mail

Étapes : validation syntaxique, normalisation, whitelist, listes de domaines jetables (sous-domaines compris), vérification MX (timeout 300 ms, résultat en cache), analyse du motif, calcul du score.

Request body application/json

`email`required string
`event` signup \| check	`signup` (défaut) enregistre l’inscription (doublons, séries, rapports) et renvoie un `signup_id` ; `check` analyse seulement (validation en direct d’un formulaire, par exemple).
`external_id` string	Identifiant côté client (ex. `user_123`), stocké tel quel.
`offer` string	Profil d’offre (`offer_profiles` des paramètres), ex. `welcome_10`.

{
  "email": "Jean.Dupont+promo@gmail.com"
}

Responses

200Adresse analysée.
400invalid_email : adresse syntaxiquement invalide. invalid_request : body absent, JSON malformé ou email qui n’est pas une chaîne.
401Clé API absente ou invalide.
403La clé n’a pas le scope check (insufficient_scope), ou le compte est suspendu (account_suspended).
413Body supérieur à 4 Ko.
415Content-Type autre que application/json.
429rate_limit_exceeded : limite de débit de la clé (fenêtre glissante, Retry-After). quota_exceeded : quota mensuel de vérifications de l’offre atteint (comptes en libre-service), jusqu’au 1er du mois suivant (resets_at) ou à un changement d’offre. Dans les deux cas, laissez passer l’inscription : votre formulaire ne doit jamais tomber à cause de l’API.
500Erreur interne.
503Clé jamais vue et base de données injoignable (impossible de l’authentifier). Côté client : accepter l’inscription (fail-open).

{
  "email": "Jean.Dupont+promo@gmail.com",
  "normalized_email": "jeandupont@gmail.com",
  "domain": "gmail.com",
  "risk_score": 0,
  "block": false,
  "reasons": [],
  "checks": {
    "disposable": false,
    "whitelisted_domain": true,
    "mx": "valid",
    "website": "present",
    "suspicious_pattern": false
  }
}

GET/v1/settings

Lire les paramètres du client (scope admin)

Paramètres actuels, valeurs par défaut comprises.

Responses

200Paramètres du client.
401Clé API absente ou invalide.
403La clé n’a pas le scope admin.

PUT/v1/settings

Remplacer les paramètres du client (scope admin)

Remplace l’ensemble des paramètres : un champ absent reprend sa valeur par défaut. Les domaines des listes sont normalisés ; les adresses e-mail sont normalisées puis remplacées par leur empreinte hmac:<64 hex> (propre au client) : elles ne sont jamais stockées ni renvoyées en clair. La prise en compte est immédiate.

Request body application/json

`mode` enforce \| shadow
`disposable_action` block \| deny_offer \| allow
`offer_policy` scored \| grant_all \| deny_all
`block_threshold` integer
`offer_threshold` integer
`deferred_band` integer[]
`privacy_relay_policy` allow \| defer \| deny_offer \| block
`duplicate_policy` object
`allowlist` object
`denylist` object
`offer_profiles` object	Surcharges par profil d’offre (`welcome_10`, `free_trial`…).
`economics` object
`retention_days` integer
`deferred_release_conditions` email_verified \| first_purchase \| account_age_24h[]

{
  "disposable_action": "block",
  "offer_threshold": 40,
  "allowlist": {
    "domains": [
      "partenaire.fr"
    ],
    "emails": []
  },
  "denylist": {
    "domains": [
      "concurrent.example"
    ],
    "emails": [
      "fraudeur@example.com"
    ]
  }
}

Responses

200Paramètres enregistrés (forme normalisée).
400Paramètres invalides (invalid_settings, détail par champ).
401Clé API absente ou invalide.
403La clé n’a pas le scope admin.
503Base de données injoignable.

POST/v1/signups/{signup_id}/events

Renvoyer un événement d’inscription (scope check)

Mode sas : quand offer.decision vaut defer, renvoyez les preuves (e-mail confirmé, premier achat…) ; la réponse indique si l’offre peut maintenant être libérée. account_age_24h se déduit de la date d’inscription. Les événements servent aussi au rapport des économies (offer_redeemed avec value_eur). Idempotent : un même type ne compte qu’une fois par inscription.

Parameters

signup_id (path)required

string

Request body application/json

`type`required email_verified \| first_purchase \| offer_redeemed \| offer_released
`value_eur` number

{
  "type": "email_verified"
}

Responses

200Événement enregistré.
400Type inconnu ou valeur invalide.
401Clé API absente ou invalide.
403La clé n’a pas le scope check.
404Inscription inconnue ou appartenant à un autre client.
503Base de données injoignable.

{
  "offer_release": true,
  "met_conditions": [
    "email_verified"
  ]
}

GET/v1/reports/summary

Rapport des économies (scope admin)

Résumé d’une période (jours UTC, 366 jours maximum ; défaut : mois en cours). estimated_savings_eur est une estimation, dont la méthode est renvoyée : offres refusées × valeur de l’offre, + offres en attente jamais accordées (aucun événement offer_released ni offer_redeemed) × valeur de l’offre. Valeur = moyenne des value_eur réels reçus (offer_redeemed) pour le profil, sinon offer_value_eur configuré. En mode test, les décisions comptées sont celles qui auraient été prises. format=html : rapport HTML en français, prêt à être envoyé par e-mail.

Parameters

`from (query)` string
`to (query)` string
`format (query)` json \| html

Responses

200Résumé de la période.
400Dates invalides ou période trop longue (invalid_request).
401Clé API absente ou invalide.
403La clé n’a pas le scope admin, ou l’offre n’inclut pas le rapport (plan_upgrade_required : Pro et plus).
503Base de données injoignable.

POST/v1/batch

Analyser un fichier CSV en asynchrone (scope admin)

Même moteur que npm run audit. Corps text/csv (5 Mo maximum, virgule ou point-virgule détectés). Réponse immédiate 202 avec job_id ; suivez le statut sur /v1/batch/{job_id}. Le fichier source n’est jamais stocké ; les résultats (sans aucune adresse) sont supprimés après 7 jours.

Parameters

`email_column (query)` string
`coupon_column (query)` string
`date_column (query)` string
`offer_value (query)` string
`delimiter (query)` , \| ;

Request body text/csv

"email,code_utilise\njean@example.com,BIENVENUE\n"

Responses

202Fichier accepté.
400Fichier vide ou paramètres invalides.
401Clé API absente ou invalide.
403La clé n’a pas le scope admin, ou l’offre n’inclut pas l’audit CSV (plan_upgrade_required : Business et plus).
413Fichier supérieur à 5 Mo.
415Content-Type autre que text/csv.

GET/v1/batch/{job_id}

Statut et résumé d’une analyse (scope admin)

Parameters

job_id (path)required

string

Responses

200status : queued, running, done (avec summary et results_url) ou failed (avec error, ex. colonne introuvable).
404Analyse inconnue, expirée ou appartenant à un autre client.

GET/v1/batch/{job_id}/results.csv

Résultats d’une analyse (CSV sans adresse e-mail)

Colonnes : line (numéro de ligne d’origine), status, reasons, duplicate_group.

Parameters

job_id (path)required

string

Responses

200CSV de résultats.
404Analyse inconnue, non terminée ou expirée.

DELETE/v1/subjects

Droit à l’effacement (scope admin)

Supprime toutes les données liées à une adresse pour ce client (inscriptions et empreintes), variantes équivalentes comprises (Jean.Dupont+x@googlemail.com = jeandupont@gmail.com). L’adresse n’est ni stockée ni journalisée. Répond 204 même si rien ne correspondait.

Request body application/json

emailrequired

string

Responses

204Données effacées.
400Adresse invalide.
401Clé API absente ou invalide.
403La clé n’a pas le scope admin.
503Base de données injoignable.

GET/health

Sonde de disponibilité (sans authentification)

Responses

200Service opérationnel.