Senden-als-Adressen über API und MCP

TrekMail trennt zwei Aufgaben, die unterschiedliche Anmeldedaten und Berechtigungen verwenden:

1. Die Dashboard/Ops-Oberfläche verwaltet wiederverwendbare SMTP-Profile und das Domain-Routing. Sie verwendet ein tm_live_-Token mit smtp:read oder smtp:write.
2. Die Webmail/Nachrichten-Oberfläche verwaltet die Absenderadressen, die einem Postfach und einem verbundenen Posteingang zur Verfügung stehen. Sie verwendet ein tm_msg_-Token mit messages:read, messages:write oder messages:send.

Diese Trennung ist beabsichtigt. Ein Postfach-Token kann eine bereits autorisierte Senderoute auswählen, aber weder SMTP-Anmeldedaten offenlegen noch die Infrastruktur eines anderen Kontos verwalten.

Kurzfassung

• Wenn Sie nur mit external_account_id senden, sehen die Empfänger die eigene Adresse dieses verbundenen Kontos und dessen eigener SMTP-Server wird verwendet.
• Wenn Sie zusätzlich eine quellgebundene identity_id senden, sehen die Empfänger die Geschäftsadresse der Identität. TrekMail verwendet die dieser Identität zugewiesene Domain-Route oder das gespeicherte SMTP-Profil und speichert anschließend die Gesendet-Kopie im verbundenen Posteingang.
• Starter kann dies in Webmail einrichten und verwenden. Pro und Agency können es außerdem über API oder MCP automatisieren. Nano hat keine Plätze für verbundene Konten.

Die verfügbaren API- und MCP-Tools entwickeln sich mit dem Produkt weiter. Senden als verwendet die SMTP- und Nachrichtenfamilien. Jede Verbindung sieht nur die Teilmenge, die ihr Tarif, ihre Scopes und die genehmigten Berechtigungen erlauben.

Routing-Modell

Wenn external_account_id ohne identity_id gesendet wird, sendet TrekMail über den eigenen SMTP-Server dieses externen Kontos und verwendet dessen eigene Adresse.

Wenn beide Werte gesendet werden, behandelt TrekMail das externe Konto als Ziel für Posteingang/Gesendet und die Identität als sichtbare Absenderadresse + SMTP-Route:

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

Identität und externes Konto müssen miteinander verknüpft sein. Wird die Quelle weggelassen oder eine Identität aus einem anderen Postfach angegeben, wird 422 identity_unavailable zurückgegeben.

1. SMTP in der Dashboard-API prüfen oder konfigurieren

Verwenden Sie ein Ops-Token.

Beim Lesen eines Profils wird das Passwort nie zurückgegeben. Über den Nutzungs-Endpoint kann ein Agent die Auswirkungen vor dem Bearbeiten oder Löschen eines gemeinsam verwendeten Profils sicher erklären.

MCP-Tools: 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. Adressen für den genauen Posteingang auflisten

Verwenden Sie ein Nachrichten-Token:

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

Die Antwort enthält quellenspezifische identities, alle konfigurierten external_identities, sending_addresses, geeignete send_as_domains, die reply_from_policy des Postfachs und, nur für das Postfach des Kontoinhabers, gespeicherte smtp_profiles, die direkt ausgewählt werden können.

MCP: Rufen Sie list_identities mit external_account_id auf.

Gehostetes MCP und lokales stdio

Bei Nachrichten-Tools gibt es einen wichtigen Transport-Unterschied:

• Gehostetes HTTP-MCP (OAuth): Übergeben Sie außerdem mailbox_id bei jedem Aufruf eines Nachrichten-Tools. Der gehostete Server verwendet sie, um ein kurzlebiges Nachrichten-Token für genau dieses Postfach bereitzustellen. Rufen Sie beispielsweise list_identities mit { "mailbox_id": 7, "external_account_id": 42 } auf.
• Selbst gehostetes stdio-MCP (tm_msg_): Übergeben Sie mailbox_id nicht. Das statische Nachrichten-Token ist bereits an ein Postfach gebunden, daher benötigt das Tool-Schema nur external_account_id.

external_account_id ersetzt mailbox_id nie: Sie wählt einen verbundenen Posteingang innerhalb des bereits autorisierten Postfachs. Dashboard-SMTP-Tools bleiben kontobezogen und akzeptieren bei keinem der beiden Transporte mailbox_id.

