TrekMail-REST-API-Übersicht für Entwickler

Öffne TrekMail in Claude, wähle Connect, melde dich an und erlaube den Zugriff. Du musst keinen API-Token erstellen. Prüfe Berechtigungen oder trenne die App unter KI-Agenten und API, Token, Verbundene Apps.

Deine eigene White-Label-Marke: verwende die MCP-Adresse aus deinem gebrandeten Dashboard und den Namen deiner Marke. Füge sie als custom connector hinzu; der öffentliche TrekMail-Eintrag meldet dich bei TrekMail an und ersetzt nicht die Verbindung deiner Marke.

Mit der TrekMail-API können Sie Domains, Postfächer, Weiterleitungen, DNS, E-Mail-Migrationen und Webmail-Vorgänge über einen HTTP-Client oder KI-Agenten verwalten. Dazu gehören das Lesen und Senden von Nachrichten, Entwürfe, Zeitplanung, Ordner, Kontakte, Kalender, Identitäten, Vorlagen und blockierte Absender. Authentifizierte Anfragen verwenden ein Bearer-Token, Antworten werden als JSON zurückgegeben und API-Aktivitäten werden protokolliert.

E-Mails mit einem Schlüssel lesen

Wähle bei Pro und Agency beim Erstellen eines API-Schlüssels E-Mails lesen. Das ausdrückliche Recht lautet mailboxes:messages:read; mailboxes:read zeigt nur Adressen und Verbindungsdaten. Alle Postfächer schließt aktuelle und zukünftige Postfächer ein; alternativ kannst du bestimmte Domains und Postfächer auswählen. Bestehende Schlüssel erhalten keine neuen Rechte automatisch.

Verwende den Kontoschlüssel mit den GET-Routen unten. Senden, Löschen und andere Änderungen benötigen weiterhin separate Nachrichtenzugangsdaten und Rechte. Gehostetes MCP akzeptiert OAuth, keine tm_live_- oder tm_msg_-Schlüssel. Der Fehler zum Token-Typ nennt dem Agenten den passenden Endpunkt oder die Autorisierung.

GET /api/v1/mailboxes/{mailbox}/messages
GET /api/v1/mailboxes/{mailbox}/folders
GET /api/v1/mailboxes/{mailbox}/messages/{uid}
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/raw
GET /api/v1/mailboxes/{mailbox}/messages/{uid}/attachments/{index}

Ihre Möglichkeiten

• REST API v1 mit einem JSON-Anfrage- und Antwortformat.
• Bearer-Token-Authentifizierung: keine Cookies oder Sitzungen für authentifizierte API-Aufrufe.
• Idempotenzschlüssel bei Schreibvorgängen, die sie benötigen, um doppelte Arbeit bei Wiederholungen zu verhindern.
• Ratenbegrenzung pro Token mit Retry-After-Headern.
• Auditprotokoll, das in Ihrem Dashboard unter KI-Agenten & API, Audit-Protokoll sichtbar ist.
• MCP-Server mit einem Katalog, der nach den Anmeldedaten, dem Transport und den Sicherheitseinstellungen der aktuellen Verbindung gefiltert wird. Eine eng begrenzte Projektverbindung sieht daher nur die Werkzeuge, die sie verwenden kann.
• Domain-Aliasse: Verbinden Sie reine Empfangsadressen einer sekundären Domain mit denselben lokalen Teilen einer primären Domain, einschließlich gespeicherter und aktiver Zustellungszustände sowie sicherer Entfernung. Siehe Domain-Aliasse über API und MCP.
• Dual-Token-Architektur: separate Ops-Token für die Infrastruktur und Nachrichten-Token für vollständige E-Mail-Vorgänge wie Lesen, Senden, Entwürfe, Zeitplanung, Kontakte, Kalender, Identitäten, Vorlagen und Ordner.
• Einblicke in ausgehende Zustellbarkeit und Bounces: Rufen Sie im Dashboard die Summen für gesendet, zugestellt, Hard-Bounce und Soft-Bounce sowie SMTP-Codes und Antworten pro Empfänger ab. Siehe Zustellbarkeit und Bounces.
• App-Passwörter für Mail-Apps: Verwalten Sie separate Passwörter für IMAP, SMTP, Kalender und Kontakte und legen Sie fest, welche Passwörter Mail-Apps akzeptieren. Diese ersetzen weder API-Bearer-Token noch Message-API-Token. Siehe App-Passwörter über API und MCP.
• Postfach-Speichernutzung: list_mailboxes und get_mailbox geben used_mb, quota_mb, allocation_mb und is_pooled zurück. So kann ein Agent ohne Dashboard-Zugriff Postfächer erkennen, die sich ihrem Limit nähern.
• White-Label-Verwaltung: Prüfen Sie die Einrichtung, verwalten Sie Branding pro Domain, laden Sie Kunden ein, steuern Sie Rollen und Domains, sperren oder reaktivieren Sie Zugriffe und überprüfen Sie Aktivitäten über API oder MCP. Siehe Branding-Leitfaden und Leitfaden zur Teamverwaltung.

Drive-API und Dateiautomatisierung

