Verbundene Konten über API und MCP

Mit verbundenen Konten kann ein Webmail-Postfach Nachrichten aus externen Postfächern, Gmail, Yahoo, iCloud, Outlook.com/Microsoft 365 oder einem beliebigen IMAP-Server lesen und darüber senden. Die Nachrichten-API und die MCP-Tools stellen dieselbe Funktion programmatisch bereit: Sie können verbundene Konten auflisten, hinzufügen, testen, bearbeiten und entfernen sowie normale Nachrichtenaufrufe (Auflisten, Lesen, Senden, Markierungen, Verschieben, Löschen und Ordner) an ein verbundenes Konto statt an das eigene Postfach des Tokens richten.

Einfach ausgedrückt: mailbox_id wählt das TrekMail-Postfach, für das der Agent handeln darf, während external_account_id Gmail oder ein anderes darin verbundenes Postfach auswählt. Sie sind nicht austauschbar.

Tarife, Limits und Kataloggröße

Die Verwaltung verbundener Konten bietet sieben Nachrichten-Tools. Ein Token mit eingeschränkten Scopes sieht nur die Tools, die es tatsächlich nutzen kann, und nicht den vollständigen Produktkatalog.

Vorbereitungen

• Verbundene Konten sind eine Webmail-Funktion und nutzen die Oberfläche für Nachrichten-Token (/api/v1/messages/...). Die Autorisierung erfolgt mit einem Nachrichten-Token mit den unten genannten Scopes und nicht mit einem Dashboard-API-Token.
• Tariflimits gelten pro Postfach: Starter 5, Pro 10, Agency 30. Der Nano-Tarif umfasst keine verbundenen Konten.
• Jeder Endpoint ist auf das eigene Postfach des Tokens beschränkt. Ein Token kann nur seine eigenen verbundenen Konten sehen und verwalten, niemals die eines anderen Postfachs.
• Anmeldedaten und OAuth-Token werden in Antworten immer maskiert. Sie können ein Passwort oder App-Passwort eingeben, es aber nie wieder auslesen.
• Outlook.com- und Microsoft 365-Konten werden über die Microsoft-Anmeldung (OAuth) in der Webmail-Oberfläche verbunden. Die API kann sie nach dem Verbinden verwalten und verwenden, führt den interaktiven Microsoft-Zustimmungsschritt jedoch nicht aus.

Scopes

Das Ansprechen eines verbundenen Kontos in einem Nachrichtenaufruf erfordert denselben Scope, den der Aufruf bereits benötigt (zum Beispiel erfordert das Auflisten seiner Nachrichten messages:read, das Senden messages:send).

Verbundene Konten verwalten

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

Konto hinzufügen

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

Anfragetext:

Rufen Sie zuerst POST /external-accounts/detect auf, um provider und die Servereinstellungen automatisch auszufüllen. Der Speicheraufruf führt vor dem Speichern einen echten IMAP- + SMTP-Test aus. Ein 422 mit einer Fehlerkategorie (auth, tls, network, transient_throttle) bedeutet, dass die Anmeldedaten nicht funktionierten und nichts gespeichert wurde.

Verbundenes Konto in Nachrichtenaufrufen ansprechen

Jeder Nachrichten-Endpoint, der auf einem Postfach arbeitet, akzeptiert eine optionale external_account_id. Geben Sie sie an, um den Aufruf für dieses verbundene Konto statt für das eigene Postfach des Tokens auszuführen. Lassen Sie sie weg, um das Postfach selbst zu verwenden. Dies gilt für Auflisten, Lesen, Senden, Antworten, Markierungen, Verschieben, Löschen und die Ordnerliste.

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": "..."
}

Beim Senden nur mit external_account_id wird der eigene SMTP-Server dieses Kontos verwendet (mit SPF/DKIM seines Anbieters). Wenn Sie stattdessen eine quellgebundene identity_id angeben, wird die Domain oder die Route des gespeicherten Profils dieser Senden-als-Identität verwendet, während die Gesendet-Kopie weiterhin im verbundenen Posteingang gespeichert wird. Das Konto muss funktionsfähig sein (status: active). Ein getrenntes Konto gibt einen Fehler mit der Aufforderung zurück, es erneut zu verbinden. Siehe Senden-als-Adressen über API und MCP.

MCP-Tools

Dieselbe Funktion steht KI-Agenten über MCP zur Verfügung (sowohl auf dem privaten stdio-Server als auch auf dem öffentlichen MCP-Server):

Die Nachrichten-Tools list_messages, read_message, send_message, list_folders, update_message_flags, move_message, delete_message, prepare_reply, prepare_reply_all und prepare_forward akzeptieren das optionale Argument external_account_id. Senden, Entwurfserstellung und Planung akzeptieren außerdem eine quellgebundene identity_id, die von list_identities zurückgegeben wird.

Da die Verwaltungs-Tools ausgehende Verbindungen zu beliebigen Mailservern mit vom Benutzer angegebenen Anmeldedaten öffnen, gelten für sie dieselben Sicherheitsvorkehrungen wie für die übrige Funktion für verbundene Konten: Host-Zulassungsliste, Sperrung privater Bereiche, Port-Zulassungsliste und Verbindungslimits pro Host.