Descripción general de la API REST de TrekMail

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.

La API de TrekMail te permite administrar dominios, buzones, reenvío, DNS, migraciones de correo electrónico y operaciones de webmail desde un cliente HTTP o un agente de IA. Esto incluye leer y enviar mensajes, borradores, programación, carpetas, contactos, calendarios, identidades, plantillas y remitentes bloqueados. Las solicitudes autenticadas usan un token bearer, las respuestas son JSON y la actividad de la API queda registrada para auditoría.

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}

Qué obtienes

• API REST v1 con formato JSON para solicitudes y respuestas.
• Autenticación con token bearer: sin cookies ni sesiones para las llamadas autenticadas a la API.
• Claves de idempotencia en las operaciones de escritura que las requieren, para evitar trabajo duplicado durante los reintentos.
• Límite de velocidad por token con encabezados Retry-After.
• Registro de auditoría visible en el panel, en Agentes de IA y API, Registro de auditoría.
• Servidor MCP con un catálogo filtrado según las credenciales, el transporte y la configuración de seguridad de la conexión actual. Por eso, una conexión limitada a un proyecto solo ve las herramientas que puede usar.
• Alias de dominio: conecta direcciones de solo recepción de un dominio secundario con las mismas partes locales de un dominio principal, con estados de entrega guardados y activos, además de eliminación segura. Consulta Alias de dominio mediante API y MCP.
• Arquitectura de dos tokens: tokens de operaciones separados para infraestructura y tokens de mensajes para operaciones completas de correo, como lectura, envío, borradores, programación, contactos, calendarios, identidades, plantillas y carpetas.
• Información sobre entregabilidad saliente y rebotes: obtén desde el panel el resumen de enviados, entregados, rebotes permanentes y rebotes temporales, además de los códigos y respuestas SMTP por destinatario. Consulta Entregabilidad y rebotes.
• Contraseñas de aplicación: administra contraseñas independientes para IMAP, SMTP, calendarios y contactos, y elige qué contraseñas aceptan las apps de correo. No sustituyen los tokens Bearer de la API ni los tokens de la API de mensajes. Consulta Contraseñas de aplicación por API y MCP.
• Uso de almacenamiento del buzón: list_mailboxes y get_mailbox devuelven used_mb, quota_mb, allocation_mb e is_pooled, para que un agente detecte buzones próximos a su límite sin acceder al panel.
• Administración de White Label: revisa la configuración, gestiona el branding por dominio, invita clientes, controla roles y dominios, suspende o restaura el acceso y consulta la actividad mediante API o MCP. Consulta la guía de branding y la guía de administración de equipos.

API de Drive y automatización de archivos

Drive forma parte de la API pública. Incluye los espacios de Drive de la cuenta y de los buzones, el uso, la exploración de carpetas, las cargas, la administración de archivos y carpetas, la Papelera, las acciones masivas, los enlaces públicos para compartir, la administración de contraseñas de dispositivos de sincronización y el estado de solo lectura del complemento Drive Storage.

Drive usa once ámbitos de tokens de operaciones: drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, drive:addon:read, drive:devices:read y drive:devices:write. Las acciones de facturación para el complemento Drive, como comprar, cambiar el tamaño y cancelar, siguen disponibles solo en el panel y no se exponen como operaciones de escritura de API o MCP.

Empieza con la descripción general de la API de Drive o la guía de inicio rápido de la API de Drive.

Arquitectura de dos tokens

La API usa dos tipos de token independientes. Puedes usar uno o ambos según tus necesidades:

Los tokens de operaciones y los tokens de mensajes tienen ámbitos y límites de velocidad separados. Un solo agente puede usar ambos tokens al mismo tiempo configurándolos en el entorno del servidor MCP.

Los tokens de mensajes están disponibles en los planes Pro y Agency.

Antes de empezar

• Todos los planes tienen acceso a la API:
  • Nano: Email Verifier. Añade un complemento Drive Storage para obtener acceso completo a la API y MCP de Drive.
  • Starter: acceso completo a Drive y Email Verifier, y acceso de solo lectura al resto de las áreas de infraestructura. Usa el panel para esas acciones de escritura.
  • Pro / Agency: acceso completo a la API base, incluidos los tokens de mensajes. Los ámbitos de White Label se añaden mientras su prueba o complemento de pago esté activo.
