Adresses d’expéditeur avec API et MCP

TrekMail sépare deux tâches qui utilisent des identifiants et des autorisations différents :

1. L’interface Tableau de bord/Ops gère les profils SMTP réutilisables et le routage des domaines. Elle utilise un jeton tm_live_ avec smtp:read ou smtp:write.
2. L’interface Messagerie web/Messages gère les adresses d’expéditeur disponibles pour une boîte et une boîte de réception connectée. Elle utilise un jeton tm_msg_ avec messages:read, messages:write ou messages:send.

Cette séparation est volontaire. Un jeton de boîte peut sélectionner une route d’envoi déjà autorisée, mais il ne peut pas révéler les identifiants SMTP ni gérer l’infrastructure d’un autre compte.

En bref

• Si vous envoyez uniquement avec external_account_id, les destinataires voient l’adresse propre de ce compte connecté et son propre serveur SMTP est utilisé.
• Si vous envoyez aussi un identity_id lié à la source, les destinataires voient l’adresse professionnelle de l’identité. TrekMail utilise la route du domaine ou le profil SMTP enregistré attribué à cette identité, puis conserve la copie Envoyés dans la boîte connectée.
• Starter permet de configurer et d’utiliser cette fonction dans la messagerie web. Pro et Agency permettent aussi de l’automatiser par API ou MCP. Nano ne propose aucun emplacement de compte connecté.

Les outils API et MCP disponibles évoluent avec le produit. Envoyer en tant que utilise les familles SMTP et de messages, et chaque connexion ne voit que le sous-ensemble autorisé par son forfait, ses portées et ses permissions approuvées.

Modèle de routage

Lorsque external_account_id est envoyé sans identity_id, TrekMail utilise le propre serveur SMTP de ce compte externe et sa propre adresse.

Lorsque les deux valeurs sont envoyées, TrekMail considère le compte externe comme la destination de la boîte de réception/Envoyés et l’identité comme l’adresse d’expéditeur visible + route 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

L’identité et le compte externe doivent être liés. Omettre la source ou fournir une identité provenant d’une autre boîte renvoie 422 identity_unavailable.

1. Examiner ou configurer SMTP dans l’API du tableau de bord

Utilisez un jeton Ops.

La lecture d’un profil ne renvoie jamais le mot de passe. L’endpoint d’utilisation permet à un agent d’expliquer sans risque les conséquences avant de modifier ou supprimer un profil partagé.

Outils 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. Répertorier les adresses pour la boîte exacte

Utilisez un jeton Messages :

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

La réponse comprend les identities propres à la source, toutes les external_identities configurées, les sending_addresses, les send_as_domains admissibles, la reply_from_policy de la boîte et, uniquement pour la boîte du propriétaire du compte, les smtp_profiles enregistrés qui peuvent être sélectionnés directement.

MCP: appelez list_identities avec external_account_id.

MCP hébergé et stdio local

Les outils de messages présentent une différence de transport importante :

• MCP HTTP hébergé (OAuth) : transmettez aussi mailbox_id à chaque appel d’outil de messages. Le serveur hébergé l’utilise pour créer un jeton de messages de courte durée pour cette boîte exacte. Par exemple, appelez list_identities avec { "mailbox_id": 7, "external_account_id": 42 }.
• MCP stdio auto-hébergé (tm_msg_) : ne transmettez pas mailbox_id. Le jeton de messages statique est déjà lié à une boîte, donc le schéma de l’outil a seulement besoin de external_account_id.

external_account_id ne remplace jamais mailbox_id: il sélectionne une boîte de réception connectée dans la boîte déjà autorisée. Les outils SMTP du tableau de bord restent limités au compte et n’acceptent mailbox_id dans aucun des deux transports.

3. Créer une identité Envoyer en tant que

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 doit déjà être l’adresse principale de cette boîte ou un alias actif autorisé à envoyer. Son domaine doit être actif et appartenir au même compte. smtp_mode: domain suit la route du domaine configurée dans le tableau de bord. smtp_mode: profile associe l’identité à smtp_connection_id; la sélection directe d’un profil est réservée à la boîte du propriétaire du compte. L’appartenance ne permet pas de créer une identité send_as ordinaire pour l’adresse commune.

external_account_id est facultatif, et il convient de préciser sa signification :

• Incluez-le lorsque vous lisez les messages de cette adresse par une boîte Gmail, Outlook ou IMAP connectée. L’identité est alors liée à cette boîte et ne peut être utilisée qu’avec elle.
• Omettez-le lorsque les messages sont plutôt transférés dans une boîte TrekMail, selon le flux de boîte partagée où un client conserve ses messages chez son propre fournisseur et en transfère des copies à une boîte d’équipe.

Une boîte de réception personnelle connectée ne peut jamais être associée à une boîte partagée: elle reste privée pour la personne qui l’a connectée. Omettez alors external_account_id.