Drive gehört zur öffentlichen API. Es umfasst Account-Drive und Drive-Bereiche von Postfächern, Nutzung, Ordnernavigation, Uploads, Datei- und Ordnerverwaltung, Papierkorb, Massenaktionen, öffentliche Freigabelinks, Verwaltung von Passwörtern für Synchronisierungsgeräte und den schreibgeschützten Status des Drive-Storage-Add-ons.

Drive verwendet elf Ops-Token-Bereiche: drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, drive:addon:read, drive:devices:read und drive:devices:write. Abrechnungsaktionen für das Drive-Add-on wie Kauf, Größenänderung und Kündigung bleiben dem Dashboard vorbehalten und werden nicht als API- oder MCP-Schreibvorgänge angeboten.

Beginnen Sie mit der Drive-API-Übersicht oder dem Drive-API-Schnellstart.

Dual-Token-Architektur

Die API verwendet zwei unabhängige Token-Typen. Sie können je nach Bedarf einen oder beide verwenden:

Ops-Token und Nachrichten-Token besitzen separate Bereiche und Ratenlimits. Ein einzelner Agent kann beide Token gleichzeitig verwenden, indem sie in der MCP-Serverumgebung konfiguriert werden.

Nachrichten-Token sind in den Tarifen Pro und Agency verfügbar.

Bevor Sie beginnen

• Alle Tarife haben API-Zugriff:
  • Nano: Email Verifier. Fügen Sie ein Drive-Storage-Add-on hinzu, um vollständigen Drive-API- und MCP-Zugriff zu erhalten.
  • Starter: Vollständiger Zugriff auf Drive und Email Verifier sowie schreibgeschützter Zugriff auf die übrigen Infrastrukturbereiche. Verwenden Sie das Dashboard für deren Schreibaktionen.
  • Pro / Agency: Vollständiger Zugriff auf die Basis-API einschließlich Nachrichten-Token. White-Label-Bereiche werden hinzugefügt, solange die Testversion oder das kostenpflichtige Add-on aktiv ist.
• Möchten Sie einen KI-Agenten verbinden? Fügen Sie https://trekmail.net/mcp in einem kompatiblen Client als Remote-MCP-Server hinzu. Wenn er Browserautorisierung unterstützt, ist kein manuelles Token erforderlich. Unter KI-Agenten verbinden (MCP) finden Sie Remote-, CLI-/Desktop-, Bridge- und selbst gehostete Optionen.
• Entwickeln Sie eine eigene Integration? Erstellen Sie unter KI-Agenten & API, Token, Token erstellen ein tm_live_-Token und senden Sie es als Authorization: Bearer …. Siehe API-Token erstellen und verwalten.
• Ist die API neu für Sie? Klicken Sie oben auf der Seite KI-Agenten & API auf Tour starten, um eine kurze Einführung in Verbindungsmethoden, Token-Verwaltung, verbundene Apps und das Auditprotokoll zu erhalten.

Funktionsweise der Authentifizierung

Jede Anfrage muss Ihr Token im Authorization-Header enthalten:

Authorization: Bearer tm_live_abc123...

Ops-Token beginnen mit tm_live_, Nachrichten-Token mit tm_msg_. Beide werden bei der Erstellung einmal angezeigt und können danach nicht erneut eingeblendet werden.

Wenn das Token fehlt, widerrufen wurde oder abgelaufen ist, gibt die API 401 mit dem Fehlercode unauthenticated zurück.

Basis-URL und Versionierung

Alle Endpoints befinden sich unter:

https://trekmail.net/api/v1

Die Basis-URL wird in Ihrem Dashboard KI-Agenten & API unter Kurzreferenz angezeigt. Die Version steht im URL-Pfad. Sollte jemals v2 eingeführt werden, funktioniert v1 weiterhin.

Antwortformat

Erfolgreiche Antworten geben JSON mit einem data-Schlüssel für einzelne Ressourcen oder eine paginierte Liste zurück:

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Fehlerantworten folgen einer einheitlichen Struktur:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

Anfrage-IDs

Jede Antwort enthält einen X-Request-Id-Header. Sie können mit X-Request-Id in der Anfrage auch eine eigene ID übergeben. Sie wird unverändert zurückgegeben und im Auditprotokoll erfasst.

Ratenlimits

Für jedes Token gilt ein Limit pro Minute. Wenn Sie das Limit erreichen, gibt die API 429 mit einem Retry-After-Header zurück, der angibt, wann Sie es erneut versuchen können.

Destruktive Vorgänge (Löschabsichten) haben ein zusätzliches tägliches Limit pro Token und eine Wartezeit zwischen aufeinanderfolgenden Löschungen.

Für Schreibvorgänge bei Migrationen (Start, Abbruch, Wiederholung) gilt ein eigenes Ratenlimit von 10 Anfragen pro Minute und Token sowie eine serverweite Parallelitätsgrenze, die 503 zurückgibt, wenn global zu viele Migrationen ausgeführt werden.

Nachrichten-Token verwenden separate Limits. Standardmäßig gelten 30 Leseanfragen pro Minute und Token, 60 Sendeanfragen pro Minute und Token, 5,000 erfolgreiche Lesevorgänge pro Tag und Token sowie 100 API-Sendungen pro Tag über ein Postfach. Ein zweiter Sicherheitszähler für Sendungen beträgt standardmäßig 500 pro Token und Tag; normalerweise greift zuerst die niedrigere Postfachgrenze. Diese API-Schutzmaßnahmen ersetzen weder die verwalteten SMTP-Limits Ihres Tarifs noch die eigenen Limits eines externen Anbieters.

