Crear y gestionar tokens de API

Abre TrekMail en Claude, elige Connect, inicia sesión y autoriza el acceso. No necesitas crear un token de API. Revisa los permisos o desconecta la aplicación en Agentes de IA y API → Tokens → Aplicaciones conectadas.

Tu propia marca White Label: usa la dirección MCP de tu panel de marca y pon al conector el nombre de tu marca. Añádelo como custom connector; la página pública de TrekMail inicia sesión en TrekMail y no sustituye la conexión de tu marca.

Los tokens de API controlan lo que una aplicación o un agente puede hacer en tu cuenta. Cada token tiene un nombre, permisos, restricciones de dominio opcionales y una fecha de caducidad.

¿Vas a conectar un cliente MCP? Si admite autorización en el navegador, añade https://trekmail.net/mcp como servidor MCP remoto y aprueba el acceso en el navegador. Normalmente no necesitas crear ni pegar un token. Los tokens tm_live_ manuales son para scripts, tareas de CI, MCP autoalojado y clientes que no admiten ese flujo. Consulta Conectar agentes de IA (MCP).

Leer correo con una sola clave

En Pro y Agency, elige Leer correo al crear una clave API. El permiso explícito es mailboxes:messages:read; mailboxes:read solo muestra direcciones y datos de configuración. Elige todos los buzones para incluir los actuales y futuros, o limita el acceso a dominios y buzones concretos. Las claves existentes no reciben permisos nuevos automáticamente.

Usa la clave de cuenta con las rutas GET de abajo. Enviar, eliminar o cambiar datos sigue requiriendo credenciales y permisos de mensajes separados. El MCP alojado acepta OAuth, no tm_live_ ni tm_msg_. El error de tipo de token indica al agente la ruta o autorización correcta.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

Elegir y editar permisos de la aplicación

Abre los detalles de una clave API o aplicación conectada, elige Editar acceso, revisa los cambios y confirma. La clave API conserva su secreto. Reducir permisos, recursos o caducidad también limita los tokens de buzón existentes y cancela envíos que no hayan empezado. Las conexiones OAuth nuevas pueden limitarse al instante; ampliar acceso requiere una nueva aprobación. Editar una conexión antigua la desconecta y guarda la selección para reconectar. Los tokens de mensajes solo permiten quitar permisos o acortar su duración.

Antes de empezar

• Todos los planes pueden crear tokens de API, incluido Nano. Los planes Nano se limitan a los permisos de Email Verifier (verify:read, verify:write).
• Los planes Starter permiten permisos de infraestructura de solo lectura, además de todos los permisos de Drive y Email Verifier. Starter también puede gestionar el reenvío en el panel, pero el acceso de escritura para el reenvío mediante API (mailboxes:forwarding:write) requiere Pro o Agency. Pro y Agency habilitan todos los permisos.
• El propietario puede gestionar todas las credenciales de la cuenta. Un miembro delegado con permiso para tokens de API solo puede gestionar las credenciales que haya creado y solo puede conceder los permisos y dominios que ya formen parte de su membresía.
• Consejo: Haz clic en Iniciar recorrido en la página Agentes de IA y API para ver una breve guía sobre las opciones de conexión, los tokens, las aplicaciones conectadas y el registro de auditoría.

Crear un token de automatización de Drive

La API de Drive y las herramientas MCP usan tokens de operaciones (tm_live_...). Selecciona únicamente los permisos de Drive que necesite el flujo de trabajo:

• Informes de solo lectura: drive:account:read, drive:mailbox:read o drive:addon:read.
• Automatización de cargas: añade drive:account:write o drive:mailbox:write.
• Enlaces públicos de entrega: añade drive:account:share o drive:mailbox:share.
• Limpieza permanente: usa drive:account:purge o drive:mailbox:purge únicamente en un token separado y estrictamente controlado.

La compra, el cambio de tamaño y la cancelación del complemento Drive no están disponibles mediante tokens de API. Los agentes pueden consultar el estado y el precio del complemento con drive:addon:read, pero los cambios de suscripción permanecen en el panel.

Crear un token de automatización de White Label

White Label utiliza cinco permisos de token de operaciones: branding:read, branding:write, members:read, members:write y activity:read. Solo aparecen mientras la cuenta tiene acceso a White Label. members:write está marcado como peligroso porque puede retirar el acceso y revocar las claves de otra persona.