MCP: create_identity avec kind=send_as. Sur le MCP hébergé, incluez le mailbox_id parent comme indiqué ci-dessus.

4. Envoyer, créer un brouillon, programmer, répondre ou transférer

Les opérations de messages ordinaires acceptent la même paire de sources :

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

identity_id est pris en charge par l’envoi immédiat, l’enregistrement/mise à jour des brouillons et l’envoi programmé. La préparation d’une réponse ou d’un transfert accepte external_account_id et sélectionne l’identité correspondante à partir des en-têtes de livraison. L’identité sélectionnée est de nouveau autorisée au moment d’exécuter un message en attente. Désactiver son alias, son domaine, son profil ou son compte connecté arrête la livraison au lieu d’utiliser silencieusement une autre adresse d’expéditeur.

Outils MCP: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all et prepare_forward.

Envoyer en tant que boîte partagée

Pour envoyer depuis la boîte partagée via Message API ou MCP, le membre doit avoir Lire et Envoyer en tant que. Utilisez son jeton avec shared_mailbox_id. Un jeton de la boîte partagée peut lire, mais pas envoyer.

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

Le jeton reste lié au membre, et la piste d'audit aussi: un envoi depuis l'adresse d'équipe enregistre qui l'a effectué. GET /messages/identities?shared_mailbox_id=5 liste les adresses depuis lesquelles cette boîte peut envoyer.

Deux refus à prévoir :

• shared_mailbox_not_a_sender (403): le jeton lui-même appartient à une boîte partagée. La lecture n'est pas affectée ; seul l'envoi exige un membre.
• shared_mailbox_send_denied (403): Le membre doit avoir Lire et Envoyer en tant que.

Les adresses d’équipe du webmail personnel ne sont ni listées ni acceptées comme identités de Message API. Une identity_id refusée renvoie 422 identity_unavailable ; modifier ou supprimer une adresse d’équipe renvoie 422 identity_delegated. Ces refus contiennent hint et identity_id, ainsi que shared_mailbox_id et member_id lorsque disponibles. Un envoi partagé refusé contient shared_mailbox_id et, si le membre peut uniquement envoyer, member_id. Lisez le conseil avant de réessayer ; omettre le contexte partagé ou l’identité fait envoyer depuis une autre adresse.

Message API permet de programmer avec shared_mailbox_id pour les membres ayant l’autorisation Lire et Envoyer en tant que. Le webmail ne propose pas d’envoi programmé dans une boîte partagée. Pour lister, déplacer l’heure ou annuler, passez le même shared_mailbox_id ; les lignes appartiennent à la boîte partagée. La ligne n’identifie pas la personne ayant programmé l’envoi.

MCP: send_message, schedule_message et list_identities acceptent shared_mailbox_id. Sur le MCP hébergé, mailbox_id reste le membre.

Politique de réponse

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

{ "reply_from_policy": "recipient" }

recipient répond depuis l’adresse qui a reçu le message lorsque c’est possible. default commence toujours par la valeur par défaut de la boîte pour les messages ordinaires. MCP utilise set_reply_from_policy.

Règles de sécurité et d’isolation

• Les identifiants SMTP ne figurent jamais dans la réponse de l’API de messages ou de MCP.
• Chaque compte externe et chaque identité est limité à la boîte du jeton de messages.
• Une identité Envoyer en tant que connectée ne peut être utilisée qu’avec son external_account_id exact; une identité appartenant à la boîte ne peut être utilisée que sans celui-ci.
• L’adresse d’expéditeur doit déjà être autorisée comme adresse de boîte ou alias autorisé à envoyer; l’API ne peut pas inventer d’adresses d’expéditeur arbitraires.
• Une route fonctionnelle est requise avant la création et de nouveau vérifiée au moment de la livraison.
• Les en-têtes Reply-To personnalisés ne peuvent pas entrer en conflit avec le champ Répondre à enregistré d’une identité.
• Les modifications d’identité et de profil par MCP nécessitent l’autorisation d’écriture appropriée. Un administrateur MCP hébergé localement peut exiger une approbation explicite pour les actions d’écriture; l’envoi nécessite aussi une confirmation par message.

Aucune nouvelle chaîne de portée de jeton n’est requise. Les jetons smtp:* et messages:* existants continuent de fonctionner selon leurs autorisations actuelles.

Quelle limite d’envoi s’applique ?

Les appels API conservent aussi leurs protections contre les abus: par défaut, 60 requêtes d’envoi par minute et par jeton de messages, et 100 envois API par jour dans l’ensemble de la boîte. Elles s’appliquent quel que soit le serveur qui livre finalement le message.

Articles associés

• Comptes connectés avec API et MCP
• Portées de l’API et autorisations des forfaits
• Présentation de l’API REST TrekMail pour les développeurs
• Envoyez depuis une adresse professionnelle avec Gmail