• ¿Vas a conectar un agente de IA? Añade https://trekmail.net/mcp como servidor MCP remoto en cualquier cliente compatible. Si admite autorización mediante navegador, no se necesita un token manual. Consulta Conectar agentes de IA (MCP) para ver las opciones remotas, de CLI/escritorio, puente y alojamiento propio.
• ¿Vas a crear tu propia integración? Crea un token tm_live_ en Agentes de IA y API, Tokens, Crear token y envíalo como Authorization: Bearer …. Consulta Crear y administrar tokens de API.
• ¿Es tu primera vez con la API? Haz clic en Iniciar recorrido en la parte superior de la página Agentes de IA y API para ver una guía breve sobre métodos de conexión, administración de tokens, aplicaciones conectadas y el registro de auditoría.

Cómo funciona la autenticación

Cada solicitud debe incluir tu token en el encabezado Authorization:

Authorization: Bearer tm_live_abc123...

Los tokens de operaciones comienzan por tm_live_ y los tokens de mensajes por tm_msg_. Ambos se muestran una sola vez al crearlos y no pueden volver a mostrarse.

Si el token falta, fue revocado o caducó, la API devuelve 401 con el código de error unauthenticated.

URL base y control de versiones

Todos los endpoints se encuentran bajo:

https://trekmail.net/api/v1

La URL base aparece en tu panel Agentes de IA y API, en Referencia rápida. La versión se encuentra en la ruta de la URL. Si alguna vez se introduce v2, v1 seguirá funcionando.

Formato de respuesta

Las respuestas correctas devuelven JSON con una clave data para recursos individuales o una lista paginada:

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Las respuestas de error siguen una estructura coherente:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

Identificadores de solicitud

Cada respuesta incluye un encabezado X-Request-Id. También puedes enviar el tuyo mediante X-Request-Id en la solicitud. Se devolverá sin cambios y quedará registrado en el historial de auditoría.

Límites de velocidad

Cada token tiene un límite de velocidad por minuto. Cuando alcanzas el límite, la API devuelve 429 con un encabezado Retry-After que indica cuándo puedes volver a intentarlo.

Las operaciones destructivas (intenciones de eliminación) tienen un límite diario adicional por token y un tiempo de espera entre eliminaciones consecutivas.

Las operaciones de escritura de migraciones (iniciar, cancelar y reintentar) tienen un límite específico de 10 solicitudes por minuto y por token, además de un máximo de concurrencia para todo el servidor que devuelve 503 cuando se ejecutan demasiadas migraciones globalmente.

Los tokens de mensajes usan límites separados. Los valores predeterminados son 30 solicitudes de lectura por minuto y por token, 60 solicitudes de envío por minuto y por token, 5,000 lecturas correctas por día y por token, y 100 envíos por API al día en un buzón. Un segundo contador de seguridad para envíos tiene un valor predeterminado de 500 por token y por día; normalmente se aplica primero el límite inferior del buzón. Estas protecciones de la API no sustituyen los límites de SMTP administrado de tu plan ni los límites propios de un proveedor externo.

Idempotencia

Los endpoints que cambian el estado y están marcados como idempotentes requieren un encabezado Idempotency-Key. Esto incluye creaciones, actualizaciones, envíos y eliminaciones en las que un reintento automático podría duplicar el trabajo. Las acciones POST similares a lecturas, como detectar un proveedor o probar una conexión, no lo requieren; consulta la tabla de endpoints o la especificación OpenAPI. Si envías la misma clave con el mismo cuerpo, la API reproduce la respuesta original sin crear duplicados. Los envíos de mensajes son la excepción cuando su entrega falló (por un límite de envío, por ejemplo): la API ya no reproduce el 202 anterior, así que puedes volver a enviar el mismo mensaje más tarde con el mismo contenido. Si envías tu propio X-Request-Id, usa uno nuevo para ese intento: la API también trata como repetido un envío del mismo buzón con el mismo X-Request-Id, así que con el anterior solo recibirás la entrega original fallida y no se enviará nada. Un reintento de un envío que sigue pendiente o que ya se entregó recibe la respuesta original.

