Descripción general de la API REST de TrekMail

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.

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 AI Agents & API → Audit Log.
• 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.
• 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 AI Agents & API → Tokens → Create token y envíalo como Authorization: Bearer …. Consulta Crear y administrar tokens de API.
• ¿Es tu primera vez con la API? Haz clic en Start tour en la parte superior de la página AI Agents & 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 AI Agents & API, en Quick Reference. 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.

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 también validan la suma de las asignaciones del lote y rechazan todo el lote con 422 storage_pool_exceeded si se superaría la capacidad. 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.

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.

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 es una bandeja de entrada de equipo, como support@ o sales@, que los miembros abren mediante su propia cuenta de buzón normal, en Webmail y, cuando el acceso nativo está habilitado, como una carpeta IMAP delegada. No hay una contraseña compartida ni un inicio de sesión separado. El acceso es uniforme: todos los miembros pueden leer, y un único indicador can_send controla si cada miembro puede responder como la dirección (true) o tiene acceso de solo lectura (false). No hay roles de miembros.

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.

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 Send As, las rutas exactas de Inbox/Sent/Archive/Junk y las operaciones permitidas. can_send es el permiso Can reply 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.

Al eliminar un miembro, cambiar 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.
• set_account_default: true es el equivalente en la API al interruptor Make this the account default del panel (los nuevos dominios comienzan con esta ruta). apply_to_all: true es el botón Apply to all domains (un cambio único de todos los dominios a esta ruta).

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.

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 13 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, 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 Administrar 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?.
• 429 límite de velocidad: espera el tiempo indicado en el encabezado Retry-After antes de volver a intentarlo.

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.