Alias de dominio mediante API y MCP

Un alias de dominio permite que un dominio siga las direcciones receptoras de otro. Si hello@company.example puede recibir correo, hello@brand.example puede entregarlo al mismo lugar sin crear ni mantener un segundo buzón o alias.

Esta función es solo para recepción. No crea una dirección De, no cambia SMTP ni permite enviar como el dominio conectado.

Cuándo resulta útil

Los alias de dominio funcionan bien cuando una empresa tiene varios dominios de marca, un dominio antiguo que aún recibe correo de clientes o dominios nacionales distintos que deben compartir los mismos nombres de bandeja de entrada.

Por ejemplo:

hello@brand.example   → hello@company.example
billing@brand.example → billing@company.example

La parte anterior a @ permanece exactamente igual. Si la dirección coincidente no existe en el dominio principal, TrekMail no la inventa.

Planes y límites

Un dominio conectado puede seguir a un solo dominio principal a la vez. Un dominio principal puede servir a varios dominios conectados, hasta el límite normal de dominios de la cuenta. Un dominio no puede ser conectado y principal al mismo tiempo, lo que simplifica el enrutamiento y evita bucles.

Ambos dominios deben pertenecer a la misma cuenta, usar TrekMail para el correo entrante, estar activos y tener registros MX operativos. Si el estado del plan, la cuenta o el DNS cambia más adelante, TrekMail conserva la conexión guardada, pero pausa la entrega hasta que se restablezca el requisito.

Qué conserva la prioridad

El alias de dominio solo se ejecuta después de que TrekMail comprueba las direcciones exactas ya configuradas en el dominio conectado. Los buzones, alias, direcciones de reenvío, reenvíos de buzón y ajustes catch-all existentes conservan su prioridad documentada.

Esto significa que una regla intencionada para sales@brand.example no se sustituye silenciosamente por sales@company.example.

API REST

Los tres endpoints utilizan el ID del dominio conectado:

El endpoint conserva la ruta original /matching-addresses para no romper las integraciones existentes. El panel y la documentación utilizan el término más claro del sector alias de dominio.

PUT y DELETE requieren una cabecera Idempotency-Key. Es seguro repetir la misma solicitud correcta con la misma clave.

Conectar un dominio

PUT /api/v1/domains/42/matching-addresses
Authorization: Bearer tm_live_...
Idempotency-Key: matching-brand-company-v1
Content-Type: application/json

{
  "primary_domain_id": 7
}

Consultar el resultado

{
  "configured": true,
  "enabled": true,
  "delivering": true,
  "status": "delivering",
  "paused_reason": null,
  "alias_domain": {
    "id": 42,
    "domain": "brand.example"
  },
  "primary_domain": {
    "id": 7,
    "domain": "company.example"
  },
  "primary_domain_restricted": false
}

configured indica si la conexión está guardada. delivering indica si funciona ahora. Comprueba ambos valores en lugar de considerar una fila guardada como prueba de que el correo circula.

Cuando un token puede acceder al dominio conectado, pero no al principal, la respuesta establece primary_domain_restricted en true y oculta la identidad del dominio principal. Nunca revela un dominio fuera de la lista permitida del token.

Estados de entrega

Herramientas MCP

El mismo proceso está disponible mediante tres herramientas de dominio:

• get_domain_alias: consulta la conexión guardada y el estado de entrega en tiempo real;
• set_domain_alias: conecta o cambia el dominio principal;
• remove_domain_alias: desconéctalo después de confirm_remove: true.

El MCP alojado aplica los permisos aprobados durante OAuth. El administrador de un MCP alojado localmente puede exigir aprobación expresa para acciones de escritura. Ambos métodos aplican el plan de la cuenta, los ámbitos del token, la lista de dominios permitidos y la validación del servidor.

Los nombres de las herramientas y los títulos para clientes utilizan alias de dominio. El endpoint REST conserva su ruta original por compatibilidad.

Eliminación segura y bajadas de plan

Eliminar una conexión no borra ninguno de los dominios ni ningún buzón. Los buzones exactos, alias, direcciones de reenvío y reglas catch-all no cambian. Las direcciones sin coincidencia que dependían solo de esta función pueden empezar a rebotar, así que revisa el dominio antes de confirmar la eliminación.

Eliminar un dominio conectado quita automáticamente su conexión. TrekMail no eliminará un dominio principal mientras haya dominios conectados que dependan de él; desconéctalos primero.

Después de bajar a Nano, la conexión continúa guardada, pero deja de entregar. Volver a Starter o un plan superior la restaura sin introducir de nuevo el dominio principal.

Registro de auditoría

Cada cambio mediante API o MCP aparece en Agentes de IA y API → Registro de auditoría. Los eventos de conexión y cambio registran ambos ID de dominio, el dominio principal anterior cuando corresponde, el token que actúa, el ID de solicitud y la hora. La eliminación registra qué conexión se quitó. Estos eventos no incluyen contenido del correo ni credenciales.

Lista de solución de problemas

1. Confirma que ambos dominios figuran como Activos y usan TrekMail para el correo entrante.
2. Comprueba que los registros MX de ambos dominios estén correctos.
3. Confirma que la cuenta tenga Starter, Pro o Agency.
4. Revisa juntos configured, delivering, status y paused_reason.
5. Comprueba si un buzón exacto, alias, dirección de reenvío o regla catch-all ya controla la dirección.
6. Revisa en el registro de auditoría la última conexión, modificación o eliminación.