Idempotency-Key: create-mailbox-alice-2024

Si envías la misma clave con un cuerpo diferente, la API devuelve 409 Conflict.

Asignación de almacenamiento de buzones

Cada endpoint que crea un buzón o una invitación, POST /api/v1/mailboxes, /api/v1/mailboxes:bulk, /api/v1/mailboxes/invites, /api/v1/mailboxes/invites:bulk, acepta un entero opcional storage_allocation_mb.

Las asignaciones se validan comparándolas con el grupo activo menos los buzones dedicados existentes y las invitaciones dedicadas pendientes. Los endpoints masivos comprueban cada elemento con asignación propia frente a lo que queda en el momento de crearlo: se crean los que caben, y los que ya no caben fallan uno a uno con el motivo storage_pool_exceeded (207 éxito parcial, o 422 si fallan todos). En un dominio con un límite de almacenamiento de cliente de White Label, un tamaño fijo también debe caber en lo que le queda a ese límite: una creación o invitación individual devuelve 422 client_storage_limit_exceeded con limit_mb, allocated_mb, available_mb y requested_mb en details (una clave restringida a algunos dominios solo recibe available_mb y requested_mb cuando el límite también cubre un dominio fuera de su alcance), y un elemento masivo falla con el motivo client_storage_limit_exceeded. El grupo se actualiza al eliminar un buzón dedicado, al canjear una invitación (la asignación pasa al nuevo buzón) y al caducar una invitación pendiente.

En las invitaciones, la asignación se registra en el código de acceso y se copia al nuevo buzón al canjearlo. Si en ese momento el grupo ya no admite la asignación solicitada (por ejemplo, otro administrador aumentó mientras tanto su asignación dedicada), el canje reduce de forma segura el nuevo buzón a almacenamiento compartido en lugar de fallar, y el destinatario ve un aviso en la página de confirmación.

Para cambiar un buzón existente, envía PATCH /api/v1/mailboxes/{id}/storage con storage_allocation_mb en un tamaño fijo en MB, o en null para almacenamiento compartido. Requiere mailboxes:write y un Idempotency-Key, funciona con buzones activos y pausados, y hace las mismas comprobaciones que Editar almacenamiento en el panel: storage_pool_exceeded cuando el espacio libre de la cuenta no alcanza y, en un dominio con límite de almacenamiento de cliente, client_storage_limit_exceeded, o client_storage_below_usage cuando el nuevo tamaño es menor que lo que el buzón ya almacena. El almacenamiento compartido nunca se rechaza por su tamaño. Un buzón en Eliminados recientemente o en proceso de eliminación devuelve 422 mailbox_unavailable. La herramienta MCP es set_mailbox_storage.

Los límites de almacenamiento de cliente de White Label están bajo /api/v1/white-label/client-limits; consulta Gestionar equipos White Label con API y MCP. Una clave restringida a algunos dominios solo ve su parte de la cuenta en GET /api/v1/account: usage cuenta solo sus dominios y buzones, limits.max_storage_mb es el límite del cliente cuando todos sus dominios comparten uno que no cubre ningún otro dominio, y client_limit contiene ese límite (id, storage_limit_mb, allocated_mb, used_bytes) o null. Los demás reciben la respuesta sin cambios.

Los buzones normales nuevos, incluidos los creados en bloque, mediante invitaciones o agentes de IA, siguen Configuración de la cuenta > Buzones nuevos > Las apps de correo necesitan contraseñas de aplicación, activado por defecto. Cambiarlo no modifica los buzones existentes. POST /api/v1/mailboxes permite elegir un client_auth_mode de app_password_only o password_or_app_password; si se omite, se aplica el ajuste de la cuenta. Los recursos de listado y detalle de buzones incluyen client_auth_mode y app_passwords_count (contraseñas de aplicación activas). Los buzones compartidos no tienen contraseñas de aplicación ni modo de inicio de sesión propios.

