Supresiones

La lista de supresión evita que se envíen correos electrónicos a direcciones que han rebotado, se han desuscrito o han presentado quejas. MailLand administra las supresiones automáticamente a partir de eventos de rebote y queja, y usted puede agregar o eliminar entradas manualmente a través de la API.

Tipos de supresiónCopiar enlace de la sección

Alcances de supresiónCopiar enlace de la sección

Los alcances controlan qué tipos de correos son bloqueados:

Restricciones de alcance:

• HardBounce, Complaint, Invalid, SpamTrap, RoleAddress → solo alcance Global
• SoftBounce → típicamente alcance Marketing
• Unsubscribe → Global, Marketing o List (no Transactional)
• Manual → cualquier alcance

Listar supresionesCopiar enlace de la sección

GET https://api.mail.land/v1/transactional/suppressions

Autentíquese con Authorization: Bearer <token> o X-API-Key: <api key>.

curl https://api.mail.land/v1/transactional/suppressions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parámetros de consultaCopiar enlace de la sección

{
  "items": [
    {
      "id": "k3v9x2m8q1w7z4",
      "email": "[email protected]",
      "suppressionType": "hardBounce",
      "scope": "global",
      "mailingListId": null,
      "mailingListName": null,
      "expiresAt": null,
      "reason": "550 5.1.1 The email account does not exist",
      "bounceType": "Hard",
      "bounceCategory": "invalid_recipient",
      "bounceCount": 1,
      "lastBounceAt": "2026-02-17T12:00:00Z",
      "unsubscribeSource": null,
      "campaignId": null,
      "subscriberId": null,
      "source": "webhook",
      "notes": null,
      "createdAt": "2026-02-17T12:00:01Z",
      "isLocked": false,
      "lockedReason": null
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

mailingListId, campaignId y subscriberId son el id público del recurso relacionado, resuelto dentro de su tenant: nunca el id numérico interno de la fila. Cada uno es null cuando la entrada no tiene ese vínculo, o cuando el recurso vinculado se ha eliminado desde entonces.

Estadísticas de supresiónCopiar enlace de la sección

Obtenga un resumen de su lista de supresión:

GET https://api.mail.land/v1/transactional/suppressions/stats

curl https://api.mail.land/v1/transactional/suppressions/stats \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "totalCount": 5000,
  "globalCount": 3000,
  "marketingCount": 1500,
  "transactionalCount": 200,
  "listCount": 300,
  "hardBounceCount": 2000,
  "softBounceCount": 1500,
  "complaintCount": 500,
  "unsubscribeCount": 700,
  "manualCount": 200,
  "invalidCount": 50,
  "spamTrapCount": 30,
  "roleAddressCount": 20,
  "expiringCount": 85,
  "lastSuppression": "2026-02-17T12:00:01Z"
}

El campo expiringCount muestra los rebotes soft que expirarán dentro de los próximos 7 días.

Verificar si un correo electrónico está suprimidoCopiar enlace de la sección

Verificación individualCopiar enlace de la sección

GET https://api.mail.land/v1/transactional/suppressions/[email protected]&messageType=Marketing

curl "https://api.mail.land/v1/transactional/suppressions/[email protected]&messageType=Marketing" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "email": "[email protected]",
  "isSuppressed": true,
  "messageType": "Marketing"
}

Verificación masivaCopiar enlace de la sección

Verifique hasta 1,000 correos electrónicos a la vez:

POST https://api.mail.land/v1/transactional/suppressions/check-bulk

curl -X POST https://api.mail.land/v1/transactional/suppressions/check-bulk \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]","[email protected]","[email protected]"],"messageType":"Marketing","mailingListId":null}'

{
  "emails": ["[email protected]", "[email protected]", "[email protected]"],
  "messageType": "Marketing",
  "mailingListId": null
}

{
  "suppressedEmails": ["[email protected]"]
}

Agregar una supresiónCopiar enlace de la sección

POST https://api.mail.land/v1/transactional/suppressions

curl -X POST https://api.mail.land/v1/transactional/suppressions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","suppressionType":"Manual","scope":"Global","reason":"Customer requested removal from all lists","notes":"Ticket #4521"}'

{
  "email": "[email protected]",
  "suppressionType": "Manual",
  "scope": "Global",
  "reason": "Customer requested removal from all lists",
  "notes": "Ticket #4521"
}

Devuelve 201 Created con el objeto de supresión completo. El encabezado Location es /v1/transactional/suppressions: la ruta de listado, ya que no existe un endpoint de obtención por id. Use el campo id del cuerpo para identificar la supresión creada, y las secciones "Listar supresiones" o "Verificar si un correo electrónico está suprimido" más abajo para buscarla.

Agregar en masaCopiar enlace de la sección

Agregue hasta 1,000 supresiones a la vez:

POST https://api.mail.land/v1/transactional/suppressions/bulk

curl -X POST https://api.mail.land/v1/transactional/suppressions/bulk \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"emails":[{"email":"[email protected]","suppressionType":"Manual","scope":"Global","reason":"Cleanup"},{"email":"[email protected]","suppressionType":"Manual","scope":"Marketing"}]}'

{
  "emails": [
    { "email": "[email protected]", "suppressionType": "Manual", "scope": "Global", "reason": "Cleanup" },
    { "email": "[email protected]", "suppressionType": "Manual", "scope": "Marketing" }
  ]
}

{
  "totalCount": 2,
  "addedCount": 2,
  "skippedCount": 0,
  "skippedEmails": [],
  "message": "Added 2 suppressions"
}

Los correos electrónicos que ya existen en la lista de supresión se omiten (no se duplican).

Importar desde CSVCopiar enlace de la sección

Desde contenido de textoCopiar enlace de la sección

POST https://api.mail.land/v1/transactional/suppressions/import

curl -X POST https://api.mail.land/v1/transactional/suppressions/import \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"csvContent":"[email protected]\[email protected]\[email protected]","defaultReason":"Imported from legacy system","suppressionType":"Manual","scope":"Global"}'

{
  "csvContent": "[email protected]\n[email protected]\n[email protected]",
  "defaultReason": "Imported from legacy system",
  "suppressionType": "Manual",
  "scope": "Global"
}

Desde carga de archivoCopiar enlace de la sección

POST https://api.mail.land/v1/transactional/suppressions/import-file

curl -X POST "https://api.mail.land/v1/transactional/suppressions/import-file?scope=List&mailingListId=123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "[email protected]"

Cargue un archivo .csv (máx. 5 MB) con direcciones de correo electrónico separadas por comas o saltos de línea. Una fila de encabezado que contenga "email" se omite automáticamente.

Parámetros de consulta:

{
  "totalRows": 1000,
  "importedCount": 950,
  "skippedCount": 40,
  "invalidCount": 10,
  "invalidEmails": ["not-an-email", "missing-domain@", "..."],
  "errors": [],
  "message": "Imported 950 emails. 40 already existed. 10 invalid."
}

Exportar supresionesCopiar enlace de la sección

Descargue su lista de supresión como CSV:

GET https://api.mail.land/v1/transactional/suppressions/export

curl https://api.mail.land/v1/transactional/suppressions/export \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -o suppressions.csv

Devuelve un archivo CSV con las columnas: email, type, scope, mailing_list, reason, bounce_count, source, created_at, expires_at. Limitado a 100,000 filas.

Eliminar una supresiónCopiar enlace de la sección

Por IDCopiar enlace de la sección

DELETE https://api.mail.land/v1/transactional/suppressions/{id}

curl -X DELETE https://api.mail.land/v1/transactional/suppressions/k3v9x2m8q1w7z4 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Por correo electrónicoCopiar enlace de la sección

DELETE https://api.mail.land/v1/transactional/suppressions/[email protected]

curl -X DELETE "https://api.mail.land/v1/transactional/suppressions/[email protected]" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Devuelve 204 No Content en caso de éxito, 404 si no se encuentra.

Supresiones bloqueadasCopiar enlace de la sección

Ciertas supresiones no pueden eliminarse para proteger la reputación de su remitente y cumplir con las regulaciones antispam:

Intentar eliminar una supresión bloqueada devuelve:

{
  "code": "SUPPRESSION_LOCKED",
  "message": "Cannot delete: Spam complaint - compliance requirement",
  "details": {
    "lockedReason": "Spam complaint - compliance requirement"
  }
}

Fuentes de desuscripciónCopiar enlace de la sección

Cuando un destinatario se desuscribe, se registra la fuente:

Respuestas de errorCopiar enlace de la sección

Próximos pasosCopiar enlace de la sección

• Rebotes: comprenda los tipos de rebotes y la supresión automática
• Resumen de entregabilidad: monitoree la reputación del remitente
• Eventos de webhooks: reciba eventos message.bounced (suppression.added/suppression.removed están definidos en el catálogo, pero hoy nunca se emiten)