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

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.

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 AI Agents & API → Audit Log 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.
• 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 AI Agents & API → Tokens → Create token 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 AI Agents & API auf Start tour, 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 AI Agents & API unter Quick Reference 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.

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 zusätzlich die Summe der Zuweisungen im Stapel und lehnen den gesamten Stapel mit 422 storage_pool_exceeded ab, wenn er die Kapazität überschreiten würde. 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.

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.

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 ist ein Team-Posteingang wie support@ oder sales@, den Mitglieder über ihr eigenes reguläres Postfachkonto in Webmail und bei aktiviertem nativen Zugriff als delegierten IMAP-Ordner öffnen. Es gibt kein gemeinsames Passwort oder separates Login. Der Zugriff ist einheitlich: Jedes Mitglied kann lesen, und ein einzelnes can_send-Flag legt fest, ob es als diese Adresse antworten kann (true) oder nur Lesezugriff hat (false). Es gibt keine Mitgliederrollen.

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.

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, effektive Send-As-Bereitschaft und Begründung, genaue Inbox-/Sent-/Archive-/Junk-Pfade sowie erlaubte Vorgänge. can_send ist die zugewiesene Berechtigung Can reply, 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.

Das Entfernen eines Mitglieds, die Änderung von 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.
• set_account_default: true entspricht dem Schalter Make this the account default im Dashboard (neue Domains beginnen auf dieser Route). apply_to_all: true entspricht der Schaltfläche Apply to all domains (einmaliges Umschalten aller Domains auf diese Route).

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.

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 13 Routen unter /api/v1/white-label: Status und Einrichtungsfortschritt, einen aktuellen Zugriffskatalog, Mitgliederliste und Lebenszyklusaktionen, 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?.
• 429 Ratenlimit erreicht: Warten Sie die im Retry-After-Header angegebene Dauer ab, bevor Sie es erneut versuchen.

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.