3. Senden-als-Identität erstellen

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 muss bereits die primäre Adresse dieses Postfachs oder ein aktiver, sendefähiger Alias sein. Die Domain muss aktiv sein und demselben Konto gehören. smtp_mode: domain folgt der im Dashboard konfigurierten Domain-Route. smtp_mode: profile bindet die Identität an smtp_connection_id; die direkte Profilauswahl ist auf das Postfach des Kontoinhabers beschränkt.

external_account_id ist optional. Ihre genaue Bedeutung ist wichtig:

• Geben Sie sie an, wenn Sie die Nachrichten dieser Adresse über einen verbundenen Gmail-, Outlook- oder IMAP-Posteingang lesen. Die Identität wird dann an diesen Posteingang gebunden und kann nur mit ihm verwendet werden.
• Lassen Sie sie weg, wenn Nachrichten stattdessen an ein TrekMail-Postfach weitergeleitet werden. Dies ist der Arbeitsablauf für gemeinsame Posteingänge, bei dem ein Kunde seine Nachrichten beim eigenen Anbieter belässt und Kopien an ein Team-Postfach weiterleitet. Die Identität gehört dem Postfach selbst und jedes Mitglied mit Sendeberechtigung kann sie verwenden.

Ein persönlicher verbundener Posteingang kann nie einem gemeinsamen Postfach zugeordnet werden: Er bleibt für die Person privat, die ihn verbunden hat. Lassen Sie external_account_id dort weg.

MCP: create_identity mit kind=send_as. Geben Sie beim gehosteten MCP wie oben beschrieben die übergeordnete mailbox_id an.

4. Senden, Entwurf erstellen, planen, antworten oder weiterleiten

Die normalen Nachrichtenoperationen akzeptieren dasselbe Quellenpaar:

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

identity_id wird beim sofortigen Senden, Speichern/Aktualisieren von Entwürfen und geplanten Senden unterstützt. Die Vorbereitung von Antworten/Weiterleitungen akzeptiert external_account_id und wählt anhand der Zustellkopfzeilen die passende Identität aus. Die ausgewählte Identität wird erneut autorisiert, wenn eine Nachricht in der Warteschlange tatsächlich ausgeführt wird. Das Deaktivieren ihres Alias, ihrer Domain, ihres Profils oder ihres verbundenen Kontos stoppt die Zustellung, anstatt unbemerkt auf eine andere Absenderadresse zurückzugreifen.

MCP-Tools: send_message, save_draft, update_draft, schedule_message, prepare_reply, prepare_reply_all und prepare_forward.

Antwortrichtlinie

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

{ "reply_from_policy": "recipient" }

recipient antwortet nach Möglichkeit von der Adresse, welche die Nachricht empfangen hat. default beginnt bei normalen Postfachnachrichten immer mit dem Postfachstandard. MCP verwendet set_reply_from_policy.

Sicherheits- und Isolationsregeln

• SMTP-Anmeldedaten gelangen nie in die Antwort der Nachrichten-API oder von MCP.
• Jedes externe Konto und jede Identität ist auf das Postfach des Nachrichten-Tokens beschränkt.
• Eine verbundene Senden-als-Identität kann nur mit ihrer genauen external_account_id verwendet werden; eine postfacheigene Identität nur ohne sie.
• Die Absenderadresse muss bereits als Postfachadresse oder sendefähiger Alias autorisiert sein; die API kann keine beliebigen Absenderadressen erfinden.
• Vor der Erstellung wird eine funktionierende Route vorausgesetzt und bei der Zustellung erneut geprüft.
• Benutzerdefinierte Reply-To-Kopfzeilen dürfen nicht mit dem gespeicherten Reply-To einer Identität in Konflikt stehen.
• Änderungen an Identitäten und Profilen über MCP erfordern die entsprechende Schreibberechtigung. Ein lokal gehosteter MCP-Administrator kann eine ausdrückliche Genehmigung für Schreibaktionen verlangen; auch das Senden erfordert eine Bestätigung pro Nachricht.

Es sind keine neuen Token-Scope-Zeichenfolgen erforderlich. Vorhandene smtp:*- und messages:*-Token funktionieren gemäß ihren aktuellen Berechtigungen weiter.

Welches Sendelimit gilt?

API-Aufrufe behalten außerdem ihre eigenen Schutzmaßnahmen gegen Missbrauch: standardmäßig 60 Sendeanfragen pro Minute und Nachrichten-Token sowie 100 API-Sendungen pro Tag über das gesamte Postfach. Sie gelten unabhängig davon, welcher Server die E-Mail letztlich zustellt.