Idempotenz

Als idempotent markierte Endpoints, die den Zustand ändern, erfordern einen Idempotency-Key-Header. Dies gilt für Erstellungen, Aktualisierungen, Sendungen und Löschungen, bei denen eine automatische Wiederholung sonst Arbeit duplizieren könnte. Leseähnliche POST-Aktionen wie die Erkennung eines Anbieters oder ein Verbindungstest benötigen keinen; prüfen Sie die Endpoint-Tabelle oder die OpenAPI-Spezifikation. Wenn Sie denselben Schlüssel mit demselben Body senden, gibt die API die ursprüngliche Antwort wieder, ohne Duplikate zu erstellen. Eine Ausnahme bilden Nachrichtensendungen, deren Zustellung fehlgeschlagen ist (etwa wegen eines ausgeschöpften Sendekontingents): Für sie gibt die API das frühere 202 nicht mehr wieder, sodass dieselbe Nachricht später mit demselben Inhalt erneut gesendet werden kann. Wenn Sie eine eigene X-Request-Id übergeben, verwenden Sie für diesen Versuch eine neue: Die API behandelt eine Sendung aus demselben Postfach mit derselben X-Request-Id ebenfalls als Wiederholung. Mit der alten ID erhalten Sie also nur die ursprüngliche, fehlgeschlagene Sendung zurück, und es wird nichts gesendet. Ein erneuter Versuch für eine Sendung, die noch aussteht oder bereits zugestellt wurde, erhält weiterhin die ursprüngliche Antwort.

Idempotency-Key: create-mailbox-alice-2024

Wenn Sie denselben Schlüssel mit einem anderen Body senden, gibt die API 409 Conflict zurück.

Postfach-Speicherzuweisung

Jeder Endpoint, der ein Postfach oder eine Einladung erstellt, POST /api/v1/mailboxes, /api/v1/mailboxes:bulk, /api/v1/mailboxes/invites, /api/v1/mailboxes/invites:bulk, akzeptiert optional die Ganzzahl storage_allocation_mb.

Zuweisungen werden gegen den aktuellen Speicher abzüglich vorhandener dedizierter Postfächer und ausstehender dedizierter Einladungen geprüft. Massen-Endpoints prüfen jedes Element mit fester Zuweisung gegen den Rest, der beim Anlegen dieses Elements frei ist: Was passt, wird angelegt, was nicht mehr passt, schlägt einzeln mit dem Grund storage_pool_exceeded fehl (207 teilweiser Erfolg oder 422, wenn alle fehlschlagen). In einer Domain mit einem White-Label-Speicherlimit für Kunden muss eine feste Größe außerdem in den Rest dieses Limits passen: Eine einzelne Erstellung oder Einladung gibt 422 client_storage_limit_exceeded mit limit_mb, allocated_mb, available_mb und requested_mb in details zurück (ein auf bestimmte Domains beschränkter Schlüssel erhält nur available_mb und requested_mb, wenn das Limit auch eine Domain umfasst, auf die er keinen Zugriff hat), und ein Element einer Massenanfrage schlägt mit dem Grund client_storage_limit_exceeded fehl. Der Speicher wird aktualisiert, wenn ein dediziertes Postfach gelöscht, eine Einladung eingelöst (die Zuweisung geht auf das neue Postfach über) oder eine ausstehende Einladung abläuft.

Bei Einladungen wird die Zuweisung im Zugangscode gespeichert und beim Einlösen auf das neue Postfach übertragen. Wenn der Speicher zu diesem Zeitpunkt nicht mehr für die angeforderte Zuweisung ausreicht (z. B. weil ein anderer Administrator seine dedizierte Zuweisung zwischenzeitlich vergrößert hat), wird das neue Postfach beim Einlösen problemlos auf gemeinsamen Speicher herabgestuft, statt dass der Vorgang fehlschlägt. Der Empfänger sieht auf der Erfolgsseite einen Hinweis.

Um ein bestehendes Postfach zu ändern, senden Sie PATCH /api/v1/mailboxes/{id}/storage mit storage_allocation_mb als feste Größe in MB oder als null für gemeinsamen Speicher. Der Aufruf braucht mailboxes:write und einen Idempotency-Key, funktioniert bei aktiven und pausierten Postfächern und führt dieselben Prüfungen aus wie Speicher bearbeiten im Dashboard: storage_pool_exceeded, wenn der freie Speicher des Kontos zu klein ist, und in einer Domain mit Speicherlimit für Kunden außerdem client_storage_limit_exceeded oder client_storage_below_usage, wenn die neue Größe unter dem liegt, was das Postfach bereits speichert. Gemeinsamer Speicher wird nie wegen seiner Größe abgelehnt. Ein Postfach in Kürzlich gelöscht oder eines, das gerade gelöscht wird, gibt 422 mailbox_unavailable zurück. Das MCP-Tool heißt set_mailbox_storage.

White-Label-Speicherlimits für Kunden liegen unter /api/v1/white-label/client-limits; siehe White-Label-Teams mit API und MCP verwalten. Ein auf bestimmte Domains beschränkter Schlüssel sieht in GET /api/v1/account nur seinen Teil des Kontos: usage zählt nur seine Domains und Postfächer, limits.max_storage_mb ist das Limit des Kunden, wenn alle seine Domains eines teilen, das keine weitere Domain umfasst, und client_limit enthält dieses Limit (id, storage_limit_mb, allocated_mb, used_bytes) oder null. Andere Aufrufer erhalten die Antwort unverändert.

