Ámbitos de API y permisos de los planes
Compara ámbitos de API de TrekMail entre planes, complementos, OAuth, membresías, límites de dominio y controles de seguridad de MCP, incluido White Label.
Detalles del artículo
Tipo, dificultad, planes e información de última actualización.
▼
Detalles del artículo
Tipo, dificultad, planes e información de última actualización.
- Tipo
- Referencia
- Dificultad
- Intermedio
- Planes
- Nano · Starter · Pro · Agency
- Última actualización
- 23 de ago. de 2026
Los ámbitos controlan exactamente lo que puede hacer un token de API. Cada token contiene un conjunto de ámbitos y la API los comprueba en cada solicitud.
Cómo funcionan los ámbitos
Al crear un token, seleccionas qué ámbitos incluir. La API aplica tres límites a cada solicitud:
- Derechos de la cuenta: el plan actual y los complementos activos determinan qué capacidades existen en ese momento.
- Membresía: una persona delegada no puede conceder ni usar más de lo que permiten su rol actual y su acceso a dominios.
- Concesión de credenciales: el token o consentimiento de OAuth debe incluir el ámbito requerido por el endpoint.
El error identifica el límite que falló. insufficient_scope significa que nunca se concedió el ámbito a la credencial, scope_blocked_by_membership indica que el rol de la persona es más limitado y scope_blocked_by_entitlement significa que el derecho requerido de White Label no está activo.
Dos capas de ámbitos: OAuth y ámbitos de API
OAuth admite seis paquetes heredados prácticos, cada ámbito específico de API y selectores tools:* que solo controlan la exposición. Los paquetes heredados son:
| Ámbito de OAuth | Incluye |
|---|---|
mail:read |
Lectura de cuenta, dominios, buzones, reenvío, reglas de correo, respuesta automática, SMTP, Cloudflare y tickets, además de lectura de Drive. |
mail:write |
Todo mail:read, más creación, actualización y eliminación de dominios, buzones, alias, reenvío, reglas, respuesta automática, DNS de Cloudflare, tickets, cargas y elementos compartidos de Drive. |
mail:admin |
Todo mail:write, más facturación, intenciones de eliminación, purgas destructivas de Drive, escrituras de migración, eliminación de tokens de Cloudflare y emisión de tokens de mensajes. |
messages:read |
Lectura del contenido del buzón (mensajes, carpetas, adjuntos, contactos, calendario, identidades y plantillas). |
messages:write |
Cambio de borradores, carpetas, indicadores, contactos, calendarios, plantillas y ajustes sin enviar correo. |
messages:send |
Lectura y envío de correo, incluida la creación de borradores y la programación de mensajes. |
Cada paquete heredado de OAuth se expande en ámbitos específicos de API, como domains:read y drive:account:write. Las integraciones nuevas pueden solicitar directamente esos ámbitos detallados. Los ámbitos de White Label se excluyen deliberadamente de los antiguos paquetes mail:*, por lo que un conector existente nunca obtiene administración de revendedor después de una actualización. Debe solicitar explícitamente los ámbitos requeridos de White Label. Un selector tools:white_label limita la exposición de MCP, pero no concede por sí solo permisos de API.
Tres formas de conexión y cómo concede capacidades cada una
Hay tres formas de que un agente o una integración acceda a TrekMail, y el mecanismo de control es diferente en cada una. Esto importa porque los "indicadores de capacidad" de MCP (TREKMAIL_ALLOW_DESTRUCTIVE, TREKMAIL_ALLOW_SENDING, TREKMAIL_ALLOW_MIGRATION) solo existen en una de ellas.
| Modo | Autenticación | Mecanismo de control | Indicadores de capacidad | Alcance de herramientas y endpoints |
|---|---|---|---|---|
MCP HTTP alojado (https://trekmail.net/mcp, OAuth) |
OAuth 2.1 con paquetes heredados o ámbitos detallados | Derechos actuales, membresía, ámbitos consentidos, conjuntos de herramientas seleccionados y compatibilidad de transporte. | Política de seguridad alojada | El subconjunto permitido por cada límite activo |
MCP stdio autoalojado (@trekmail/mcp-server, local) |
Un token tm_live_ y, cuando sea necesario, un token tm_msg_ |
Ámbitos del token, conjuntos de herramientas seleccionados, modo de solo lectura y ajustes de seguridad del operador. Las herramientas no autorizadas no se registran. | Configuración del operador | El subconjunto permitido por el token y la configuración local |
| API REST directa | Un token bearer tm_live_ o tm_msg_ |
Ámbitos específicos del token, como smtp:read, smtp:write y domains:delete |
No aplicable | Los endpoints permitidos por los ámbitos del token |
En resumen: MCP HTTP alojado filtra las herramientas anunciadas según la credencial OAuth; MCP stdio cruza los ámbitos del token con los conjuntos de herramientas, el modo de solo lectura y los controles de seguridad locales; y la API REST se controla directamente mediante los ámbitos específicos incluidos en el token. La autorización de API en tiempo de ejecución sigue siendo la autoridad definitiva en todos los modos.
Referencia de ámbitos
Cuenta y facturación
| Ámbito | Función | Planes |
|---|---|---|
account:read |
Ver información de la cuenta, plan, límites y uso | Starter · Pro · Agency |
billing:read |
Ver el estado de facturación y el historial de facturas | Starter · Pro · Agency |
billing:autopay |
Pagar compras en tu nombre sin preguntarte cada vez | Todos los planes, incluido Nano |
billing:autopay es el único ámbito que mueve dinero, por lo que conviene leerlo dos veces.
Está separado deliberadamente de billing:read: una conexión autorizada para ver tu factura no debe
poder aumentarla, y conceder lectura de facturación no implica aceptar gastos. Nunca se incluye
automáticamente; un token o conexión solo lo tiene si lo concediste de forma explícita, y no aparece
en ninguno de los antiguos paquetes generales de ámbitos, por lo que una conexión autorizada antes de su creación
no puede gastar nada.
Lo que permite: comprar créditos de verificación de correo e iniciar una suscripción. Lo que no permite en absoluto: cancelar, bajar de plan o cambiar una suscripción existente. Esas acciones no tienen endpoint. Además, el gasto se limita por compra, día y mes para toda la cuenta, independientemente del número de conexiones que tengan el ámbito.
Está disponible en todos los planes porque los créditos de verificación se venden en todos ellos, incluido Nano.
Dominios
| Ámbito | Función | Planes |
|---|---|---|
domains:read |
Enumerar dominios y leer detalles, métricas de spam, direcciones de reenvío y estado de alias de dominio | Starter · Pro · Agency |
domains:create |
Añadir dominios nuevos a la cuenta | Pro · Agency |
domains:write |
Actualizar alias de dominio, catch-all, DKIM, notas, direcciones de reenvío y si el dominio aloja el correo entrante o solo envía | Pro · Agency |
domains:delete |
Eliminar dominios (peligroso) | Pro · Agency |
domains:dns:read |
Ver requisitos de DNS y resultados de comprobación | Starter · Pro · Agency |
domains:dns:recheck |
Iniciar una nueva verificación de DNS | Pro · Agency |
La entrega mediante alias de dominio está disponible desde Starter. Los tokens de Starter pueden leer el estado guardado y actual; conectarlo, cambiarlo o eliminarlo mediante API/MCP requiere la capacidad domains:write de Pro/Agency. Los cambios desde el panel siguen disponibles en Starter. Consulta Alias de dominio mediante API y MCP.
White Label
Estos ámbitos de tokens de operaciones solo aparecen mientras esté activa una prueba o un complemento de pago de White Label. Durante el periodo de gracia de cancelación, el propietario conserva los ámbitos de lectura; se eliminan los miembros delegados y todos los ámbitos de escritura.
| Ámbito | Función | Disponibilidad |
|---|---|---|
branding:read |
Leer marcas, recursos, hosts, estado de la zona de correo y registros DNS requeridos | Derecho activo; propietario durante el periodo de gracia |
branding:write |
Configurar la marca, cargar o eliminar recursos, crear vistas previas y verificar DNS | Derecho activo |
members:read |
Leer el catálogo de acceso y los clientes o miembros del equipo de White Label | Derecho activo; propietario durante el periodo de gracia |
members:write |
Invitar, actualizar, suspender, reanudar, eliminar o restaurar miembros | Derecho activo |
activity:read |
Leer la actividad de White Label de la cuenta y de cada miembro | Derecho activo; propietario durante el periodo de gracia |
La membresía actual impone otro límite. Un cliente o compañero nunca puede ampliar su propio rol, acceso a dominios o permisos personalizados creando un token más amplio. Consulta Gestionar equipos White Label con API y MCP.
Buzones
| Ámbito | Función | Planes |
|---|---|---|
mailboxes:read |
Enumerar y ver buzones, y obtener datos de configuración del cliente de correo sin contraseña | Starter · Pro · Agency |
mailboxes:create |
Crear buzones nuevos | Pro · Agency |
mailboxes:delete |
Eliminar buzones (mediante intenciones de eliminación) | Pro · Agency |
mailboxes:invites:create |
Enviar invitaciones para configurar buzones | Pro · Agency |
mailboxes:forwarding:read |
Ver la configuración de reenvío | Starter · Pro · Agency |
mailboxes:write |
Cambiar contraseña, actualizar notas, pausar/reanudar, suspender/restaurar el inicio de sesión y configurar el acceso a Drive | Pro · Agency |
mailboxes:forwarding:write |
Crear y modificar reglas de reenvío | Pro · Agency |
mailboxes:rules:read |
Ver filtros de correo | Starter · Pro · Agency |
mailboxes:rules:write |
Crear, actualizar y eliminar filtros de correo | Pro · Agency |
mailboxes:auto-reply:read |
Ver la configuración de respuesta automática | Starter · Pro · Agency |
mailboxes:auto-reply:write |
Actualizar la configuración de respuesta automática | Pro · Agency |
mailboxes:message-tokens:manage |
Crear, enumerar y revocar tokens de mensajes | Pro · Agency |
Mensajes (token de mensajes)
| Ámbito | Función | Planes |
|---|---|---|
messages:read |
Acceso de lectura a toda la interfaz de webmail, enumerar/leer mensajes, enumerar carpetas, descargar adjuntos, obtener el origen sin procesar, enumerar mensajes programados, contactos y eventos del calendario, exportar contactos, obtener datos de respuesta/reenvío, enumerar identidades y rutas Enviar como del buzón conectado, plantillas y remitentes bloqueados | Pro · Agency |
messages:write |
Acceso de escritura, actualizar indicadores, eliminar/mover mensajes, informar spam/ham, acciones masivas, crear/cambiar nombre/eliminar carpetas, vaciar Papelera/Correo no deseado, guardar/actualizar borradores, cancelar mensajes programados, crear/actualizar/eliminar contactos y eventos del calendario, importar contactos, crear/actualizar/eliminar grupos de contactos, gestionar miembros de grupos, crear/actualizar/eliminar identidades, establecer política de remitente de respuesta, crear/actualizar/eliminar plantillas y bloquear/desbloquear remitentes | Pro · Agency |
messages:send |
Enviar correo desde el buzón o una identidad Enviar como autorizada y vinculada al origen; también incluye programar mensajes nuevos y cancelar envíos programados | Pro · Agency |
Los ámbitos de mensajes se incluyen en tokens de mensajes (prefijo tm_msg_), no en tokens de operaciones (prefijo tm_live_). Los tokens de mensajes se crean mediante la API con un token de operaciones que tenga el ámbito mailboxes:message-tokens:manage. Además de los límites ordinarios de la ruta de envío, cuentan con protecciones específicas de API: de forma predeterminada, la lectura permite 30 solicitudes por minuto y 5,000 lecturas correctas al día por token; el envío permite 60 solicitudes por minuto por token y 100 envíos de API diarios en todo el buzón. Un segundo contador de seguridad del token tiene un valor predeterminado de 500 envíos diarios, por lo que normalmente prevalece el límite inferior del buzón.
Todos los endpoints nuevos de la API de webmail (contactos, calendario, identidades, plantillas, remitentes bloqueados, borradores, envío programado, carpetas y adjuntos) se asignan a los tres ámbitos existentes de mensajes; no se añadieron ámbitos nuevos. Los tokens existentes siguen funcionando sin cambios.
messages:read no concede acceso de escritura. En OAuth alojado, aprobar la capacidad más amplia messages:send proporciona conjuntamente acceso de lectura, escritura y envío; un token tm_msg_ creado manualmente conserva exactamente los ámbitos seleccionados al crearlo.
Tickets de soporte
| Ámbito | Función | Planes |
|---|---|---|
tickets:read |
Enumerar y ver tickets y mensajes de soporte | Starter · Pro · Agency |
tickets:write |
Crear tickets, responderlos y cerrarlos | Pro · Agency |
Starter: acceso de solo lectura mediante API. Abre y responde tickets desde el panel.
Configuración de SMTP
| Ámbito | Función | Planes |
|---|---|---|
smtp:read |
Ver la ruta SMTP de un dominio, enumerar perfiles guardados y su uso exacto de dominios/Enviar como, leer el valor predeterminado de toda la cuenta y consultar trabajos de prueba | Starter · Pro · Agency |
smtp:write |
Configurar la ruta de un dominio, crear/actualizar/eliminar perfiles guardados, definir el valor predeterminado de la cuenta y ejecutar pruebas de conexión | Pro · Agency |
SMTP se configura por dominio (/api/v1/domains/{id}/smtp), con un único valor predeterminado para toda la cuenta (/api/v1/smtp/default) que decide la configuración inicial de los dominios nuevos. Consulta Descripción general de la API para ver la lista completa de endpoints. Los endpoints heredados de cuenta /api/v1/smtp siguen respondiendo por compatibilidad, pero ya no controlan el enrutamiento.
Migraciones
| Ámbito | Función | Planes |
|---|---|---|
migrations:read |
Enumerar y ver los detalles de las migraciones | Starter · Pro · Agency |
migrations:write |
Iniciar, cancelar, reintentar y eliminar migraciones | Pro · Agency |
Los ámbitos de migración se incluyen en tokens de operaciones (prefijo tm_live_). Starter puede ver migraciones mediante la API y ejecutarlas desde el panel. Pro y Agency también pueden iniciar, cancelar, reintentar y eliminar migraciones mediante la API y MCP.
Cloudflare
| Ámbito | Función | Planes |
|---|---|---|
cloudflare:read |
Validar tokens, enumerar zonas y previsualizar cambios de DNS | Starter · Pro · Agency |
cloudflare:write |
Conectar dominios y aplicar cambios de DNS mediante Cloudflare | Pro · Agency |
cloudflare:delete |
Eliminar tokens de Cloudflare (peligroso) | Pro · Agency |
Drive
| Ámbito | Función | Planes |
|---|---|---|
drive:account:read |
Explorar Account Drive, ver carpetas/archivos/papelera/metadatos de enlaces compartidos y solicitar URL de descarga | Planes de pago o complemento Drive activo |
drive:account:write |
Cargar, crear carpetas, cambiar nombre, mover, enviar a la papelera y restaurar elementos de Account Drive | Planes de pago o complemento Drive activo |
drive:account:share |
Crear, enumerar y revocar enlaces públicos compartidos para archivos de Account Drive | Planes de pago o complemento Drive activo |
drive:account:purge |
Purgar permanentemente archivos/carpetas de Account Drive en la papelera y vaciarla | Planes de pago o complemento Drive activo; alto riesgo |
drive:mailbox:read |
Explorar espacios permitidos de Drive para buzones | Planes de pago o complemento Drive activo |
drive:mailbox:write |
Cargar y modificar archivos/carpetas en espacios permitidos de Drive para buzones | Planes de pago o complemento Drive activo |
drive:mailbox:share |
Crear, enumerar y revocar enlaces públicos de archivos permitidos de Drive para buzones | Planes de pago o complemento Drive activo |
drive:mailbox:purge |
Purgar permanentemente elementos de Drive para buzones enviados a la papelera | Planes de pago o complemento Drive activo; alto riesgo |
drive:addon:read |
Leer estado, precios y vista previa de cancelación del complemento Drive Storage | Nano · Starter · Pro · Agency cuando exista contexto de complemento/Drive |
drive:devices:read |
Enumerar contraseñas de dispositivos de sincronización sin exponer su texto sin formato | Planes de pago o complemento Drive activo |
drive:devices:write |
Crear, rotar y revocar contraseñas de dispositivos de sincronización | Planes de pago o complemento Drive activo |
Los ámbitos de Drive son ámbitos de tokens de operaciones. Un token puede limitarse a buzones seleccionados y Drive ocultará al token los demás espacios de buzones. La compra, el cambio de tamaño y la cancelación del complemento Drive no son operaciones de escritura de API/MCP; los cambios de facturación permanecen en el panel.
Nano + complemento Drive: con un complemento Drive Storage activo, Nano obtiene el conjunto completo de ámbitos de Drive. No se desbloquea nada más, solo Drive y los ámbitos de Email Verifier que Nano ya tiene. Si cancelas el complemento, los ámbitos de lectura siguen activos durante el periodo de gracia de 7 días para que termines las descargas o la transición; la escritura, el uso compartido y la purga se interrumpen de inmediato.
Email Verifier
| Ámbito | Función | Planes |
|---|---|---|
verify:read |
Consultar créditos, enumerar trabajos y ver el estado y los resultados | Nano · Starter · Pro · Agency |
verify:write |
Enviar verificaciones, cancelar y eliminar trabajos (también concede acceso de lectura) | Nano · Starter · Pro · Agency |
Los ámbitos de Email Verifier están disponibles en todos los planes, incluido Nano. La única limitación es tu saldo de créditos. Consulta API de Email Verifier para ver la referencia completa de endpoints.
Niveles de acceso de los planes
| Plan | Acceso a API | Ámbitos disponibles |
|---|---|---|
| Nano | Email Verifier. Añade un complemento Drive Storage para disponer de toda la API de Drive + MCP. | verify:read, verify:write. Con el complemento Drive: todos los ámbitos drive:*. |
| Starter | Drive completo, Email Verifier completo y solo lectura en el resto. Ejecuta las escrituras del panel desde el panel. | account:read, billing:read, domains:read, domains:dns:read, mailboxes:read, mailboxes:forwarding:read, mailboxes:rules:read, mailboxes:auto-reply:read, migrations:read, tickets:read, smtp:read, cloudflare:read, verify:read, verify:write, todos los ámbitos drive:*. |
| Pro | Acceso completo | Todos los ámbitos de operaciones + ámbitos de Drive + ámbitos de mensajes + ámbitos de migración + tickets + SMTP + Cloudflare + cuenta + facturación + verificador |
| Agency | Acceso completo | Todos los ámbitos de operaciones + ámbitos de Drive + ámbitos de mensajes + ámbitos de migración + tickets + SMTP + Cloudflare + cuenta + facturación + verificador |
Los ámbitos de White Label son adicionales, no forman parte del plan base Pro o Agency. Solo aparecen para esas cuentas mientras su derecho de White Label está activo.
Qué ocurre al bajar de plan
Si bajas de Pro a Starter, los tokens existentes con ámbitos de escritura no se eliminan. En su lugar, la API bloquea en tiempo de ejecución las solicitudes que utilizan ámbitos no permitidos.
Por ejemplo, un token con mailboxes:create en un plan Starter recibirá 403 con el código token_scope_blocked_by_plan al intentar crear un buzón. Los ámbitos de lectura del mismo token seguirán funcionando.
Para solucionarlo, revoca el token antiguo y crea otro solo con los ámbitos que permite tu plan actual.
Ámbitos peligrosos
Los ámbitos mailboxes:delete, domains:delete, migrations:write y cloudflare:delete se marcan como peligrosos en el panel. Los tokens con estos ámbitos pueden iniciar la eliminación de buzones o dominios, quitar tokens de Cloudflare o realizar otras acciones irreversibles. Considera si tu caso de uso realmente los necesita.
En un servidor MCP alojado localmente, su administrador puede exigir TREKMAIL_ALLOW_DESTRUCTIVE=true antes de habilitar las herramientas de eliminación. MCP alojado utiliza los ámbitos aprobados durante OAuth.
El ámbito messages:send permite enviar correo real desde el buzón. En un servidor MCP alojado localmente, el envío también puede requerir TREKMAIL_ALLOW_SENDING=true y confirm_send=true en cada llamada. Consulta Protecciones e intenciones de eliminación para obtener más información.
El ámbito migrations:write permite iniciar migraciones de correo que se conectan a servidores IMAP externos mediante credenciales guardadas. En un servidor MCP alojado localmente, las escrituras de migración también pueden requerir TREKMAIL_ALLOW_MIGRATION=true y parámetros de confirmación por llamada (confirm_start, confirm_cancel, confirm_retry).
Restricciones de dominio
Los ámbitos controlan qué puede hacer un token. Las restricciones de dominio controlan dónde puede hacerlo.
Un token restringido a dominios concretos solo verá y modificará recursos dentro de esos dominios. Esto permite dar a un contratista o agente acceso a un solo dominio de cliente sin mostrar los demás.
Las comprobaciones de ámbitos se realizan antes que las restricciones de dominio. Si un token carece del ámbito requerido, la solicitud falla con 403 independientemente de las restricciones de dominio.
Soluciones rápidas
- 403 "insufficient_scope": tu token no tiene el ámbito requerido para este endpoint. Crea un token nuevo con los ámbitos correctos.
- 403 "token_scope_blocked_by_plan": tu plan ya no permite uno o varios ámbitos del token. Mejora el plan o revoca el token y crea otro con ámbitos permitidos.
- 403 "scope_blocked_by_entitlement": White Label está inactivo o se intentó una escritura durante el periodo de gracia de cancelación. Reactívalo antes de volver a autorizar la conexión.
- 403 "scope_blocked_by_membership": el rol actual del miembro o el permiso personalizado no permite la acción. Pide al propietario de la cuenta que cambie esa membresía.
- Algunos ámbitos están ocultos en el formulario de creación: tu plan no los admite. Solo se muestran los ámbitos permitidos.
Artículos relacionados
Ve a guías cercanas que continúan el flujo de trabajo.