Direcciones Enviar como mediante API y MCP

TrekMail separa dos tareas que usan credenciales y permisos distintos:

1. La superficie Panel/Ops controla los perfiles SMTP reutilizables y el enrutamiento de dominios. Usa un token tm_live_ con smtp:read o smtp:write.
2. La superficie Correo web/Mensajes controla las direcciones de remitente disponibles para un buzón y una bandeja conectada. Usa un token tm_msg_ con messages:read, messages:write o messages:send.

Esto es intencional. Un token de buzón puede seleccionar una ruta de envío ya autorizada, pero no puede revelar credenciales SMTP ni gestionar la infraestructura de otra cuenta.

Versión breve

• Si envías solo con external_account_id, los destinatarios ven la dirección propia de esa cuenta conectada y se usa su servidor SMTP.
• Si también envías un identity_id vinculado al origen, los destinatarios ven la dirección empresarial de la identidad. TrekMail usa la ruta del dominio o el perfil SMTP guardado asignado a esa identidad y después guarda la copia de Enviados en la bandeja conectada.
• Starter permite configurar y usar esta función en el correo web. Pro y Agency también permiten automatizarla mediante API o MCP. Nano no dispone de espacios para cuentas conectadas.

Las herramientas disponibles de API y MCP evolucionan con el producto. Enviar como utiliza las familias SMTP y de mensajes, y cada conexión solo ve el subconjunto que permiten su plan, ámbitos y permisos aprobados.

Modelo de enrutamiento

Cuando se envía external_account_id sin identity_id, TrekMail realiza el envío mediante el servidor SMTP de esa cuenta externa y usa su propia dirección.

Cuando se envían ambos valores, TrekMail considera la cuenta externa como el destino de la bandeja/Enviados y la identidad como la dirección de remitente visible + ruta SMTP:

connected Gmail inbox
  + Send As identity sales@example.com
  + identity route: domain or saved SMTP profile
  = recipients see sales@example.com
    mail is delivered through the identity route
    the Sent copy is appended to that Gmail account

La identidad y la cuenta externa deben estar vinculadas entre sí. Omitir el origen o proporcionar una identidad de otro buzón devuelve 422 identity_unavailable.

1. Inspeccionar o configurar SMTP en la API del panel

Usa un token de Ops.

Las lecturas del perfil nunca devuelven la contraseña. El endpoint de uso es la forma segura de que un agente explique el impacto antes de editar o eliminar un perfil compartido.

Herramientas MCP: get_domain_smtp, set_domain_smtp, list_domain_smtp_profiles, get_domain_smtp_profile_usage, create_domain_smtp_profile, update_domain_smtp_profile, delete_domain_smtp_profile, test_domain_smtp, get_domain_smtp_test_status, get_account_smtp_default, set_account_smtp_default.

2. Listar direcciones para la bandeja exacta

Usa un token de Mensajes:

GET /api/v1/messages/identities?external_account_id=42
Authorization: Bearer tm_msg_...

La respuesta incluye identities específicas del origen, todas las external_identities configuradas, sending_addresses, los send_as_domains aptos, la reply_from_policy del buzón y, solo para el buzón del propietario de la cuenta, los smtp_profiles guardados que pueden seleccionarse directamente.

MCP: llama a list_identities con external_account_id.

MCP alojado frente a stdio local

Las herramientas de mensajes tienen una diferencia importante de transporte:

• MCP HTTP alojado (OAuth): pasa también mailbox_id en cada llamada de herramienta de mensajes. El servidor alojado lo usa para aprovisionar un token de mensajes de corta duración para ese buzón exacto. Por ejemplo, llama a list_identities con { "mailbox_id": 7, "external_account_id": 42 }.
• MCP stdio autoalojado (tm_msg_): no pases mailbox_id. El token de mensajes estático ya está vinculado a un buzón, por lo que el esquema de la herramienta solo necesita external_account_id.

external_account_id nunca sustituye a mailbox_id: selecciona una bandeja conectada dentro del buzón ya autorizado. Las herramientas SMTP del panel siguen estando limitadas a la cuenta y no reciben mailbox_id en ninguno de los transportes.

