API de oposición para remitentes

La API tiene dos endpoints. /v1/suppression/check responde para un destinatario a la vez y se usa en tiempo real — por ejemplo en una cola de marcación o justo antes de un envío. /v1/suppression/batch recibe una lista y se usa cuando se está preparando una campaña.

Ambos aceptan identificadores con hash. Ningún endpoint devuelve datos personales, y ninguno confirma que una persona exista en nuestro sistema — solo que no se debe contactar con ese hash.

Una respuesta con suppressed: false significa que no tenemos constancia de ninguna oposición. Eso no es consentimiento, y no sustituye tu propia valoración de licitud.

Cada llamada lleva una clave en la cabecera Authorization. Las claves están vinculadas a un entorno: mm_test_ para el entorno de pruebas, mm_live_ para producción. Una clave usada contra el entorno equivocado se rechaza con 401 en lugar de aplicarse igualmente sin avisar.

Authorization: Bearer mm_live_…Content-Type: application/jsonIdempotency-Key: <uuid v4>   # recomendado para cada llamada de escritura

El hash se calcula en tu lado, con un pepper único para tu organización. Eso consigue dos cosas: no podemos reconstruir el dato de contacto, y una filtración de tus hashes no se puede cruzar con los de nadie más.

# 1. Normaliza a E.164 antes que nada  070-123 45 67        ->  +46701234567  Name@Example.COM     ->  name@example.com # 2. Aplica el hash con tu pepper asignado (nunca en el cliente)  sha256(pepper + normalized) # 3. Envía el hash, nunca el valor  "identifier_hash": "sha256:9f1a3c…c07d",

La normalización tiene que ocurrir antes del hash. 070-123 45 67 y +46 70 123 45 67 son el mismo abonado pero cadenas distintas — sin normalizar, el hash da resultados diferentes y la comprobación no detecta la oposición.

Se usa por destinatario, en tiempo real. El tiempo de respuesta está pensado para encajar dentro de un flujo de llamada, de modo que la comprobación puede ir justo antes de marcar.

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

Guarda receipt_id junto con tu registro de envíos. Es la única referencia que vincula tu comprobación con nuestra respuesta si alguna vez se cuestiona el resultado.

Envía hasta 10.000 hashes por llamada. La lista de resultados siempre tiene el mismo orden y la misma longitud que identifier_hashes, así que puedes indexar directamente sin tener que emparejar por valores.

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"  ]} # Respuesta: mismo orden que la solicitud, nunca se reordena{  "results": [    { "suppressed": true,  "scope": "sender" },    { "suppressed": false, "scope": null }  ],  "receipt_id": "rcpt_01HZK4Q2M8V44P"}

Las listas más grandes las divides tú, no nosotros. Una llamada que supera el límite se rechaza con 400 en lugar de truncarse sin avisar.

Todos los errores se devuelven en JSON con los campos error y message. El código de estado es el que manda — léelo antes que el cuerpo.

• 200OK — La comprobación se completó. Consulta suppressed para conocer el resultado.
• 202Accepted — El lote se recibió pero se procesa de forma asíncrona. Recupera el resultado con receipt_id.
• 400Bad Request — No se pudo interpretar el cuerpo, o a identifier_hash le falta el prefijo sha256:.
• 401Unauthorized — Falta la clave, ha sido revocada, o pertenece a otro entorno.
• 409Conflict — La Idempotency-Key se reutilizó con un cuerpo diferente.
• 422Unprocessable — El canal o el propósito no son compatibles. Consulta los valores de channel y purpose indicados arriba.
• 429Too Many Requests — Se ha agotado la cuota. Espera el número de segundos indicado en Retry-After.
• 503Service Unavailable — Mantenimiento planificado o sobrecarga. Reinténtalo con espera exponencial.

Límite de frecuencia

1.000 llamadas por minuto y clave. La cuota restante está en RateLimit-Remaining.

Límite de lote

10.000 hashes por llamada. El exceso se rechaza, nunca se trunca.

Reintentos

Espera exponencial a partir de 1 s. Envía el mismo Idempotency-Key y el intento solo cuenta una vez.

Conservación de datos

Guardamos el recibo y el hash sobre el que preguntaste — nunca nada que se pueda rastrear hasta una persona.