Para una integración de estado y auditoría de solo lectura, selecciona branding:read, members:read y activity:read. Añade branding:write solo para configurar la marca y DNS. Añade members:write únicamente cuando la automatización deba invitar o modificar personas.

Durante el periodo de gracia de cancelación, el propietario conserva los tres permisos de lectura para la recuperación, mientras que las operaciones de escritura y las credenciales delegadas de White Label dejan de funcionar. La reactivación no recupera una credencial revocada; crea o autoriza una nueva.

Crear un token

1. Ve a Agentes de IA y API → Tokens.
2. Haz clic en Crear token.
3. Completa el formulario:
   • Nombre: Una etiqueta para identificar el token (por ejemplo, "Agente Claude", "Canalización CI/CD").
   • Caducidad: Elige 7 días, 30 días, 90 días, una fecha personalizada o nunca.
   • Permisos: Selecciona las operaciones que puede realizar el token. Todos los permisos disponibles están marcados de forma predeterminada.
   • Restricción de dominio: Elige "Todos los dominios (actuales y futuros)", "Solo los dominios seleccionados" o "Todos los dominios (actuales y futuros) excepto…" para dejar fuera algunos dominios.
4. Haz clic en Crear token.

Después de crearlo, el token en texto sin formato se muestra una sola vez. Cópialo inmediatamente o usa el botón Descargar para guardarlo como archivo .txt.

El token no se puede volver a consultar. Guárdalo de forma segura antes de cerrar la confirmación.

Crear un token de mensajes

Los tokens de mensajes permiten que los agentes lean y envíen correo desde un buzón específico. Son independientes de los tokens de operaciones y se crean mediante programación a través de la API usando tu token de operaciones.

Para crear un token de mensajes, el agente llama a:

curl -s -X POST \
  -H "Authorization: Bearer tm_live_your_ops_token" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-message-token-my-agent" \
  -d '{"name":"my-agent","scopes":["messages:read","messages:send"]}' \
  https://trekmail.net/api/v1/mailboxes/{MAILBOX_ID}/message-tokens

Elige los permisos mínimos que necesite el flujo de trabajo:

El token en texto sin formato (tm_msg_...) se devuelve una sola vez. Añádelo a tu configuración MCP como TREKMAIL_MESSAGE_TOKEN.

Los tokens de mensajes están disponibles en los planes Pro y Agency. El token de operaciones debe tener el permiso mailboxes:message-tokens:manage.

Para una cuenta de Gmail conectada u otra bandeja externa, usa external_account_id. Para que los destinatarios vean en su lugar una dirección empresarial autorizada, usa también un identity_id devuelto por el endpoint de identidades. Consulta Direcciones Enviar como mediante API y MCP.

Formato del token

TrekMail usa dos prefijos para distinguir los tipos de token:

Los primeros 8 caracteres después del prefijo se guardan como prefijo visible en el panel para facilitar la identificación.

Permisos

Los permisos controlan lo que puede hacer el token. Las opciones disponibles dependen de tu plan:

• Nano: Solo Email Verifier (verify:read, verify:write). Añadir Drive Storage también proporciona a la cuenta las funciones de la API de Drive y MCP a las que tiene derecho.
• Starter: Acceso completo a Drive y Email Verifier, y acceso de solo lectura al resto (dominios, buzones, reenvío, filtros de correo, respuesta automática, migraciones, tickets, SMTP y Cloudflare). Usa el panel para las acciones de escritura que Starter no ofrece mediante la API, como crear migraciones, responder a tickets o cambiar la respuesta automática.
• Pro y Agency: Acceso completo. Lectura, escritura, creación y eliminación en todas las familias, además de tokens de mensajes para leer y enviar correo mediante la API.

Los permisos de White Label son un derecho del complemento, no un atajo en la tabla de planes. Solo se ofrecen mientras White Label está activo; el propietario conserva acceso de recuperación de solo lectura durante el periodo de gracia de cancelación.

Consulta Permisos de API y planes para ver la referencia de cada permiso.

Restricciones de dominio

De forma predeterminada, los tokens pueden acceder a todos los dominios de tu cuenta, incluidos los que añadas más adelante. Hay dos opciones para limitarlo:

