Domainaliase über API und MCP verwalten

Mit einem Domainalias kann eine Domain den Empfangsadressen einer anderen Domain folgen. Wenn hello@company.example E-Mails empfangen kann, kann hello@brand.example sie an dasselbe Ziel zustellen, ohne ein zweites Postfach oder einen zweiten Alias anzulegen und zu verwalten.

Diese Funktion dient nur dem Empfang. Sie erstellt keine Absenderadresse, ändert SMTP nicht und erlaubt niemandem, unter der verbundenen Domain zu senden.

Wann die Funktion nützlich ist

Domainaliase eignen sich für Unternehmen mit mehreren Markendomains, einer alten Domain, die noch Kundenpost empfängt, oder getrennten Länderdomains, die dieselben Postfachnamen verwenden sollen.

Beispiel:

hello@brand.example   → hello@company.example
billing@brand.example → billing@company.example

Der Teil vor @ bleibt exakt gleich. Wenn die entsprechende Adresse auf der primären Domain nicht existiert, erfindet TrekMail sie nicht.

Tarife und Limits

Eine verbundene Domain kann jeweils einer primären Domain folgen. Eine primäre Domain kann mehrere verbundene Domains bis zum normalen Domainlimit des Kontos bedienen. Eine Domain kann nicht zugleich verbundene und primäre Domain sein. Das vereinfacht das Routing und verhindert Schleifen.

Beide Domains müssen demselben Konto gehören, TrekMail für eingehende E-Mails verwenden, aktiv sein und funktionierende MX-Einträge besitzen. Wenn sich Tarif, Konto- oder DNS-Status später ändern, behält TrekMail die gespeicherte Verbindung bei, pausiert die Zustellung aber bis zur Wiederherstellung der Voraussetzung.

Was Vorrang behält

Der Domainalias wird erst angewendet, nachdem TrekMail die bereits auf der verbundenen Domain konfigurierten exakten Adressen geprüft hat. Bestehende Postfächer, Aliase, Weiterleitungsadressen, Postfachweiterleitungen und Catch-all-Einstellungen behalten ihre dokumentierte Priorität.

Eine beabsichtigte Regel für sales@brand.example wird daher nicht unbemerkt durch sales@company.example ersetzt.

REST-API

Die drei Endpoints verwenden die ID der verbundenen Domain:

Der Endpoint behält den ursprünglichen Pfad /matching-addresses, damit bestehende Integrationen funktionieren. Dashboard und Dokumentation verwenden den eindeutigeren Branchenbegriff Domainalias.

PUT und DELETE benötigen einen Idempotency-Key-Header. Dieselbe erfolgreiche Anfrage kann mit demselben Schlüssel sicher wiederholt werden.

Domain verbinden

PUT /api/v1/domains/42/matching-addresses
Authorization: Bearer tm_live_...
Idempotency-Key: matching-brand-company-v1
Content-Type: application/json

{
  "primary_domain_id": 7
}

Ergebnis lesen

{
  "configured": true,
  "enabled": true,
  "delivering": true,
  "status": "delivering",
  "paused_reason": null,
  "alias_domain": {
    "id": 42,
    "domain": "brand.example"
  },
  "primary_domain": {
    "id": 7,
    "domain": "company.example"
  },
  "primary_domain_restricted": false
}

configured zeigt, ob die Verbindung gespeichert ist. delivering zeigt, ob sie derzeit funktioniert. Prüfen Sie beide Werte, statt eine gespeicherte Zeile als Beleg für den E-Mail-Fluss anzusehen.

Wenn ein Token auf die verbundene, aber nicht auf die primäre Domain zugreifen darf, setzt die Antwort primary_domain_restricted auf true und verbirgt die Identität der primären Domain. Eine Domain außerhalb der Zulassungsliste des Tokens wird nie offengelegt.

Zustellungsstatus

MCP-Tools

Derselbe Ablauf ist über drei Domain-Tools verfügbar:

• get_domain_alias: gespeicherte Verbindung und aktuellen Zustellungsstatus lesen;
• set_domain_alias: primäre Domain verbinden oder ändern;
• remove_domain_alias: Verbindung nach confirm_remove: true trennen.

Gehostetes MCP wendet die während OAuth genehmigten Berechtigungen an. Ein Administrator eines lokal gehosteten MCP kann eine ausdrückliche Freigabe für Schreibaktionen verlangen. Beide Wege erzwingen Kontotarif, Token-Scopes, Domain-Zulassungsliste und serverseitige Validierung.

Toolnamen und kundenseitige Titel verwenden Domainalias. Der REST-Endpoint behält aus Kompatibilitätsgründen seinen ursprünglichen Pfad.

Sicheres Entfernen und Tarifwechsel

Das Entfernen einer Verbindung löscht weder eine Domain noch ein Postfach. Exakte Postfächer, Aliase, Weiterleitungsadressen und Catch-all-Regeln bleiben unverändert. Nicht zugeordnete Adressen, die nur von dieser Zuordnung abhingen, können danach E-Mails zurückweisen. Prüfen Sie die Domain daher vor der Bestätigung.

Beim Löschen einer verbundenen Domain wird ihre Verbindung automatisch entfernt. TrekMail löscht keine primäre Domain, solange verbundene Domains von ihr abhängen; trennen Sie diese zuerst.

Nach einem Wechsel zu Nano bleibt die Verbindung gespeichert, stellt aber nicht mehr zu. Die Rückkehr zu Starter oder höher stellt sie wieder her, ohne die primäre Domain erneut einzugeben.

Audit-Protokoll

Jede API- oder MCP-Änderung erscheint unter KI-Agenten und API → Audit-Protokoll. Verbindungs- und Änderungsereignisse erfassen beide Domain-IDs, gegebenenfalls die vorherige primäre Domain, das handelnde Token, Anfrage-ID und Uhrzeit. Beim Entfernen wird die entfernte Verbindung erfasst. E-Mail-Inhalte oder Zugangsdaten werden nicht in diese Ereignisse geschrieben.

Checkliste zur Fehlerbehebung

1. Bestätigen Sie, dass beide Domains als Aktiv angezeigt werden und TrekMail für eingehende E-Mails verwenden.
2. Prüfen Sie die MX-Einträge beider Domains.
3. Bestätigen Sie Starter, Pro oder Agency für das Konto.
4. Betrachten Sie configured, delivering, status und paused_reason gemeinsam.
5. Prüfen Sie, ob bereits ein exaktes Postfach, ein Alias, eine Weiterleitungsadresse oder eine Catch-all-Regel für die Adresse zuständig ist.
6. Prüfen Sie das Audit-Protokoll auf die letzte Verbindung, Änderung oder Entfernung.