Opt-out-API voor afzenders

De API heeft twee endpoints. /v1/suppression/check beantwoordt voor één ontvanger tegelijk en wordt in realtime gebruikt — bijvoorbeeld in een belwachtrij of vlak voor het versturen. /v1/suppression/batch neemt een lijst en wordt gebruikt bij het voorbereiden van een campagne.

Beide accepteren gehashte identifiers. Geen enkel endpoint geeft persoonsgegevens terug, en geen enkel endpoint bevestigt dat een persoon in ons systeem bestaat — alleen dat de hash niet benaderd mag worden.

Een antwoord met suppressed: false betekent dat wij geen afmelding kennen. Het is geen toestemming en vervangt niet je eigen rechtmatigheidstoets.

Elke aanroep bevat een sleutel in de Authorization-header. Sleutels zijn omgevingsgebonden: mm_test_ voor de testomgeving, mm_live_ voor productie. Een sleutel die tegen de verkeerde omgeving wordt gebruikt, wordt geweigerd met 401 in plaats van stilletjes terug te vallen.

Authorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: <uuid v4>   # aanbevolen voor elke schrijvende aanroep

De hash wordt aan jouw kant berekend, met een peper die uniek is voor je organisatie. Dat doet twee dingen: wij kunnen het contactgegeven niet reconstrueren, en een lek van jouw hashes kan niet worden gekoppeld aan die van iemand anders.

# 1. Normaliseer naar E.164 voordat er iets anders gebeurt  070-123 45 67        ->  +46701234567  Naam@Voorbeeld.NL    ->  naam@voorbeeld.nl # 2. Hash met je toegewezen peper (nooit in de client)  sha256(pepper + normalized) # 3. Stuur de hash, nooit de waarde  "identifier_hash": "sha256:9f1a3c…c07d"

Normalisatie moet gebeuren vóór het hashen. 070-123 45 67 en +46 70 123 45 67 zijn dezelfde abonnee maar verschillende tekenreeksen — zonder normalisatie hashen ze verschillend en mist de controle de afmelding.

Wordt per ontvanger gebruikt, in realtime. De responstijd is ontworpen om in een gespreksflow te passen, zodat de controle vlak voor het bellen kan plaatsvinden.

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": "campagne-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"}

Bewaar receipt_id samen met je verzendlog. Het is de enige referentie die jouw controle koppelt aan ons antwoord als het resultaat ooit ter discussie staat.

Verstuur tot 10.000 hashes per aanroep. De resultatenlijst heeft altijd dezelfde volgorde en dezelfde lengte als identifier_hashes, zodat je er direct doorheen kunt indexeren zonder op waarden te matchen.

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"  ]} # Antwoord: zelfde volgorde als het verzoek, nooit herschikt{  "results": [    { "suppressed": true,  "scope": "sender" },    { "suppressed": false, "scope": null }  ],  "receipt_id": "rcpt_01HZK4Q2M8V44P"}

Grotere lijsten deel je zelf op, wij doen dat niet. Een aanroep die het maximum overschrijdt, wordt geweigerd met 400 in plaats van stilletjes afgekapt.

Alle fouten worden teruggegeven als JSON met de velden error en message. De statuscode is leidend — lees die voordat je de body leest.

• 200OK — De controle is voltooid. Lees suppressed voor het resultaat.
• 202Accepted — De batch is ontvangen maar wordt asynchroon verwerkt. Haal het resultaat op met receipt_id.
• 400Bad Request — De body kon niet worden verwerkt, of identifier_hash mist het voorvoegsel sha256:.
• 401Unauthorized — De sleutel ontbreekt, is ingetrokken, of hoort bij een andere omgeving.
• 409Conflict — De Idempotency-Key is hergebruikt met een andere body.
• 422Unprocessable — Het kanaal of doel wordt niet ondersteund. Zie de waarden voor channel en purpose hierboven.
• 429Too Many Requests — De quotum is op. Wacht het aantal seconden dat in Retry-After staat.
• 503Service Unavailable — Gepland onderhoud of overbelasting. Probeer opnieuw met exponentiële backoff.

Rate limit

1.000 aanroepen per minuut per sleutel. Resterend quotum staat in RateLimit-Remaining.

Batchlimiet

10.000 hashes per aanroep. Een overschrijding wordt geweigerd, nooit afgekapt.

Retries

Exponentiële backoff vanaf 1s. Stuur dezelfde Idempotency-Key en de poging telt maar één keer.

Bewaartermijn van gegevens

Wij bewaren het ontvangstbewijs en de hash waarnaar je vroeg — nooit iets dat we tot een persoon kunnen herleiden.