API d'opposition pour les expéditeurs

L'API compte deux points d'accès. /v1/suppression/check répond pour un destinataire à la fois et s'utilise en temps réel — par exemple dans une file d'appels ou juste avant un envoi. /v1/suppression/batch prend une liste et s'utilise lors de la préparation d'une campagne.

Les deux acceptent des identifiants hachés. Aucun point d'accès ne renvoie de donnée personnelle, et aucun ne confirme qu'une personne existe dans notre système — seulement que le hachage ne doit pas être contacté.

Une réponse avec suppressed: false signifie que nous ne connaissons pas d'opposition. Ce n'est pas un consentement, et cela ne remplace pas votre propre analyse de licéité.

Chaque appel transporte une clé dans l'en-tête Authorization. Les clés sont liées à un environnement : mm_test_ pour l'environnement de test, mm_live_ pour la production. Une clé utilisée sur le mauvais environnement est rejetée avec 401 plutôt que de basculer silencieusement.

Authorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: <uuid v4>   # recommandé pour chaque appel d'écriture

Le hachage est calculé de votre côté, avec un sel propre à votre organisation. Cela a deux effets : nous ne pouvons pas reconstituer la coordonnée, et une fuite de vos hachages ne peut pas être recoupée avec celle de quelqu'un d'autre.

# 1. Normaliser au format E.164 avant toute chose  070-123 45 67        ->  +46701234567  Name@Example.COM     ->  name@example.com # 2. Hacher avec le sel qui vous est attribué (jamais côté client)  sha256(pepper + normalized) # 3. Envoyer le hachage, jamais la valeur  "identifier_hash": "sha256:9f1a3c…c07d"

La normalisation doit avoir lieu avant le hachage. 070-123 45 67 et +46 70 123 45 67 désignent le même abonné mais sont des chaînes différentes — sans normalisation, elles produisent des hachages différents et la vérification manque l'opposition.

Utilisé par destinataire, en temps réel. Le temps de réponse est conçu pour s'intégrer dans un flux d'appel, afin que la vérification puisse se placer juste avant la composition.

POST /v1/suppression/check HTTP/1.1Host: api.marketmute.comAuthorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: 8c1f0b52-3a77-4a1e-9f0c-2b7d4e11ab90 {  "channel": "phone",                         "identifier_hash": "sha256:9f1a3c…c07d",  "purpose": "direct_marketing",  "sender_ref": "campaign-2026-h2"}

HTTP/1.1 200 OKContent-Type: application/jsonRateLimit-Remaining: 986 {  "suppressed": true,  "channel": "phone",  "scope": "sender",  "effective_from": "2026-03-04T09:12:00Z",  "receipt_id": "rcpt_01HZK4Q2M8V3XT",  "checked_at": "2026-08-19T07:41:02Z"}

Conservez receipt_id avec votre journal d'envoi. C'est la seule référence qui relie votre vérification à notre réponse si le résultat est un jour contesté.

Envoyez jusqu'à 10 000 hachages par appel. La liste de résultats a toujours le même ordre et la même longueur que identifier_hashes, ce qui vous permet d'indexer directement sans faire correspondre les valeurs.

POST /v1/suppression/batch HTTP/1.1Authorization: Bearer mm_live_…Content-Type: application/json {  "channel": "phone",  "purpose": "direct_marketing",  "identifier_hashes": [    "sha256:9f1a3c…c07d",    "sha256:41b8ee…9a20"  ]} # Réponse : même ordre que la requête, jamais réorganisée{  "results": [    { "suppressed": true,  "scope": "sender" },    { "suppressed": false, "scope": null }  ],  "receipt_id": "rcpt_01HZK4Q2M8V44P"}

Les listes plus longues sont découpées par vous, pas par nous. Un appel qui dépasse le plafond est rejeté avec 400 plutôt que d'être tronqué silencieusement.

Toutes les erreurs sont renvoyées en JSON avec les champs error et message. Le code de statut fait foi — lisez-le avant le corps.

• 200OK — La vérification s'est terminée. Lisez suppressed pour le résultat.
• 202Accepted — Le lot a été reçu mais est traité de manière asynchrone. Récupérez le résultat avec receipt_id.
• 400Bad Request — Le corps n'a pas pu être analysé, ou identifier_hash n'a pas son préfixe sha256:.
• 401Unauthorized — La clé est manquante, a été révoquée, ou appartient à un autre environnement.
• 409Conflict — L'Idempotency-Key a été réutilisée avec un corps différent.
• 422Unprocessable — Le canal ou la finalité n'est pas pris en charge. Voir les valeurs de channel et purpose ci-dessus.
• 429Too Many Requests — Le quota est épuisé. Attendez le nombre de secondes indiqué dans Retry-After.
• 503Service Unavailable — Maintenance planifiée ou surcharge. Réessayez avec un backoff exponentiel.

Limite de débit

1 000 appels par minute et par clé. Le quota restant figure dans RateLimit-Remaining.

Plafond du lot

10 000 hachages par appel. L'excédent est rejeté, jamais tronqué.

Nouvelles tentatives

Backoff exponentiel à partir de 1 s. Envoyez le même Idempotency-Key et la tentative ne compte qu'une seule fois.

Conservation des données

Nous conservons le reçu et le hachage que vous avez interrogé — jamais rien qui puisse être relié à une personne.