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. La membresía no permite crear una identidad send_as normal para la dirección compartida.

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.

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.

Enviar como buzón compartido

Para enviar desde el buzón compartido mediante la Message API o MCP, el miembro necesita Leer y Enviar como. Usa su token con shared_mailbox_id. Un token del buzón compartido puede leer, pero no enviar.

{
  "shared_mailbox_id": 5,
  "to": ["customer@example.net"],
  "subject": "Re: your order",
  "body": { "text": "Answered by the team" }
}

El token sigue vinculado al miembro, y el rastro de auditoría también: un envío desde la dirección del equipo registra quién lo hizo. GET /messages/identities?shared_mailbox_id=5 enumera las direcciones desde las que ese buzón puede enviar.

Dos rechazos previsibles:

• shared_mailbox_not_a_sender (403): el token pertenece a un buzón compartido. La lectura no se ve afectada; solo el envío exige un miembro.
• shared_mailbox_send_denied (403): El miembro necesita Leer y Enviar como.

Las direcciones de equipo del webmail personal no se enumeran ni aceptan como identidades de Message API. Una identity_id rechazada devuelve 422 identity_unavailable; cambiar o borrar una dirección de equipo devuelve 422 identity_delegated. Estos errores incluyen hint e identity_id, además de shared_mailbox_id y member_id cuando están disponibles. Un envío compartido rechazado incluye shared_mailbox_id y, si el miembro solo puede enviar, member_id. Lee la pista antes de reintentar; omitir el contexto compartido o la identidad envía desde otra dirección.

La Message API permite programar con shared_mailbox_id para miembros con los permisos Leer y Enviar como. Webmail no permite programar dentro de un buzón compartido. Para listar, cambiar la hora o cancelar, usa el mismo shared_mailbox_id; las filas pertenecen al buzón compartido. La fila no identifica a quien programó el mensaje.

MCP: send_message, schedule_message y list_identities aceptan shared_mailbox_id. En el MCP alojado, mailbox_id sigue siendo el miembro.

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 Responder a 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.