Las seis herramientas MCP para administrar contraseñas de aplicación son list_mailbox_app_passwords, create_mailbox_app_password, rotate_mailbox_app_password, revoke_mailbox_app_password, set_mailbox_client_auth_mode, update_account. update_account: Define new_mailbox_client_auth_mode para los buzones futuros; los existentes conservan su modo. Requiere mailboxes:write, un token o conector del propietario sin restricciones de recursos y TREKMAIL_ALLOW_DESTRUCTIVE=true en stdio autoalojado.

Acceso de buzones a Drive

Cada buzón tiene un nivel drive_access que determina cuánto contenido de Drive puede usar en webmail la persona asociada. Se devuelve en el recurso del buzón y puede establecerse con PATCH /api/v1/mailboxes/{id} o, para varios buzones a la vez, con POST /api/v1/mailboxes:drive-access.

El almacenamiento se comparte en toda la cuenta, por lo que este control determina cuánto puede ocupar una sola persona con archivos.

Suspensión del inicio de sesión del buzón

Es posible suspender el inicio de sesión de un buzón mientras sigue recibiendo correo: se rechazan webmail, IMAP, SMTP y las contraseñas de dispositivos, y se cierran las sesiones abiertas, pero la entrega no cambia. Nada rebota y todo espera cuando se restaura el inicio de sesión. Configúralo con POST /api/v1/mailboxes/{id}:suspend-login (y :resume-login) o, para varios buzones, con POST /api/v1/mailboxes:login-access.

El recurso del buzón lo informa como login_suspended, login_suspended_at y login_suspended_reason. Consulta login_suspended para saber si la persona puede iniciar sesión y status para saber si el buzón funciona. Un buzón suspendido conserva active porque sigue aceptando correo. :pause es diferente: cambia status a disabled y también detiene la entrega.

La suspensión revoca permanentemente todas las contraseñas de aplicación. Restaurar el inicio de sesión no las recupera. También se revocan cuando un administrador define una nueva contraseña del buzón en el panel, por API o mediante un agente de IA, al recuperar la contraseña, convertir el buzón en compartido o moverlo a Eliminados recientemente. Restaurar un buzón eliminado no las recupera.

Consulta Suspender el inicio de sesión de un buzón mediante API.

El endpoint masivo acepta exactamente un selector, mailbox_ids, domain_id o all, y devuelve lo que hizo:

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

domain_id es el selector adecuado cuando un dominio corresponde a un cliente. Los buzones que ya tienen el nivel solicitado cuentan como matched, pero no como updated, por lo que es seguro repetir la llamada.

Los buzones compartidos se rechazan en el endpoint individual con 422 drive_access_not_applicable y el endpoint masivo los omite y contabiliza: no tienen un usuario propio de webmail, por lo que los miembros los abren con su propio nivel y un valor guardado en la fila compartida no cambiaría nada.

La restricción se aplica tanto a la API como a la interfaz. El espacio de Drive de un buzón restringido no aparece en GET /api/v1/drive/spaces, sus archivos responden con 404 al consultarlos por id y no se puede crear un dispositivo de sincronización para él.

Direcciones de reenvío

GET /api/v1/domains/{id}/forwarding-addresses devuelve más que la lista, porque hay dos aspectos de una dirección de reenvío que no se ven en la propia dirección:

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max se aplica por dominio y depende del plan: 100 en Pro, 300 en Agency y 25 guardadas pero inactivas en Nano o Starter.
• delivery.active indica si estas reglas están moviendo correo ahora mismo. Es false en un plan inferior a requires_plan y también es false mientras paused_until tenga un valor (la cuenta superó su tasa de envío por hora; consulta Límites de envío por plan). Una regla puede tener is_active: true y aun así no entregar mensajes, por lo que debes consultar delivery, no solo is_active, antes de informar que el reenvío funciona.

Se permite crear reglas en un plan que no puede entregar y se devuelve 201: la regla queda guardada y empieza a funcionar al mejorar el plan. Esto coincide con el panel, que muestra esas reglas como guardadas e inactivas.

