Gekoppelde accounts via API en MCP

Met gekoppelde accounts kan een webmailbox berichten lezen en verzenden vanuit externe mailboxen, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 of een willekeurige IMAP-server. De berichten-API en de MCP-tools bieden programmatisch dezelfde mogelijkheid: je kunt gekoppelde accounts weergeven, toevoegen, testen, bewerken en verwijderen. Je kunt ook gewone berichtaanroepen (weergeven, lezen, verzenden, markeringen, verplaatsen, verwijderen en mappen) op een gekoppeld account richten in plaats van op de eigen mailbox van het token.

Eenvoudig gezegd: mailbox_id kiest de TrekMail-mailbox waarvoor de agent mag handelen, terwijl external_account_id Gmail of een andere gekoppelde mailbox daarbinnen kiest. Ze zijn niet uitwisselbaar.

Abonnementen, limieten en catalogusomvang

Het beheer van gekoppelde accounts biedt zeven berichtentools. Een token met beperkte scopes ziet alleen de tools die het daadwerkelijk kan gebruiken, niet de volledige productcatalogus.

Voordat je begint

• Gekoppelde accounts zijn een webmail-functie en gebruiken het oppervlak voor het berichtentoken (/api/v1/messages/...). Dit wordt geautoriseerd door een berichtentoken met de onderstaande scopes, niet door een dashboard-API-token.
• Abonnementslimieten gelden per mailbox: Starter 5, Pro 10, Agency 30. Het Nano-abonnement bevat geen gekoppelde accounts.
• Elk endpoint is beperkt tot de eigen mailbox van het token. Een token kan alleen zijn eigen gekoppelde accounts zien en beheren, nooit die van een andere mailbox.
• Aanmeldgegevens en OAuth-tokens zijn in reacties altijd gemaskeerd. Je kunt een wachtwoord of app-wachtwoord invoeren, maar je kunt het nooit teruglezen.
• Outlook.com- en Microsoft 365-accounts worden via Microsoft-aanmelding (OAuth) in de webmailinterface gekoppeld. De API kan ze na het koppelen beheren en gebruiken, maar voert de interactieve Microsoft-toestemmingsstap niet uit.

Scopes

Voor het richten van een berichtaanroep op een gekoppeld account is dezelfde scope vereist die de aanroep al nodig heeft (voor het weergeven van berichten is bijvoorbeeld messages:read nodig; voor verzenden messages:send).

Gekoppelde accounts beheren

Basispad: /api/v1/messages/external-accounts

Een account toevoegen

POST /api/v1/messages/external-accounts
Scope: messages:write

Aanvraagtekst:

Roep eerst POST /external-accounts/detect aan om provider en de serverinstellingen automatisch in te vullen. De opslagaanroep voert vóór het opslaan een echte IMAP- + SMTP-test uit. Een 422 met een foutcategorie (auth, tls, network, transient_throttle) betekent dat de aanmeldgegevens niet werkten en dat er niets is opgeslagen.

Een gekoppeld account in berichtaanroepen kiezen

Elk berichten-endpoint dat op een mailbox werkt, accepteert een optionele external_account_id. Geef deze op om de aanroep voor dat gekoppelde account uit te voeren in plaats van voor de eigen mailbox van het token; laat deze weg om de mailbox zelf te gebruiken. Dit geldt voor weergeven, lezen, verzenden, beantwoorden, markeringen, verplaatsen, verwijderen en het weergeven van mappen.

GET /api/v1/messages?external_account_id=42&folder=INBOX
Scope: messages:read

POST /api/v1/messages/send
Scope: messages:send
{
  "external_account_id": 42,
  "to": "someone@example.com",
  "subject": "Sent from my connected account",
  "text": "..."
}

Verzenden met alleen external_account_id verloopt via de eigen SMTP-server van dat account (met SPF/DKIM van de provider). Als je in plaats daarvan een brongebonden identity_id opgeeft, wordt het domein of de opgeslagen profielroute van die Verzenden als-identiteit gebruikt, terwijl de kopie in Verzonden nog steeds in de gekoppelde inbox wordt opgeslagen. Het account moet gezond zijn (status: active); een losgekoppeld account geeft een foutmelding waarin je wordt gevraagd het opnieuw te koppelen. Zie Verzenden als-adressen via API en MCP.

MCP-tools

Dezelfde mogelijkheid is via MCP beschikbaar voor AI-agenten (zowel op de privé-stdio-server als op de openbare MCP-server):

De berichtentools list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all en prepare_forward accepteren het optionele argument external_account_id. Verzenden, concepten maken en plannen accepteren ook een brongebonden identity_id die door list_identities wordt teruggegeven.

Omdat de beheertools uitgaande verbindingen openen naar willekeurige mailservers met door de gebruiker opgegeven aanmeldgegevens, volgen ze dezelfde veiligheidsmaatregelen als de rest van de functie voor gekoppelde accounts: een lijst met toegestane hosts, geblokkeerde privébereiken, een lijst met toegestane poorten en verbindingslimieten per host.