Automatizar buzones de Sophos Email mediante la API
La Sophos Email Management API cubre todo el ciclo de vida del buzón: buscar el inventario, crear buzones individualmente o en lotes, cambiar nombres y relaciones, y eliminar objetos. La secuencia segura siempre es leer, comparar el estado deseado con el real, realizar un cambio concreto y volver a leer. Un estado HTTP correcto no basta en operaciones en bloque o de relaciones.
Confirmar requisitos y propiedad
Este artículo presupone la introducción a Sophos Email Management API. La autenticación, vigencia del token, resolución del tenant y selección del host regional se explican en Autenticar Sophos Email API y enrutar al tenant. Todas las rutas siguientes requieren:
- URL base regional
${SOPHOS_API_HOST%/}/email/v1; Authorization: Bearer <access-token>,X-Tenant-ID: <tenant-uuid>y, para cuerpos JSON,Content-Type: application/json;- un UUID de buzón donde aparezca
{id}; - el contrato de API vigente. Los esquemas aquí verificados corresponden a Email Management API v1.4.0.
Antes de escribir, determina qué sistema es propietario del inventario. La sincronización de directorios sigue siendo autoritativa para objetos sincronizados. La API no sustituye esa propiedad: el cambio puede sobrescribirse o rechazarse. La especificación documenta 409 para un buzón sincronizado al renombrarlo, eliminarlo individualmente o cambiar alias o delegados. Realiza el cambio en el directorio de origen; no intentes forzarlo con variantes ni reintentos.
Inventariar y buscar todos los buzones
GET /mailboxes devuelve items y pages con fromKey, nextKey, size y maxSize. pageSize admite como máximo 50 registros. Codifica pages.nextKey para URL y pásalo como pageFromKey; el inventario solo termina cuando no existe nextKey. Limita claves repetidas, páginas y duración total.
Solo se permite un parámetro de búsqueda por solicitud: name, nameStartsWith, email, emailStartsWith, createdAfter, createdBefore, type, bulkSenderPrivilegeStatus, blocked, distributionListOwnedBy, alias, aliasesStartWith o delegate. Los tipos son user, distributionList, publicFolder y sharedMailbox; los estados son neverRequested, approvalPending, approved, rejected y revoked. No combines filtros exactos y de prefijo.
Conserva al menos id, type, email, name, createdAt y blocked. También pueden aparecer aliases, delegates, distributionListOwners, bulkSenderPrivilege y policies. El inventario contiene datos personales: no lo vuelques sin filtrar en registros.
Crear, leer y renombrar buzones
| Tarea | Método y ruta | Contrato |
|---|---|---|
| Crear uno | POST /mailboxes | type, email y name obligatorios |
| Crear hasta 10 | POST /mailboxes/bulk | array items obligatorio, máximo 10 |
| Leer uno | GET /mailboxes/{id} | UUID id; devuelve el estado actual |
| Cambiar nombre | PATCH /mailboxes/{id} | name, 1–256 caracteres |
Al crear, email tiene formato de correo y 4–320 caracteres; name, 1–256. type acepta los cuatro valores anteriores. La creación individual devuelve 201; 409 indica que un buzón o alias ya usa la dirección. No inventes otra dirección: localiza el objeto y aclara su propiedad.
La creación masiva también devuelve 201 si solo se creó una parte. Concilia items y errors con cada dirección solicitada, guarda los UUID correctos y corrige únicamente los elementos fallidos. Comprueba cada objeto con GET /mailboxes/{id} comparando type, email y name. Tras renombrar, 201 significa actualizado; el GET posterior debe mostrar el name esperado.
Cambiar alias, delegados y propietarios de listas
Las tres relaciones usan arrays JSON add y remove; ambos pueden ir en una solicitud. Lee antes para evitar un delta vacío o ya aplicado.
| Relación | Ruta | Máximo por add y remove |
|---|---|---|
| Alias | POST /mailboxes/{id}/aliases | 100 |
| Delegados | POST /mailboxes/{id}/delegates | 50 |
| Propietarios de lista | POST /mailboxes/{id}/distribution-list-owners | 1 |
La última operación se aplica a distributionList. En las tres, 200 puede ser éxito parcial. Evalúa added, removed, errors.failedToAdd y errors.failedToRemove; luego verifica el delta exacto mediante GET en aliases, delegates o distributionListOwners. Reintenta solo valores fallidos cuya causa ya se corrigió, nunca toda la solicitud a ciegas.
Son errores habituales un alias ya usado, un alias inexistente o un delegado cuya dirección no tiene buzón. 400 apunta a solicitud o esquema, 404 al ID o contexto del tenant y 409, donde esté documentado, a la propiedad de sincronización.
Solicitar privilegios de remitente masivo
POST /mailboxes/{id}/bulksender-privilege-request exige count entero, period igual a daily, weekly o monthly, y purpose de 2–2048 caracteres. Describe el uso real. El contrato no fija un máximo numérico para count; no inventes uno.
La respuesta 200 contiene accepted. accepted: true confirma la recepción, no la aprobación. Sigue el estado con GET en bulkSenderPrivilege.bulkSenderPrivilegeStatus. Solo presenta otra solicitud tras comprobar el estado y la causa empresarial.
Eliminar sin reintentos ciegos
La eliminación individual usa DELETE /mailboxes/{id}. La respuesta 200 incluye deleted y esa misma clase también está documentada cuando no se encuentra el buzón: comprueba el booleano y vuelve a leer.
POST /mailboxes/delete elimina hasta 20 UUID en el array obligatorio items; la respuesta 200 separa items correctos de errors por id. Antes de eliminar, exporta UUID y dirección y compáralos con un inventario reciente. Elimina objetos sincronizados en su origen.
No reintentes a ciegas: tras un timeout o error inesperado, algunos o todos los buzones pueden haberse eliminado. Comprueba cada UUID por GET o en Sophos Fusion (antes Sophos Central), reconstruye éxitos y fallos por elemento y, con una nueva autorización, envía solo objetivos que siguen existiendo.
Límites, errores y aprobación de producción
Sophos documenta 10.000 solicitudes diarias para Create, Update y Delete, y 20.000 para Get; la guía indica que el límite horario coincide con el diario. Los cambios de nombre, alias, delegados y propietarios cuentan como Update. Ante 429, pausa dentro de límites definidos; no aumentes concurrencia ni repitas mutaciones automáticamente. Para ampliar cuota, contacta con Sophos Support.
Antes de producción, valida: paginación completa y un filtro por solicitud; límites de tipo, correo, nombre y arrays antes de enviar; conciliación por elemento de respuestas masivas y relaciones; GET o inventario tras toda escritura; tratamiento separado de 400, 404, 409, 429 y 5xx; y ausencia de reintentos automáticos de Delete u otras operaciones no idempotentes tras un resultado incierto. Así, la API sigue siendo una herramienta de automatización y no una segunda fuente de verdad en conflicto.