Los rechazos se devuelven como 422 con error.code establecido en validation_error o limit_exceeded: una dirección ya usada en el dominio, un destinatario del mismo dominio (que produciría un bucle), un dominio destinatario sin MX operativo o el presupuesto por dominio agotado.

Las operaciones POST y DELETE en estos endpoints requieren una Idempotency-Key; PATCH no la requiere.

Historial de entrega

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log devuelve lo ocurrido realmente con el correo reciente, empezando por lo más nuevo:

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcome puede ser delivered, deferred (fallo temporal, se siguen realizando reintentos), failed (el servidor del destinatario lo rechazó) o blocked. Este último significa que nuestro filtro de spam detuvo el mensaje antes del reenvío, por lo que nunca llegó al destinatario. Tratar blocked como un rebote haría que alguien investigara el servidor receptor por un problema ocurrido en el nuestro.

limit (1-200, valor predeterminado 100) es el único parámetro. La ventana es la retención del plan: 30 días en Agency y 7 en los demás. No hay eventos más antiguos que consultar porque los eventos reenviados se eliminan.

Buzones compartidos (de equipo)

Un buzón compartido tiene su propia bandeja de equipo. can_read es Leer y can_send es Enviar como. Abrir carpetas compartidas requiere Leer. Enviar desde el buzón compartido con la Message API requiere ambos. No hay contraseña común, inicio de sesión separado ni roles de miembro.

GET /api/v1/mailboxes y GET /api/v1/mailboxes/{id} ahora devuelven mailbox_type ("user" o "shared") y el booleano is_shared; los buzones compartidos también incluyen shared_member_count. Usa estos campos para distinguir una bandeja de equipo de una normal antes de llamar a los endpoints de miembros.

Al volver a un buzón normal se quitan todos los miembros. Establece una nueva contraseña de webmail y crea contraseñas de aplicación para las apps de correo en la pestaña Seguridad.

Los cambios pueden devolver 422 no_access_left si ambos permisos quedarían desactivados, 422 send_only_disabled si el cambio solicitado del permiso Leer no está disponible, o 422 last_reader si la última persona activa que lee perdería acceso. Usa Quitar para quitar todo el acceso y da el permiso Leer a otro miembro activo antes de eliminar al último lector. Cada uno de estos errores devuelve también shared_mailbox_id, member_id si el miembro ya existe y un hint que indica la solicitud que lo resuelve.

Los endpoints de miembros reutilizan tus ámbitos mailboxes:read / mailboxes:write existentes. No hay un ámbito independiente para buzones compartidos.

Para descubrir el acceso nativo desde aplicaciones de correo, llama a GET /api/v1/mailboxes/{member_mailbox_id}/client-setup para un buzón normal de miembro. Su objeto shared_mailboxes informa de la disponibilidad nativa duradera, la disponibilidad y el motivo efectivos de Enviar como, las rutas exactas de Inbox/Sent/Archive/Junk y las operaciones permitidas. can_send es el permiso Enviar como asignado, no una prueba de que SMTP esté listo. El endpoint nunca devuelve una contraseña. Si se llama con el id del buzón compartido, devuelve 422 direct_login_unavailable porque la dirección compartida no puede autenticarse directamente.

shared_mailboxes.items[] solo incluye miembros con el permiso Leer cuando el acceso nativo a carpetas está habilitado. delegated_send_addresses es una lista aparte de direcciones del equipo disponibles en el campo De con id, email y display_name; puede estar vacía. No da acceso a carpetas ni comprueba que se pueda enviar. Estas direcciones no son identidades de la Message API. Usa los servidores devueltos, también en White Label, en vez de copiar el servidor de la plataforma.

Al eliminar un miembro, cambiar can_read / can_send o convertir un buzón compartido en normal, se sincronizan los permisos del servidor de correo cuando el acceso nativo está habilitado. Una respuesta 503 native_access_sync_failed permite reintentar y garantiza que la membresía, el permiso o el tipo de buzón no se modificaron, en lugar de aplicar parcialmente la operación.

Endpoints disponibles

Drive tiene su propia referencia y no se repite aquí; consulta la descripción general de la API de Drive. Los endpoints SMTP a nivel de cuenta que se conservan por compatibilidad con versiones anteriores se describen en Enrutamiento SMTP por dominio, en lugar de mostrarse como actuales.

