Kieltorajapinta lähettäjille

Rajapinnassa on kaksi päätepistettä. /v1/suppression/check vastaa yhdelle vastaanottajalle kerrallaan ja sitä käytetään reaaliajassa — esimerkiksi soittojonossa tai juuri ennen lähetystä. /v1/suppression/batch ottaa vastaan listan ja sitä käytetään, kun kampanjaa valmistellaan.

Molemmat hyväksyvät tiivistettyjä tunnisteita. Kumpikaan päätepiste ei palauta henkilötietoja, eikä kumpikaan vahvista, että henkilö on olemassa järjestelmässämme — ainoastaan sen, ettei tiivisteeseen tule ottaa yhteyttä.

Vastaus, jossa on suppressed: false, tarkoittaa, ettemme tiedä kiellosta. Se ei ole suostumus, eikä se korvaa omaa arviotasi käsittelyn lainmukaisuudesta.

Jokainen kutsu kuljettaa avaimen Authorization-otsakkeessa. Avaimet ovat ympäristösidonnaisia: mm_test_ testiympäristöön, mm_live_ tuotantoon. Väärää ympäristöä vasten käytetty avain hylätään koodilla 401 sen sijaan, että se palaisi hiljaisesti johonkin muuhun.

Authorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: <uuid v4>   # suositellaan jokaiselle kirjoituskutsulle

Tiiviste lasketaan sinun puolellasi, organisaatiollesi ainutlaatuisella pepper-arvolla. Tämä tekee kaksi asiaa: emme voi palauttaa yhteystietoa alkuperäiseen muotoonsa, eikä tiivisteidesi vuotoa voida verrata kenenkään muun tiivisteisiin.

# 1. Normalisoi muotoon E.164 ennen mitään muuta  070-123 45 67        ->  +46701234567  Nimi@Esimerkki.FI     ->  nimi@esimerkki.fi # 2. Tiivistä sinulle osoitetulla pepper-arvolla (ei koskaan asiakassovelluksessa)  sha256(pepper + normalized) # 3. Lähetä tiiviste, ei koskaan arvoa  "identifier_hash": "sha256:9f1a3c…c07d"

Normalisoinnin täytyy tapahtua ennen tiivistämistä. 070-123 45 67 ja +46 70 123 45 67 ovat sama tilaaja, mutta eri merkkijonot — ilman normalisointia ne tiivistyvät eri tavalla, ja tarkistus ei löydä kieltoa.

Käytetään per vastaanottaja, reaaliajassa. Vasteaika on suunniteltu sopimaan puhelunkulkuun, joten tarkistus voi olla suoraan ennen soittoa.

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

Tallenna receipt_id lähetyslokisi yhteyteen. Se on ainoa viite, joka yhdistää tarkistuksesi meidän vastaukseemme, jos lopputulos joskus kyseenalaistetaan.

Lähetä enintään 10 000 tiivistettä per kutsu. Tuloslista on aina samassa järjestyksessä ja samanpituinen kuin identifier_hashes, joten voit indeksoida suoraan ilman arvojen täsmäytystä.

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"  ]} # Vastaus: sama järjestys kuin pyynnössä, ei koskaan uudelleenjärjestetty{  "results": [    { "suppressed": true,  "scope": "sender" },    { "suppressed": false, "scope": null }  ],  "receipt_id": "rcpt_01HZK4Q2M8V44P"}

Suuremmat listat pilkot itse, emme me. Kutsu, joka ylittää rajan, hylätään koodilla 400 sen sijaan, että se katkaistaisiin hiljaisesti.

Kaikki virheet palautetaan JSON-muodossa kentillä error ja message. Tilakoodi on ratkaiseva — lue se ennen rungon sisältöä.

• 200OK — Tarkistus valmistui. Lue suppressed-kentästä lopputulos.
• 202Accepted — Erä vastaanotettiin, mutta se käsitellään asynkronisesti. Hae tulos receipt_id:llä.
• 400Bad Request — Runkoa ei voitu jäsentää, tai identifier_hash-kentästä puuttuu sha256:-etuliite.
• 401Unauthorized — Avain puuttuu, se on kumottu tai se kuuluu eri ympäristöön.
• 409Conflict — Idempotency-Key-arvoa käytettiin uudelleen eri rungolla.
• 422Unprocessable — Kanavaa tai käyttötarkoitusta ei tueta. Katso yllä olevat channel- ja purpose-arvot.
• 429Too Many Requests — Kiintiö on käytetty loppuun. Odota Retry-After-otsakkeessa annettu määrä sekunteja.
• 503Service Unavailable — Suunniteltu huolto tai ylikuormitus. Yritä uudelleen eksponentiaalisella viiveellä.

Nopeusrajoitus

1 000 kutsua minuutissa per avain. Jäljellä oleva kiintiö on kentässä RateLimit-Remaining.

Eräkoon yläraja

10 000 tiivistettä per kutsu. Ylimenevä osa hylätään, ei koskaan katkaista.

Uudelleenyritykset

Eksponentiaalinen viive alkaen 1 sekunnista. Lähetä sama Idempotency-Key, niin yritys lasketaan vain kerran.

Tietojen säilytys

Säilytämme kuitin ja tiivisteen, josta kysyit — emme koskaan mitään, minkä voisimme jäljittää henkilöön.