Workspaces

Workspaces (Mandanten) sind isolierte Umgebungen für Ihre E-Mail-Operationen. Jeder Workspace hat eigene Domains, Abonnenten, API-Schlüssel und Abrechnung. Ein einzelnes Benutzerkonto kann zu mehreren Workspaces gehören.

Sub-Workspaces organisieren, Tenants trennenLink zum Abschnitt kopieren

Ein Sub-Workspace (/v1/account/workspaces) organisiert Ressourcen nur innerhalb eines Tenants und nutzt dafür die vorhandenen Rollen. Er ist keine Grenze für Abrechnung, Zustellbarkeit oder Sicherheit. Folgendes gehört immer zum Tenant:

• Abrechnung: Tarif, Abonnement und Rechnungen
• Die Unterdrückungsliste (Suppression-Liste)
• Versandlimits und Kontingente
• Versand-IPs und Absenderreputation
• Sicherheit der API-Schlüssel

Wenn Sie ein eigenständiges Unternehmen betreiben oder einen separaten Kunden bedienen, legen Sie dafür einen eigenen Tenant an, keinen Sub-Workspace. Andernfalls teilt sich dieser Kunde Unterdrückungsliste, Versandlimits und Reputation mit allen anderen im Tenant.

VerifizierungsstufenLink zum Abschnitt kopieren

Jeder Workspace hat eine Verifizierungsstufe, die die Versandfähigkeiten bestimmt:

Workspaces auflistenLink zum Abschnitt kopieren

Alle Workspaces abrufen, denen der aktuelle Benutzer angehört:

GET https://api.mail.land/v1/account/tenants

curl https://api.mail.land/v1/account/tenants \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

[
  {
    "publicId": "k3m9x2p7qw4rtz",
    "name": "My Company",
    "role": "owner",
    "isActive": true,
    "status": "active"
  },
  {
    "publicId": "t2p9k4m7x1n6w3",
    "name": "Client Project",
    "role": "member",
    "isActive": true,
    "status": "active"
  }
]

Die Antwort ist ein reines Array, nicht { "tenants": [...] }. Es gibt hier kein roleName, verificationLevel, verificationLevelName, isCurrent oder createdAt, isActive und status ersetzen isCurrent, und die Verifizierungsstufe wird separat abgerufen (siehe Abrechnung). id ist die interne numerische Kennung des Tenants; publicId ist der Wert, der in API-Aufrufen und UIs verwendet werden sollte (das numerische id-Feld wird hier nur gezeigt, weil die aktuelle API es zurückgibt: bauen Sie keine Client-Logik darauf auf, da es aus client-seitigen Antworten entfernt werden soll).

Workspace erstellenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/account/tenants

{
  "name": "New Project",
  "description": "Optional workspace description"
}

curl -X POST https://api.mail.land/v1/account/tenants \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Project" }'

AntwortLink zum Abschnitt kopieren

Liefert 201 Created mit der gleichen Form wie die Antwort von Workspace wechseln: neue, auf den neuen Workspace beschränkte Tokens, plus den Workspace-Datensatz verschachtelt unter tenant:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-02-17T13:00:00Z",
  "tenant": {
    "publicId": "u6w1m8k3p5x9n2",
    "name": "New Project",
    "role": "owner",
    "isActive": true,
    "status": "active"
  }
}

Der erstellende Benutzer erhält automatisch die Rolle Owner. Es gibt kein verificationLevel/verificationLevelName in dieser Antwort, siehe Abrechnung für den Verifizierungs-/Policy-Status.

Workspace wechselnLink zum Abschnitt kopieren

Den aktiven Workspace für nachfolgende API-Aufrufe wechseln:

POST https://api.mail.land/v1/account/tenants/switch

{
  "tenantId": "t2p9k4m7x1n6w3",
  "refreshToken": "rt_a1b2c3d4e5..."
}

refreshToken ist optional: wenn weggelassen, wird stattdessen der Wert aus dem Refresh-Token-Cookie verwendet. tenantId ist die publicId des Workspaces aus Workspaces auflisten.

curl -X POST https://api.mail.land/v1/account/tenants/switch \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "t2p9k4m7x1n6w3" }'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-09-25T15:00:00Z",
  "tenant": {
    "publicId": "t2p9k4m7x1n6w3",
    "name": "Client Project",
    "role": "member",
    "isActive": true,
    "status": "active"
  }
}

Das Wechseln von Workspaces stellt neue Tokens aus, die auf den Ziel-Workspace beschränkt sind. Die Tenant-Felder haben die gleiche Form wie die Antwort von Workspaces auflisten, verschachtelt unter tenant statt flach als tenantId/tenantName/role.

Workspace aktualisierenLink zum Abschnitt kopieren

Einstellungen des aktuellen Workspaces aktualisieren:

PUT https://api.mail.land/v1/account/tenants/current

{
  "name": "Updated Project Name",
  "description": "Optional workspace description"
}

name ist 2–100 Zeichen lang; description ist optional, bis zu 500 Zeichen.

curl -X PUT https://api.mail.land/v1/account/tenants/current \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Updated Project Name" }'

Nur Owner und Admin können den Workspace aktualisieren. Member, Viewer und API-Schlüssel erhalten einen typisierten 403 INSUFFICIENT_PERMISSIONS (mit der fehlenden Berechtigung tenant.edit in details.permission).

AntwortLink zum Abschnitt kopieren

Gibt 200 OK zurück:

{
  "publicId": "t2p9k4m7x1n6w3",
  "name": "Updated Project Name",
  "description": "Optional workspace description",
  "status": "Active",
  "createdAt": "2026-01-15T08:00:00Z"
}

Workspace-KontextLink zum Abschnitt kopieren

Alle API-Anfragen sind auf den aktiven Workspace beschränkt. Der Workspace wird durch den Aktiver-Workspace-Claim des Tokens bestimmt. Ressourcen (Domains, Abonnenten, Kampagnen, API-Schlüssel) sind zwischen Workspaces isoliert.

Bei Verwendung von API-Schlüsseln ist jeder Schlüssel auf einen einzelnen Workspace beschränkt. Ein Workspace-Wechsel ist nicht erforderlich: der Schlüssel bestimmt den Kontext automatisch.

FehlerantwortenLink zum Abschnitt kopieren

Nächste SchritteLink zum Abschnitt kopieren

• Teamverwaltung: Mitglieder in Ihren Workspace einladen
• Abrechnung: Workspace-Abonnement verwalten
• Authentifizierung: Token- und Sitzungsverwaltung
• API-Schlüssel: Workspace-spezifische API-Schlüssel erstellen