Los endpoints de Cloudflare siguen el mismo flujo que el panel: validar un token, enumerar zonas, conectar dominios, obtener una vista previa de los cambios de DNS y aplicarlos. Tanto /cloudflare/preview como /cloudflare/apply aceptan dos controles opcionales por dominio:

• included_records, una lista de permitidos que indica qué registros se pueden modificar, organizada por ID de dominio: { "123": ["mx_primary", "spf_record"] }. Los registros omitidos se saltan, por lo que puedes aplicar solo MX y SPF y volver más tarde para DKIM. Omite el campo para aplicar todos los registros.
• confirmed_conflicts, cuando la vista previa marca un registro que ya existe con otro valor, incluye aquí su ID de registro (con la misma forma { domain_id: [record_ids] }) para autorizar su sustitución.

Los ID de registro (mx_primary, spf_record, dkim_primary, dmarc_main, …) proceden directamente de la respuesta de la vista previa, por lo que un agente típico llama primero a la vista previa y pasa a la aplicación los ID que desea:

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

Enrutamiento SMTP por dominio y valor predeterminado de la cuenta

SMTP se configura por dominio. Cada dominio elige una de tres rutas: envío administrado por la plataforma, un perfil SMTP guardado (tu propio proveedor, reutilizable entre dominios) o "sin configurar". Un único valor predeterminado para toda la cuenta decide con qué ruta comienzan los nuevos dominios.

Endpoints por dominio (smtp:read / smtp:write):

Algunas notas sobre el cuerpo de la ruta:

• smtp_mode=platform selecciona el envío administrado; smtp_mode=profile requiere smtp_connection_id; not_configured borra la ruta.
• smtp_mode=inherit hace que el dominio siga en tiempo real el valor predeterminado de la cuenta: cuando este cambia, el dominio cambia con él. La interfaz web siempre escribe rutas concretas, pero el backend sigue admitiendo inherit; por eso GET devuelve effective_smtp_mode, que muestra a qué se resuelve actualmente inherit.
• Esta ruta cambia solo su propio dominio. Para convertir una ruta en el valor predeterminado de la cuenta (Convertir en predeterminado de la cuenta en el panel), usa PUT /api/v1/smtp/default más abajo; añade apply_to_all: true para cambiar también todos los dominios a ella (Aplicar a todos los dominios).

Endpoints predeterminados para toda la cuenta (smtp:read / smtp:write):

Al eliminar un perfil que era el predeterminado de la cuenta, este se restablece al valor base del plan.

Una clave limitada a algunos dominios o buzones recibe 403 token_resource_constrained de PUT /api/v1/smtp/default, de los antiguos PUT y DELETE /api/v1/smtp y al eliminar un perfil guardado, porque cada una de estas acciones cambia la ruta de dominios a los que quizá no tenga acceso. Una clave limitada a algunos dominios recibe la misma respuesta al editar un perfil que también usa un dominio fuera de su lista.

Endpoints heredados. Los endpoints GET/PUT /api/v1/smtp a nivel de cuenta (y DELETE /api/v1/smtp/{id}, POST /api/v1/smtp:test, GET /api/v1/smtp:test-status/{jobId}) se mantienen por compatibilidad con versiones anteriores, pero ya no controlan el enrutamiento por dominio: usa los endpoints por dominio y /smtp/default anteriores. Las herramientas MCP heredadas get_smtp_config / update_smtp_config están obsoletas por el mismo motivo.

Branding White Label, clientes y acceso del equipo

El branding se configura por dominio con branding:read / branding:write. Un dominio usa su propia marca (mode=custom), hereda el valor predeterminado de la cuenta (mode=inherit) o está desactivado. Se requiere una prueba activa o un complemento de pago de White Label. Después de la cancelación, el propietario conserva acceso de recuperación de solo lectura durante el período de gracia mostrado. Lee los dns_records del dominio y publica exactamente esas entradas devueltas. No derives nombres de host ni destinos CNAME de un ejemplo.