3. Crear una identidad Enviar como

POST /api/v1/messages/identities
Authorization: Bearer tm_msg_...
Idempotency-Key: send-as-sales-v1
Content-Type: application/json

{
  "kind": "send_as",
  "external_account_id": 42,
  "email": "sales@example.com",
  "name": "Example Sales",
  "reply_to": "sales@example.com",
  "smtp_mode": "domain"
}

email ya debe ser la dirección principal de este buzón o un alias activo habilitado para enviar. Su dominio debe estar activo y pertenecer a la misma cuenta. smtp_mode: domain sigue la ruta del dominio configurada en el panel. smtp_mode: profile fija la identidad a smtp_connection_id; la selección directa de perfiles está limitada al buzón del propietario de la cuenta.

external_account_id es opcional y conviene precisar su significado:

• Inclúyelo cuando leas el correo de esa dirección mediante una bandeja conectada de Gmail, Outlook o IMAP. La identidad queda vinculada a esa bandeja y solo puede usarse con ella.
• Omítelo cuando el correo se reenvíe a un buzón de TrekMail, en el flujo de bandeja compartida, donde un cliente conserva el correo en su proveedor y reenvía copias a un buzón del equipo. La identidad pertenece al propio buzón y cualquier miembro con permiso de envío puede usarla.

Una bandeja personal conectada nunca puede asociarse a un buzón compartido: es privada para la persona que la conectó. Omite allí external_account_id.

MCP: create_identity con kind=send_as. En MCP alojado, incluye el mailbox_id principal como se explicó anteriormente.

4. Enviar, crear un borrador, programar, responder o reenviar

Las operaciones habituales de mensajes aceptan el mismo par de origen:

{
  "external_account_id": 42,
  "identity_id": 91,
  "to": ["customer@example.net"],
  "subject": "Hello",
  "body": { "text": "Hello from Example Sales" }
}

identity_id es compatible con el envío inmediato, el guardado/actualización de borradores y el envío programado. La preparación de respuestas/reenvíos acepta external_account_id y selecciona la identidad correspondiente a partir de los encabezados de entrega. La identidad seleccionada vuelve a autorizarse cuando se ejecuta un mensaje en cola; desactivar su alias, dominio, perfil o cuenta conectada detiene la entrega en lugar de recurrir silenciosamente a otra dirección de remitente.

Herramientas MCP: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all y prepare_forward.

Política de respuesta

PATCH /api/v1/messages/identities/reply-policy
Authorization: Bearer tm_msg_...
Idempotency-Key: reply-policy-v1

{ "reply_from_policy": "recipient" }

recipient responde desde la dirección que recibió el mensaje cuando es posible. default siempre comienza con el valor predeterminado del buzón para el correo normal. MCP usa set_reply_from_policy.

Reglas de seguridad y aislamiento

• Las credenciales SMTP nunca pasan a la API de mensajes ni a la respuesta MCP.
• Cada cuenta externa e identidad está limitada al buzón del token de mensajes.
• Una identidad Enviar como conectada solo puede usarse con su external_account_id exacto; una identidad propiedad del buzón solo puede usarse sin él.
• La dirección de remitente ya debe estar autorizada como dirección del buzón o alias habilitado para enviar; la API no puede inventar direcciones de remitente arbitrarias.
• Se requiere una ruta operativa antes de la creación y se vuelve a comprobar durante la entrega.
• Los encabezados Reply-To personalizados no pueden entrar en conflicto con el valor Reply-To guardado de una identidad.
• Los cambios de identidades y perfiles mediante MCP requieren el permiso de escritura correspondiente. Un administrador MCP alojado localmente puede exigir aprobación explícita para las acciones de escritura; el envío también requiere confirmación para cada mensaje.

No hacen falta cadenas nuevas de ámbitos de token. Los tokens smtp:* y messages:* existentes siguen funcionando según sus permisos actuales.

¿Qué límite de envío se aplica?

Las llamadas API también conservan sus propias protecciones contra abusos: de forma predeterminada, 60 solicitudes de envío por minuto y token de mensajes, y 100 envíos API al día en todo el buzón. Se aplican sin importar qué servidor entregue finalmente el correo.