API di opposizione per i mittenti

L'API ha due endpoint. /v1/suppression/check risponde per un destinatario alla volta ed è usato in tempo reale — per esempio in una coda di chiamate o appena prima di un invio. /v1/suppression/batch accetta un elenco ed è usato quando si sta preparando una campagna.

Entrambi accettano identificativi con hash. Nessun endpoint restituisce dati personali, e nessun endpoint conferma che una persona esista nel nostro sistema — solo che l'hash non va contattato.

Una risposta con suppressed: false significa che non siamo a conoscenza di un'opposizione. Non è un consenso, e non sostituisce la tua valutazione di liceità.

Ogni chiamata trasporta una chiave nell'header Authorization. Le chiavi sono vincolate all'ambiente: mm_test_ per l'ambiente di test, mm_live_ per la produzione. Una chiave usata contro l'ambiente sbagliato viene rifiutata con 401 invece di ripiegare silenziosamente.

Authorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: <uuid v4>   # consigliata per ogni chiamata di scrittura

L'hash viene calcolato dal tuo lato, con un pepper unico per la tua organizzazione. Questo ottiene due cose: non possiamo risalire al dato di contatto, e una fuga dei tuoi hash non può essere incrociata con quella di nessun altro.

# 1. Normalizza in E.164 prima di ogni altra cosa  070-123 45 67        ->  +46701234567  Name@Example.COM     ->  name@example.com # 2. Applica l'hash con il tuo pepper assegnato (mai nel client)  sha256(pepper + normalizzato) # 3. Invia l'hash, mai il valore  "identifier_hash": "sha256:9f1a3c…c07d"

La normalizzazione deve avvenire prima dell'hashing. 070-123 45 67 e +46 70 123 45 67 sono lo stesso abbonato ma stringhe diverse — senza normalizzazione producono hash diversi e la verifica non rileva l'opposizione.

Usato per singolo destinatario, in tempo reale. Il tempo di risposta è pensato per stare dentro un flusso di chiamata, così la verifica può stare subito prima della composizione del numero.

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

Conserva receipt_id insieme al tuo log di invio. È l'unico riferimento che collega la tua verifica alla nostra risposta, nel caso in cui l'esito venga mai messo in discussione.

Invia fino a 10.000 hash per chiamata. L'elenco dei risultati ha sempre lo stesso ordine e la stessa lunghezza di identifier_hashes, così puoi indicizzare direttamente senza fare corrispondenze sui valori.

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"  ]} # Risposta: stesso ordine della richiesta, mai riordinato{  "results": [    { "suppressed": true,  "scope": "sender" },    { "suppressed": false, "scope": null }  ],  "receipt_id": "rcpt_01HZK4Q2M8V44P"}

Elenchi più grandi vengono suddivisi da te, non da noi. Una chiamata che supera il limite viene rifiutata con 400 invece di essere troncata silenziosamente.

Tutti gli errori vengono restituiti in JSON con i campi error e message. Il codice di stato è autorevole — leggilo prima del corpo.

• 200OK — La verifica è stata completata. Leggi suppressed per il risultato.
• 202Accepted — Il batch è stato ricevuto ma viene elaborato in modo asincrono. Recupera il risultato con receipt_id.
• 400Bad Request — Il corpo non è stato interpretabile, oppure a identifier_hash manca il prefisso sha256:.
• 401Unauthorized — La chiave manca, è stata revocata, oppure appartiene a un altro ambiente.
• 409Conflict — L'Idempotency-Key è stata riutilizzata con un corpo diverso.
• 422Unprocessable — Il canale o lo scopo non sono supportati. Vedi i valori di channel e purpose sopra.
• 429Too Many Requests — La quota è esaurita. Attendi il numero di secondi indicato in Retry-After.
• 503Service Unavailable — Manutenzione programmata o sovraccarico. Riprova con backoff esponenziale.

Limite di frequenza

1.000 chiamate al minuto per chiave. La quota residua è in RateLimit-Remaining.

Limite del batch

10.000 hash per chiamata. L'eccedenza viene rifiutata, mai troncata.

Ripetizione dei tentativi

Backoff esponenziale a partire da 1s. Invia lo stesso Idempotency-Key e il tentativo conta una sola volta.

Conservazione dei dati

Conserviamo la ricevuta e l'hash su cui hai chiesto — mai nulla che potremmo ricondurre a una persona.