Neue reguläre Postfächer, auch bei Massenerstellung, Einladungen und Bereitstellung durch KI-Agenten, folgen der standardmäßig aktivierten Einstellung Kontoeinstellungen > Neue Postfächer > Mail-Apps brauchen App-Passwörter. Änderungen stellen bestehende Postfächer nicht um. POST /api/v1/mailboxes kann für client_auth_mode den Wert app_password_only oder password_or_app_password wählen; ohne Angabe gilt die Kontoeinstellung. Postfachlisten und Detailressourcen liefern client_auth_mode und app_passwords_count (aktive App-Passwörter). Freigegebene Postfächer haben keine eigenen App-Passwörter und keinen eigenen Anmeldemodus.

Die sechs MCP-Werkzeuge zur Verwaltung von App-Passwörtern sind list_mailbox_app_passwords, create_mailbox_app_password, rotate_mailbox_app_password, revoke_mailbox_app_password, set_mailbox_client_auth_mode, update_account. update_account: Setzt new_mailbox_client_auth_mode für künftige Postfächer; bestehende Postfächer behalten ihren Modus. Erfordert mailboxes:write, ein Inhaber-Token oder einen Inhaber-Konnektor ohne Ressourcenbeschränkungen und TREKMAIL_ALLOW_DESTRUCTIVE=true bei selbst gehostetem stdio.

Drive-Zugriff für Postfächer

Jedes Postfach besitzt eine drive_access-Stufe, die bestimmt, auf wie viel von Drive die Person in Webmail zugreifen kann. Sie wird in der Postfachressource zurückgegeben und kann mit PATCH /api/v1/mailboxes/{id} oder für mehrere Postfächer gleichzeitig mit POST /api/v1/mailboxes:drive-access festgelegt werden.

Der Speicher wird im gesamten Konto gemeinsam genutzt. Diese Einstellung steuert daher, wie viel davon eine einzelne Person mit Dateien belegen kann.

Sperren der Postfachanmeldung

Die Anmeldung eines Postfachs kann gesperrt werden, während es weiterhin E-Mails empfängt: Webmail, IMAP, SMTP und Gerätepasswörter werden abgewiesen und offene Sitzungen beendet, die Zustellung bleibt jedoch unberührt. Nichts wird zurückgewiesen und alles wartet, wenn die Anmeldung wiederhergestellt wird. Legen Sie dies mit POST /api/v1/mailboxes/{id}:suspend-login (und :resume-login) oder für mehrere Postfächer mit POST /api/v1/mailboxes:login-access fest.

Die Postfachressource meldet dies als login_suspended, login_suspended_at und login_suspended_reason. Lesen Sie login_suspended, um festzustellen, ob sich die Person anmelden kann, und status, um zu prüfen, ob das Postfach selbst läuft. Ein gesperrtes Postfach bleibt active, weil es weiterhin E-Mails annimmt. :pause ist etwas anderes: Es setzt status auf disabled und stoppt auch die Zustellung.

Eine Anmeldesperre widerruft alle App-Passwörter endgültig. Das Wiederherstellen der Anmeldung stellt sie nicht wieder her. Wenn ein Administrator im Dashboard, per API oder durch einen KI-Agenten ein neues Postfachpasswort setzt, werden ebenfalls alle App-Passwörter widerrufen. Dasselbe gilt bei Passwortwiederherstellung, Umwandlung in ein freigegebenes Postfach und Verschieben nach „Kürzlich gelöscht“. Das Wiederherstellen eines gelöschten Postfachs bringt sie nicht zurück.

Siehe Postfachanmeldung über API sperren.

Der Massen-Endpoint akzeptiert genau einen Selektor, mailbox_ids, domain_id oder all, und gibt das Ergebnis zurück:

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

domain_id ist der geeignete Selektor, wenn eine Domain einem Kunden entspricht. Postfächer, die bereits die angeforderte Stufe verwenden, zählen als matched, aber nicht als updated. Der Aufruf kann daher sicher wiederholt werden.

Gemeinsame Postfächer werden beim Einzel-Endpoint mit 422 drive_access_not_applicable abgewiesen und vom Massen-Endpoint übersprungen und gezählt: Sie haben keinen eigenen Webmail-Benutzer, ihre Mitglieder öffnen sie daher mit ihrer eigenen Stufe, und ein in der gemeinsamen Zeile gespeicherter Wert würde nichts ändern.

Die Einschränkung gilt sowohl für die API als auch für die Oberfläche. Der Drive-Bereich eines eingeschränkten Postfachs fehlt in GET /api/v1/drive/spaces, seine Dateien antworten bei Abfrage per id mit 404, und ein Synchronisierungsgerät kann nicht dafür erstellt werden.

Weiterleitungsadressen