PATCH es una fusión parcial, por lo que los campos omitidos se conservan. Si el branding está desactivado, envía mode para volver a activarlo. Un sender_email personalizado debe pertenecer a un dominio con una clave DKIM verificada. mail_zone_enabled ofrece aplicaciones de correo y sincronización DAV bajo el dominio propio de la marca. Pertenece a la marca y no a un solo dominio, por lo que necesita mode=custom o scope=account_default; un dominio inherit devuelve 422 inherited_brand. Lee mail_zone.dns_status, mail_zone.client_hosts_status, mail_zone.records, mail_zone.dav_url y mail_zone.dav_ready para seguir el aprovisionamiento y usar solo una dirección DAV lista. Para ver el flujo completo del agente, consulta la Guía de API y MCP para branding White Label.

La superficie White Label a nivel de cuenta añade 18 rutas bajo /api/v1/white-label: estado y progreso de configuración, un catálogo de acceso activo, listado de miembros y acciones de ciclo de vida, límites de almacenamiento de los clientes, actividad de la cuenta e historial de acciones e inicios de sesión por miembro. Usa members:read, members:write y activity:read. El acceso siempre es la intersección entre la titularidad de la cuenta, la membresía actual de la persona, la concesión de credenciales y cualquier restricción de dominio. Consulta Gestionar equipos White Label con API y MCP para ver la tabla de rutas y las transiciones de estado.

La especificación OpenAPI está disponible en /api/openapi.json para importarla en Postman, Insomnia o generadores de código.

Soluciones rápidas

• 401 "unauthenticated": comprueba que el encabezado Authorization: Bearer <token> esté presente y que el token no haya sido revocado ni haya caducado.
• 403 "plan_api_disabled": el ámbito solicitado no está incluido en tu plan. Nano incluye Email Verifier (y Drive si compraste el complemento Drive Storage). Mejora a Starter o superior para usar el resto de la API.
• 403 "token_scope_blocked_by_plan": tu token tiene ámbitos no disponibles en tu plan actual. Revoca el token y crea uno nuevo con ámbitos permitidos.
• 403 "scope_blocked_by_entitlement": una concesión de White Label guardada no está disponible porque el complemento está inactivo o la operación es una escritura durante el período de gracia. Reactiva White Label y vuelve a emitir o autorizar las credenciales.
• 403 "scope_blocked_by_membership": el rol actual del miembro es más limitado que la acción solicitada. Pide al propietario que lo cambie; volver a autorizar no puede ampliar la membresía por sí solo.
• 422 "missing_idempotency_key": añade un encabezado Idempotency-Key a la operación de escritura indicada en la referencia del endpoint.
• 403 "mailbox_sending_paused": se detuvo el envío desde ese buzón porque su correo saliente dejó de parecer propio de su titular, normalmente porque una contraseña cayó en manos equivocadas. La lectura, el listado y todos los demás endpoints siguen funcionando; solo se rechaza el envío y volver a intentarlo no soluciona el bloqueo. Es necesario cambiar la contraseña del buzón y luego el equipo de soporte volverá a activar el envío. Consulta ¿Por qué no puedo enviar correos electrónicos?.
• 403 "account_sending_on_hold": el envío desde toda la cuenta queda retenido mientras TrekMail la revisa. La recepción y todos los demás endpoints siguen funcionando; volver a intentarlo no soluciona la retención. Contacta con el equipo de soporte para que la revise.
• 403 "mailbox_send_disabled": el envío está desactivado solo para este buzón. La lectura y todos los demás endpoints siguen funcionando; volver a intentarlo no lo soluciona. Lo habitual es que el buzón quede fuera de tu plan: su dominio supera el número de dominios que incluye el plan, o el buzón supera los buzones por dominio del plan (los dominios y buzones más antiguos siguen enviando). Ocurre después de cambiar a un plan más pequeño. También puede ser un buzón creado antes de que su dominio terminara la configuración. Mejorar el plan reactiva el envío al instante; después de eliminar los dominios o buzones sobrantes, o en cuanto el dominio termina la configuración, vuelve en un día. Si nada de esto aplica, contacta con el equipo de soporte.
• 403 "account_email_unverified": el envío está bloqueado hasta que el propietario de la cuenta verifique su correo de inicio de sesión. Las cuentas registradas a partir del 19 de febrero de 2026 tienen 7 días para hacerlo, y los mismos 7 días vuelven a empezar al sustituir un correo de inicio de sesión verificado por uno nuevo. La lectura y todos los demás endpoints siguen funcionando; volver a intentarlo no lo soluciona. Abre el enlace del correo de verificación o haz clic en Reenviar correo de verificación en la franja del panel; el envío vuelve a funcionar en cuanto se verifica la dirección. Consulta ¿Por qué no puedo enviar correos electrónicos?.
• 429 límite de velocidad: espera el tiempo indicado en el encabezado Retry-After antes de volver a intentarlo. Al alcanzar el límite diario de la API por buzón, la respuesta también es rate_limited, pero con retryable en false, dimension en api_mailbox_daily y una hora en resets_at: volver a intentarlo antes no funcionará, así que espera hasta esa hora.
• 429 "sending_limit_exceeded": se agotó uno de tus límites de envío. dimension indica cuál y resets_at, cuándo se renueva. Reintentar antes de esa hora no puede funcionar, por eso retryable es false. GET /api/v1/messages/sending-limits indica en remaining_today a cuántos destinatarios más puede enviar hoy el buzón. Cuando el límite más bajo es el total diario de la cuenta, limit_today es null y remaining_today también lo es hasta que ese total se agota (entonces vale 0); un token de operaciones consulta el total con GET /api/v1/sending-limits. Si dimension es recipients_per_message, divide el mensaje en varios más pequeños. En las primeras 24 horas después del primer pago de la cuenta, entre las causas está new_payer, y GET /api/v1/sending-limits indica en full_limits_at el momento en que se aplican los límites completos del plan. Consulta Límites de envío por plan.