• Solo los dominios seleccionados: el token accede a los dominios que marques y a nada más. Un dominio que añadas después queda fuera hasta que edites el token y lo marques.
• Todos los dominios (actuales y futuros) excepto…: el token accede a todos los dominios salvo los que marques, incluidos los que añadas más adelante. Sirve para mantener a tus agentes lejos del correo de un cliente sin editar el token cada vez que añades un dominio.

Un token restringido recibe respuestas 404 al intentar acceder a recursos de otros dominios; la API se comporta como si esos dominios no existieran. En ambos casos, el token tampoco puede cambiar ajustes de toda la cuenta que afecten a dominios fuera de su alcance, como el valor predeterminado para buzones nuevos.

Para un miembro del equipo limitado a algunos dominios, "excepto…" significa sus propios dominios menos los que marque; los dominios que se añadan después a la cuenta no se incluyen. Si eliminas un dominio excluido y lo vuelves a añadir, cuenta como un dominio nuevo: exclúyelo otra vez.

Regenerar un token

Regenera un token cuando necesites de nuevo su secreto o el secreto pueda haberse filtrado. El token conserva su nombre, permisos, dominios, buzones, caducidad e historial de auditoría. Solo cambia el secreto.

1. Ve a Agentes de IA y API → Tokens y abre los Detalles del token.
2. Haz clic en Regenerar.
3. Elige cuándo deja de funcionar el secreto anterior: Ahora, En 1 hora, En 24 horas, En 3 días o En 7 días. El secreto anterior nunca funciona más allá de la caducidad del propio token.
4. Haz clic en Regenerar y copia el nuevo secreto. Como un token nuevo, solo se muestra una vez.

Mientras el secreto anterior siga funcionando, los detalles del token muestran hasta cuándo y ofrecen Desactivar ahora. Sustituye el secreto en todas las aplicaciones antes de esa fecha: las solicitudes que sigan usando el secreto anterior reciben después 401 Unauthorized.

Los tokens de mensajes (tm_msg_...) creados con el secreto anterior dejan de funcionar al mismo tiempo. Una aplicación que crea sus propios tokens de mensajes puede crear otros nuevos con el nuevo secreto. Si el secreto puede haberse filtrado, elige Ahora.

Revocar un token

1. Ve a Agentes de IA y API → Tokens.
2. Busca el token en la lista.
3. Haz clic en Revocar.
4. Confirma la revocación.

Los tokens revocados dejan de funcionar inmediatamente. Cualquier solicitud de API que use uno recibe 401 Unauthorized.

La revocación es permanente y no se puede deshacer. Crea un token nuevo si necesitas restaurar el acceso.

Estado del token

Los tokens tienen tres estados:

Usa el filtro de estado de la página Tokens para ver los tokens por estado.

Registro de auditoría

Cada creación, regeneración y revocación de un token aparece en la pestaña Registro de auditoría. Los eventos incluyen el nombre del token, la acción y la hora.

Soluciones rápidas

• "Permisos no disponibles en tu plan": Tu plan no incluye esos permisos. Nano se limita a verify:read y verify:write (añade el complemento Drive Storage para obtener también los permisos drive:*). Starter añade acceso de lectura a todas las familias de infraestructura, además de Drive y Email Verifier completos. Pro y Agency habilitan la escritura en todas partes.
• Has perdido el token en texto sin formato: El token no se puede recuperar, pero puedes regenerarlo: abre sus Detalles, haz clic en Regenerar y copia el nuevo secreto. El token conserva su configuración.
• El token funciona, pero devuelve 404 para algunos dominios: Probablemente tenga una restricción de dominio. Abre Detalles del token, elige Editar acceso y añade los dominios que faltan, o cambia a "Todos los dominios (actuales y futuros)" o a "Todos los dominios (actuales y futuros) excepto…".
• El permiso de White Label devuelve scope_blocked_by_entitlement: Reactiva White Label y crea o autoriza una credencial con el permiso necesario.
• Un token delegado dejó de funcionar tras cambiar un rol: Reducir, suspender o eliminar el acceso de un miembro revoca inmediatamente las credenciales afectadas. Crea un token nuevo cuando el propietario restaure el acceso correcto.