GET /api/v1/domains/{id}/forwarding-addresses gibt mehr als nur die Liste zurück, da zwei Eigenschaften einer Weiterleitungsadresse nicht in der Adresse selbst sichtbar sind:

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max gilt pro Domain und hängt vom Tarif ab: 100 bei Pro, 300 bei Agency und 25 gespeichert, aber inaktiv, bei Nano oder Starter.
• delivery.active zeigt an, ob diese Regeln gerade jetzt E-Mails weiterleiten. Es ist false bei einem Tarif unter requires_plan und false, solange paused_until gesetzt ist (das Konto hat seine stündliche Senderate überschritten; siehe Sendelimits pro Tarif). Eine Regel kann is_active: true sein und trotzdem nicht zustellen. Lesen Sie daher delivery und nicht nur is_active, bevor Sie melden, dass die Weiterleitung funktioniert.

Das Erstellen ist in einem Tarif ohne Zustellung erlaubt und gibt 201 zurück: Die Regel wird gespeichert und beginnt nach einem Upgrade zu funktionieren. Dies entspricht dem Dashboard, das solche Regeln als gespeichert und inaktiv anzeigt.

Ablehnungen werden als 422 zurückgegeben, wobei error.code auf validation_error oder limit_exceeded gesetzt ist: eine bereits in der Domain verwendete Adresse, ein Empfänger in derselben Domain (was eine Schleife verursachen würde), eine Empfängerdomain ohne funktionierenden MX oder ein ausgeschöpftes Domainbudget.

POST und DELETE für diese Endpoints erfordern einen Idempotency-Key; PATCH nicht.

Zustellungsverlauf

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log gibt zurück, was tatsächlich mit den neuesten E-Mails geschehen ist, beginnend mit der neuesten:

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcome ist delivered, deferred (vorübergehender Fehler, Wiederholung läuft), failed (der Server des Empfängers hat die Nachricht abgelehnt) oder blocked. Letzteres bedeutet, dass unser Spamfilter die Nachricht vor der Weiterleitung gestoppt hat und sie den Empfänger nie erreicht hat. blocked als Bounce zu behandeln würde jemanden dazu bringen, den empfangenden Server wegen eines Problems auf unserer Seite zu untersuchen.

limit (1-200, Standard 100) ist der einzige Parameter. Das Fenster entspricht der Aufbewahrung des Tarifs: 30 Tage bei Agency, andernorts 7. Ältere Ereignisse können nicht abgefragt werden, da weitergeleitete Ereignisse bereinigt werden.

Gemeinsame Team-Postfächer

Ein gemeinsames Postfach hat einen eigenen Teameingang. can_read entspricht Lesen, can_send entspricht Senden als. Gemeinsame Ordner erfordern Lesen. Senden aus dem gemeinsamen Posteingang über Message API erfordert beide Rechte. Es gibt kein gemeinsames Passwort, keine separate Anmeldung und keine Mitgliedsrollen.

GET /api/v1/mailboxes und GET /api/v1/mailboxes/{id} geben jetzt mailbox_type ("user" oder "shared") und den booleschen Wert is_shared zurück; gemeinsame Postfächer enthalten außerdem shared_member_count. Verwenden Sie diese Felder, um einen Team-Posteingang von einem normalen zu unterscheiden, bevor Sie die Mitglieder-Endpoints aufrufen.

Bei der Rückwandlung werden alle Mitglieder entfernt. Legen Sie ein neues Webmail-Passwort fest und erstellen Sie dann im Tab Sicherheit App-Passwörter für Mail-Apps.

Berechtigungsänderungen können 422 no_access_left zurückgeben, wenn beide Rechte ausgeschaltet wären, 422 send_only_disabled, wenn die gewünschte Änderung an Lesen nicht verfügbar ist, oder 422 last_reader, wenn die letzte aktive lesende Person den Zugriff verlieren würde. Beenden Sie den gesamten Zugriff mit Entfernen und geben Sie vorher einem anderen aktiven Mitglied Lesen. Jeder dieser Fehler liefert außerdem shared_mailbox_id, bei einem bestehenden Mitglied member_id und einen hint, der die Anfrage nennt, die das Problem behebt.

Die Mitglieder-Endpoints verwenden Ihre vorhandenen Bereiche mailboxes:read / mailboxes:write. Es gibt keinen separaten Bereich für gemeinsame Postfächer.

Um nativen Zugriff aus Mail-Apps zu ermitteln, rufen Sie GET /api/v1/mailboxes/{member_mailbox_id}/client-setup für das reguläre Postfach eines Mitglieds auf. Das Objekt shared_mailboxes meldet dauerhafte native Bereitschaft, tatsächliche Sendebereitschaft für Senden als und deren Begründung, genaue Inbox-/Gesendet-/Archive-/Junk-Pfade sowie erlaubte Vorgänge. can_send ist die zugewiesene Berechtigung Senden als, kein Beleg dafür, dass SMTP derzeit bereit ist. Der Endpoint gibt nie ein Passwort zurück. Ein Aufruf mit der id des gemeinsamen Postfachs gibt 422 direct_login_unavailable zurück, da sich die gemeinsame Adresse nicht direkt authentifizieren kann.

shared_mailboxes.items[] enthält nur Mitgliedschaften mit der Berechtigung Lesen, wenn nativer Ordnerzugriff aktiviert ist. delegated_send_addresses ist eine separate Liste verfügbarer Team-Absenderadressen mit id, email und display_name; sie kann leer sein. Sie gewährt keinen Ordnerzugriff und prüft keine Sendebereitschaft. Diese Adressen sind keine Message-API-Identitäten. Verwenden Sie die zurückgegebenen Server, auch bei White Label, statt einen Plattform-Hostnamen zu kopieren.