Envío de correo: cuerpo, encabezados y entregabilidad

POST /api/v1/messages/send recibe una solicitud con la forma {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.

• body.text y body.html son opcionales, pero se requiere al menos uno. Si proporcionas solo body.text, generamos automáticamente una alternativa HTML usando párrafos <p> (las líneas en blanco separan párrafos; los saltos de línea individuales se convierten en <br>), para que el mensaje se muestre como un correo normal en todos los clientes modernos. Si necesitas texto monoespaciado, envía el literal <pre>...</pre> en body.html.
• headers es un objeto opcional de encabezados salientes proporcionados por el usuario. La lista permitida es List-Unsubscribe, List-Unsubscribe-Post, Reply-To y cualquier encabezado de seguimiento personalizado X-*. Los demás nombres (From, Subject, Message-Id, Authentication-Results, etc.) son administrados por la plataforma y se rechazan con 422. También se rechazan los valores que contienen CR/LF para evitar la inyección de encabezados. Los valores tienen un máximo de 998 caracteres según RFC 2822.
• Para casos de envío masivo o automatización, consulta la sección Encabezados de entregabilidad para remitentes masivos para configurar List-Unsubscribe y el interruptor auto_list_unsubscribe de toda la cuenta.

Una respuesta 202 significa que el mensaje se aceptó, pero todavía no se envió. Los límites de envío se vuelven a comprobar cuando el mensaje sale de la cola, así que verifica el resultado con GET /api/v1/messages/deliveries/{request_id}, usando el request_id de la respuesta 202. Puede consultarlo cualquier token de mensajes del mismo buzón, no solo el que envió el mensaje; un request_id desconocido devuelve 404. Si un límite lo detuvo, status es failed y failure indica el límite (dimension) y cuándo se renueva (resets_at). Un mensaje cuyo envío falló puede enviarse de nuevo más tarde con el mismo contenido. Si envías tu propio X-Request-Id, usa uno nuevo, porque el anterior solo devuelve la entrega original. Un mensaje programado que alcanza un límite al llegar su hora queda retenido como limit_reached y se conserva durante 7 días: puedes listar estos mensajes con GET /api/v1/messages/scheduled?status=limit_reached, enviar uno más tarde asignándole un nuevo scheduled_for con PATCH /api/v1/messages/scheduled/{id} o eliminarlo con DELETE.