Das Entfernen eines Mitglieds, die Änderung von can_read / can_send oder die Umwandlung eines gemeinsamen in ein reguläres Postfach synchronisiert die Mailserverberechtigungen, wenn nativer Zugriff aktiviert ist. Eine Antwort 503 native_access_sync_failed kann wiederholt werden und garantiert, dass Mitgliedschaft, Berechtigung oder Postfachtyp unverändert geblieben sind, statt den Vorgang teilweise anzuwenden.

Verfügbare Endpoints

Drive besitzt eine eigene Referenz und wird hier nicht wiederholt. Siehe Drive-API-Übersicht. Die für Abwärtskompatibilität beibehaltenen SMTP-Endpoints auf Kontoebene werden unter SMTP-Routing pro Domain beschrieben, statt als aktuell aufgeführt zu werden.

Die Cloudflare-Endpoints folgen demselben Ablauf wie das Dashboard: Token validieren, Zonen auflisten, Domains verbinden, DNS-Änderungen in der Vorschau anzeigen und anschließend anwenden. Sowohl /cloudflare/preview als auch /cloudflare/apply akzeptieren zwei optionale Steuerungen pro Domain:

• included_records, eine nach Domain-ID gegliederte Zulassungsliste der zu ändernden Einträge: { "123": ["mx_primary", "spf_record"] }. Ausgelassene Einträge werden übersprungen. So können Sie nur MX und SPF anwenden und später zu DKIM zurückkehren. Lassen Sie das Feld aus, um alle Einträge anzuwenden.
• confirmed_conflicts: Wenn die Vorschau einen vorhandenen Eintrag mit einem anderen Wert meldet, führen Sie dessen Eintrags-ID hier auf (gleiche Form { domain_id: [record_ids] }), um die Ersetzung zu genehmigen.

Die Eintrags-IDs (mx_primary, spf_record, dkim_primary, dmarc_main, …) stammen direkt aus der Vorschauantwort. Ein typischer Agent ruft daher zuerst die Vorschau auf und übergibt die gewünschten IDs anschließend an die Anwendung:

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

SMTP-Routing pro Domain und Kontostandard

SMTP wird pro Domain konfiguriert. Jede Domain wählt eine von drei Routen: verwalteter Plattformversand, ein gespeichertes SMTP-Profil (Ihr eigener Anbieter, für mehrere Domains wiederverwendbar) oder „nicht konfiguriert“. Ein einziger kontoweiter Standard legt fest, mit welcher Route neue Domains beginnen.

Endpoints pro Domain (smtp:read / smtp:write):

Hinweise zum Route-Body:

• smtp_mode=platform wählt verwalteten Versand; smtp_mode=profile erfordert smtp_connection_id; not_configured löscht die Route.
• Mit smtp_mode=inherit folgt die Domain laufend dem Kontostandard: Ändert sich der Standard, ändert sich diese Domain ebenfalls. Die Weboberfläche schreibt immer konkrete Routen, das Backend unterstützt jedoch weiterhin inherit. Deshalb gibt GET den Wert effective_smtp_mode zurück, der zeigt, welchen Wert inherit derzeit ergibt.
• Diese Route ändert nur die eigene Domain. Um eine Route zum Konto-Standard zu machen (Als Konto-Standard festlegen im Dashboard), verwenden Sie unten PUT /api/v1/smtp/default; mit apply_to_all: true werden zusätzlich alle Domains darauf umgestellt (Auf alle Domains anwenden).

Endpoints für den kontoweiten Standard (smtp:read / smtp:write):

Wird ein Profil gelöscht, das als Kontostandard diente, wird der Standard auf den Tarifbasiswert zurückgesetzt.

Ein Schlüssel, der auf einige Domains oder Postfächer beschränkt ist, erhält 403 token_resource_constrained von PUT /api/v1/smtp/default, von den alten PUT und DELETE /api/v1/smtp und beim Löschen eines gespeicherten Profils, weil jede dieser Aktionen die Route von Domains ändert, auf die er möglicherweise keinen Zugriff hat. Ein auf einige Domains beschränkter Schlüssel erhält dieselbe Antwort, wenn er ein Profil bearbeitet, das auch eine Domain außerhalb seiner Liste nutzt.

Veraltete Endpoints. Die GET-/PUT /api/v1/smtp-Endpoints auf Kontoebene (sowie DELETE /api/v1/smtp/{id}, POST /api/v1/smtp:test, GET /api/v1/smtp:test-status/{jobId}) bleiben aus Gründen der Abwärtskompatibilität erhalten, steuern aber nicht mehr das Routing pro Domain. Verwenden Sie die oben genannten Domain-Endpoints und /smtp/default. Die veralteten MCP-Werkzeuge get_smtp_config / update_smtp_config sind aus demselben Grund nicht mehr empfohlen.

White-Label-Branding, Kunden und Teamzugriff

Branding wird mit branding:read / branding:write pro Domain konfiguriert. Eine Domain verwendet eine eigene Marke (mode=custom), erbt den Kontostandard (mode=inherit) oder ist deaktiviert. Eine aktive White-Label-Testversion oder ein kostenpflichtiges Add-on ist erforderlich. Nach der Kündigung behält der Eigentümer während des angezeigten Kulanzzeitraums schreibgeschützten Wiederherstellungszugriff. Lesen Sie die dns_records der Domain und veröffentlichen Sie genau diese zurückgegebenen Einträge. Leiten Sie keine Hostnamen oder CNAME-Ziele aus einem Beispiel ab.

PATCH führt teilweise zusammen, ausgelassene Felder bleiben also erhalten. Wenn Branding derzeit deaktiviert ist, übergeben Sie mode, um es wieder einzuschalten. Eine benutzerdefinierte sender_email muss zu einer Domain mit geprüftem DKIM-Schlüssel gehören. mail_zone_enabled stellt Mail-Apps und DAV-Synchronisierung unter der eigenen Domain der Marke bereit. Die Zone gehört zur Marke und nicht zu einer einzelnen Domain und benötigt daher mode=custom oder scope=account_default; eine inherit-Domain gibt 422 inherited_brand zurück. Lesen Sie mail_zone.dns_status, mail_zone.client_hosts_status, mail_zone.records, mail_zone.dav_url und mail_zone.dav_ready, um die Bereitstellung zu verfolgen und nur eine bereite DAV-Adresse zu verwenden. Den vollständigen Agentenablauf finden Sie im API- und MCP-Leitfaden für White-Label-Branding.

Die White-Label-Oberfläche auf Kontoebene ergänzt 18 Routen unter /api/v1/white-label: Status und Einrichtungsfortschritt, einen aktuellen Zugriffskatalog, Mitgliederliste und Lebenszyklusaktionen, Speicherlimits für Kunden, Kontoaktivität sowie den Aktions- und Anmeldeverlauf pro Mitglied. Sie verwendet members:read, members:write und activity:read. Der Zugriff ist immer die Schnittmenge aus Kontoberechtigung, aktueller Mitgliedschaft der Person, Anmeldedatenfreigabe und einer möglichen Domainbeschränkung. Die Routentabelle und Zustandsübergänge finden Sie unter White-Label-Teams mit API und MCP verwalten.

Die OpenAPI-Spezifikation steht unter /api/openapi.json zum Import in Postman, Insomnia oder Codegeneratoren bereit.

Schnelle Lösungen

• 401 „unauthenticated“: Prüfen Sie, ob der Header Authorization: Bearer <token> vorhanden ist und das Token nicht widerrufen oder abgelaufen ist.
• 403 „plan_api_disabled“: Der angeforderte Bereich ist in Ihrem Tarif nicht enthalten. Nano umfasst Email Verifier (und Drive, wenn Sie das Drive-Storage-Add-on erworben haben). Wechseln Sie für den Rest der API zu Starter oder höher.
• 403 „token_scope_blocked_by_plan“: Ihr Token enthält Bereiche, die in Ihrem aktuellen Tarif nicht verfügbar sind. Widerrufen Sie es und erstellen Sie ein neues mit zulässigen Bereichen.
• 403 „scope_blocked_by_entitlement“: Eine gespeicherte White-Label-Freigabe ist nicht verfügbar, weil das Add-on inaktiv ist oder während der Kulanzzeit geschrieben werden soll. Reaktivieren Sie White Label und stellen oder autorisieren Sie die Anmeldedaten anschließend neu.
• 403 „scope_blocked_by_membership“: Die aktuelle Mitgliederrolle ist enger als die angeforderte Aktion. Bitten Sie den Eigentümer, sie zu ändern; eine erneute Autorisierung allein kann die Mitgliedschaft nicht erweitern.
• 422 „missing_idempotency_key“: Fügen Sie dem in der Endpoint-Referenz genannten Schreibvorgang einen Idempotency-Key-Header hinzu.
• 403 „mailbox_sending_paused“: Das Senden aus diesem Postfach wurde gestoppt, weil ausgehende E-Mails nicht mehr nach ihrem Eigentümer aussahen, meist weil ein Passwort in falsche Hände geraten ist. Lesen, Auflisten und alle anderen Endpoints funktionieren weiterhin; nur das Senden wird abgewiesen, und Wiederholungen beheben die Sperre nicht. Das Postfachpasswort muss geändert werden, danach schaltet der Support das Senden wieder ein. Siehe Warum kann ich keine E-Mails senden?.
• 403 „account_sending_on_hold“: Das Senden aus dem gesamten Konto ist angehalten, während TrekMail es überprüft. Der Empfang und alle anderen Endpoints funktionieren weiterhin; Wiederholungen ändern daran nichts. Wenden Sie sich an den Support, damit die Prüfung abgeschlossen wird.
• 403 „mailbox_send_disabled“: Das Senden ist nur für dieses eine Postfach abgeschaltet. Lesen und alle anderen Endpoints funktionieren weiterhin; Wiederholungen ändern daran nichts. Meist liegt das Postfach außerhalb Ihres Tarifs: Seine Domain übersteigt die Zahl der Domains, die der Tarif enthält, oder das Postfach übersteigt die Postfächer pro Domain des Tarifs (die ältesten Domains und Postfächer senden weiter). Das passiert nach einem Wechsel in einen kleineren Tarif. Es kann auch ein Postfach sein, das angelegt wurde, bevor die Einrichtung seiner Domain abgeschlossen war. Ein Upgrade schaltet das Senden sofort wieder ein; nachdem Sie die überzähligen Domains oder Postfächer entfernt haben oder sobald die Einrichtung der Domain abgeschlossen ist, funktioniert es innerhalb eines Tages wieder. Trifft nichts davon zu, wenden Sie sich an den Support.
• 403 „account_email_unverified“: Das Senden ist gesperrt, bis der Kontoinhaber seine Anmeldeadresse bestätigt. Konten, die am oder nach dem 19. Februar 2026 registriert wurden, haben dafür 7 Tage Zeit, und dieselben 7 Tage beginnen erneut, wenn eine bestätigte Anmeldeadresse durch eine neue ersetzt wird. Lesen und alle anderen Endpoints funktionieren weiterhin; Wiederholungen ändern daran nichts. Öffnen Sie den Link in der Bestätigungsmail oder klicken Sie im Banner des Dashboards auf Bestätigungsmail erneut senden; das Senden funktioniert wieder, sobald die Adresse bestätigt ist. Siehe Warum kann ich keine E-Mails senden?.
• 429 Ratenlimit erreicht: Warten Sie die im Retry-After-Header angegebene Dauer ab, bevor Sie es erneut versuchen. Auch beim täglichen API-Limit pro Postfach lautet die Antwort rate_limited, allerdings mit retryable auf false, dimension auf api_mailbox_daily und einer Zeit in resets_at: Ein früherer Versuch hilft dort nicht, warten Sie also bis zu diesem Zeitpunkt.
• 429 „sending_limit_exceeded“: Ein Sendekontingent ist aufgebraucht. dimension nennt, welches, und resets_at, wann es sich erneuert. Ein früherer Versuch kann nicht gelingen, deshalb ist retryable auf false gesetzt. GET /api/v1/messages/sending-limits gibt in remaining_today an, an wie viele Empfänger das Postfach heute noch senden kann. Ist das niedrigste Kontingent die tägliche Gesamtsumme des Kontos, ist limit_today gleich null und remaining_today ebenfalls, bis diese Summe aufgebraucht ist (dann 0); ein Ops-Token liest die Summe mit GET /api/v1/sending-limits. Ist dimension gleich recipients_per_message, teilen Sie die Nachricht stattdessen in kleinere Nachrichten auf. In den ersten 24 Stunden nach der ersten Zahlung des Kontos gehört new_payer zu den Gründen, und GET /api/v1/sending-limits nennt in full_limits_at den Zeitpunkt, ab dem die vollen Limits des Tarifs gelten. Siehe Sendelimits pro Tarif.

E-Mails senden: Body, Header und Zustellbarkeit

POST /api/v1/messages/send akzeptiert die Anfrageform {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.

• body.text und body.html sind beide optional, aber mindestens eines ist erforderlich. Wenn Sie nur body.text angeben, erzeugen wir automatisch eine HTML-Alternative mit <p>-Absätzen (Leerzeilen trennen Absätze, einzelne Zeilenumbrüche werden zu <br>), damit die Nachricht in jedem modernen Client als normale E-Mail dargestellt wird. Für Festbreitenschrift senden Sie das Literal <pre>...</pre> in body.html.
• headers ist ein optionales Objekt mit benutzerdefinierten ausgehenden Headern. Zulässig sind List-Unsubscribe, List-Unsubscribe-Post, Reply-To und beliebige benutzerdefinierte Tracking-Header X-*. Andere Namen (From, Subject, Message-Id, Authentication-Results usw.) werden von der Plattform verwaltet und mit 422 abgelehnt. Werte mit CR/LF werden ebenfalls abgelehnt, um Header-Injektion zu verhindern. Werte sind gemäß RFC 2822 auf 998 Zeichen begrenzt.
• Informationen für Massenversand und Automatisierung finden Sie im Abschnitt Zustellbarkeitsheader für Massenversender, einschließlich der Einrichtung von List-Unsubscribe und des kontoweiten Schalters auto_list_unsubscribe.

Eine 202-Antwort bedeutet, dass die Nachricht angenommen, aber noch nicht gesendet wurde. Die Sendekontingente werden erneut kontrolliert, wenn die Nachricht die Warteschlange verlässt. Prüfen Sie das Ergebnis daher mit GET /api/v1/messages/deliveries/{request_id} und der request_id aus der 202-Antwort. Jedes Nachrichten-Token desselben Postfachs kann es abfragen, nicht nur das Token, das die Nachricht gesendet hat; eine unbekannte request_id liefert 404. Hat ein Limit die Nachricht gestoppt, ist status gleich failed, und failure nennt das Limit (dimension) und wann es sich erneuert (resets_at). Eine fehlgeschlagene Sendung kann später mit demselben Inhalt erneut gesendet werden. Wenn Sie eine eigene X-Request-Id übergeben, verwenden Sie dafür eine neue, denn die alte liefert nur die ursprüngliche Sendung zurück. Eine geplante Nachricht, die zu ihrem Sendezeitpunkt ein Limit erreicht, wird als limit_reached zurückgehalten und 7 Tage aufbewahrt: Listen Sie solche Nachrichten mit GET /api/v1/messages/scheduled?status=limit_reached auf, senden Sie eine davon später, indem Sie ihr mit PATCH /api/v1/messages/scheduled/{id} ein neues scheduled_for geben, oder löschen Sie sie mit DELETE.