Authentifizierung

MailLand unterstützt zwei Authentifizierungsmethoden: Bearer-Tokens (JWT) für Benutzersitzungen und API-Schlüssel für die Server-zu-Server-Integration. Alle API-Anfragen erfordern eine Authentifizierung über den Authorization-Header.

AuthentifizierungsmethodenLink zum Abschnitt kopieren

RegistrierungLink zum Abschnitt kopieren

POST https://api.mail.land/v1/auth/register

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd!",
  "fullName": "John Doe",
  "companyName": "My Company"
}

curl -X POST https://api.mail.land/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!",
    "fullName": "John Doe",
    "companyName": "My Company"
  }'

Unbekannte Felder (z. B. ein versehentlich gesendetes tenantName) werden stillschweigend verworfen.

{
  "requiresEmailVerification": true,
  "verificationTicket": "vt_abc123...",
  "maskedEmail": "u***@example.com"
}

Der Antwortstatus ist 201.

Nach der Registrierung muss die E-Mail-Adresse verifiziert werden, bevor Sie sich anmelden können.

E-Mail-VerifizierungLink zum Abschnitt kopieren

Bei der Registrierung wird ein 6-stelliger Code per E-Mail versendet. Rufen Sie POST /v1/auth/verify-email-ticket mit { "ticket": "<verificationTicket>", "code": "123456" } auf; bei Erfolg wird die Login-Token-Antwort zurückgegeben.

POST https://api.mail.land/v1/auth/verify-email-ticket

{
  "ticket": "vt_abc123...",
  "code": "123456"
}

curl -X POST https://api.mail.land/v1/auth/verify-email-ticket \
  -H "Content-Type: application/json" \
  -d '{"ticket": "vt_abc123...", "code": "123456"}'

Senden Sie die Verifizierungs-E-Mail erneut: Rufen Sie POST /v1/auth/resend-verification-ticket mit { "ticket": "..." } auf. Die Anfrage ist ratenbegrenzt und liefert ein neues Ticket zurück.

POST https://api.mail.land/v1/auth/resend-verification-ticket

{
  "ticket": "vt_abc123..."
}

curl -X POST https://api.mail.land/v1/auth/resend-verification-ticket \
  -H "Content-Type: application/json" \
  -d '{"ticket": "vt_abc123..."}'

AnmeldungLink zum Abschnitt kopieren

POST https://api.mail.land/v1/auth/login

{
  "email": "[email protected]",
  "password": "SecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecureP@ssw0rd!"
  }'

AntwortLink zum Abschnitt kopieren

Die Anmeldeantwort variiert je nach Kontozustand:

Erfolgreiche Anmeldung:

{
  "userId": "v4j2x7n1m9k5p3",
  "email": "[email protected]",
  "fullName": "John Doe",
  "avatarUrl": null,
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_a1b2c3d4e5...",
  "expiresAt": "2026-09-25T13:00:00Z",
  "requiresTwoFactor": false,
  "twoFactorChallengeId": null,
  "tenantCount": 1,
  "activeTenantId": "k3m9x2p7qw4rtz",
  "activeTenantName": "My Company",
  "requiresEmailVerification": false,
  "verificationTicket": null,
  "maskedEmail": null
}

Es gibt kein user-Objekt und keine role in der Antwort. Ein unverifiziertes Konto erhält 200 mit requiresEmailVerification: true und einem verificationTicket, keinen Fehler.

Zwei-Faktor-Authentifizierung erforderlich:

{
  "accessToken": null,
  "refreshToken": null,
  "requiresTwoFactor": true,
  "twoFactorChallengeId": "2fa_challenge_abc123"
}

Wenn requiresTwoFactor den Wert true hat, schließen Sie die 2FA-Verifizierung ab, bevor Sie Tokens erhalten.

Token aktualisierenLink zum Abschnitt kopieren

Zugriffstoken laufen nach 60 Minuten ab. Verwenden Sie das Aktualisierungstoken, um ein neues Zugriffstoken zu erhalten:

POST https://api.mail.land/v1/auth/refresh-token

{
  "refreshToken": "rt_a1b2c3d4e5..."
}

curl -X POST https://api.mail.land/v1/auth/refresh-token \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "rt_a1b2c3d4e5..."}'

Die Antwort hat dieselbe Form wie die obige Login-Antwort (die vollständige AuthResponse), nicht nur diese drei Felder:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-09-25T14:00:00Z"
}

AbmeldungLink zum Abschnitt kopieren

Invalidieren Sie die aktuelle Sitzung:

POST https://api.mail.land/v1/auth/logout

curl -X POST https://api.mail.land/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Widerrufen Sie alle aktiven Sitzungen:

POST https://api.mail.land/v1/auth/revoke-all-tokens

curl -X POST https://api.mail.land/v1/auth/revoke-all-tokens \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

PasswortverwaltungLink zum Abschnitt kopieren

Passwort vergessenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/auth/forgot-password

{
  "email": "[email protected]"
}

curl -X POST https://api.mail.land/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

Sendet eine Passwortzurücksetzungs-E-Mail mit einem zeitlich begrenzten Token.

Passwort zurücksetzenLink zum Abschnitt kopieren

POST https://api.mail.land/v1/auth/reset-password

confirmPassword ist erforderlich und muss mit newPassword übereinstimmen; es gelten dieselben Komplexitätsregeln wie bei der Registrierung.

{
  "token": "reset-token-from-email",
  "newPassword": "NewSecureP@ssw0rd!",
  "confirmPassword": "NewSecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-from-email",
    "newPassword": "NewSecureP@ssw0rd!",
    "confirmPassword": "NewSecureP@ssw0rd!"
  }'

Zurücksetzungstoken validierenLink zum Abschnitt kopieren

Prüfen Sie, ob ein Zurücksetzungstoken noch gültig ist, bevor Sie das Zurücksetzungsformular anzeigen:

GET https://api.mail.land/v1/auth/validate-reset-token?token=reset-token-from-email

curl "https://api.mail.land/v1/auth/validate-reset-token?token=reset-token-from-email"

{
  "valid": true,
  "message": "Token is valid"
}

Passwort ändernLink zum Abschnitt kopieren

Ändern Sie das Passwort des aktuell authentifizierten Benutzers:

POST https://api.mail.land/v1/auth/change-password

{
  "currentPassword": "OldP@ssw0rd!",
  "newPassword": "NewSecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/v1/auth/change-password \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "currentPassword": "OldP@ssw0rd!",
    "newPassword": "NewSecureP@ssw0rd!"
  }'

ProfilverwaltungLink zum Abschnitt kopieren

Aktuellen Benutzer abrufenLink zum Abschnitt kopieren

GET https://api.mail.land/v1/auth/me

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

{
  "id": "v4j2x7n1m9k5p3",
  "email": "[email protected]",
  "fullName": "John Doe",
  "companyName": "Acme",
  "avatarUrl": "https://cdn.mail.land/avatars/usr_a1b2c3d4e5.jpg",
  "status": "Active",
  "createdAt": "2026-01-15T08:00:00Z",
  "subscription": {
    "planName": "Pro",
    "monthlyEmailLimit": 50000,
    "rateLimitPerSecond": 10,
    "startDate": "2026-01-15T08:00:00Z",
    "endDate": "2026-10-15T08:00:00Z",
    "status": "Active"
  },
  "stats": {
    "credentialCount": 3,
    "domainCount": 2
  }
}

Es gibt kein firstName-, lastName-, phone-, tenantId-, role- oder twoFactorEnabled-Feld in dieser Antwort.

Profil aktualisierenLink zum Abschnitt kopieren

PUT https://api.mail.land/v1/auth/profile

fullName ist erforderlich; wird companyName weggelassen, wird es gelöscht. Diese Aktualisierung trifft die Zeile des Benutzers allein anhand der Benutzer-ID, funktioniert also aus jedem Arbeitsbereich, in dem der Benutzer aktiv ist, nicht nur aus dem, in dem das Konto erstellt wurde.

{
  "fullName": "Jane Smith",
  "companyName": "Acme"
}

curl -X PUT https://api.mail.land/v1/auth/profile \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jane Smith",
    "companyName": "Acme"
  }'

Avatar hochladenLink zum Abschnitt kopieren

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

Senden Sie eine multipart/form-data-Anfrage mit der Avatar-Bilddatei. Unterstützte Formate: JPEG, PNG, GIF oder WebP (der Inhalt wird geprüft, nicht nur die Dateiendung). Maximale Größe: 1 MB.

curl -X POST https://api.mail.land/v1/account/avatar \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -F "file=@/path/to/avatar.jpg"

Soziale AuthentifizierungLink zum Abschnitt kopieren

MailLand unterstützt die Anmeldung über Google, GitHub und Microsoft:

GET https://api.mail.land/auth/social/{provider}

curl https://api.mail.land/auth/social/google

GET https://api.mail.land/auth/social/{provider}/callback?code=...

curl "https://api.mail.land/auth/social/google/callback?code=authorization-code-from-provider"

POST https://api.mail.land/v1/auth/social/exchange

{
  "code": "one-time-code-from-callback-redirect"
}

curl -X POST https://api.mail.land/v1/auth/social/exchange \
  -H "Content-Type: application/json" \
  -d '{"code": "one-time-code-from-callback-redirect"}'

Konto löschenLink zum Abschnitt kopieren

Die Löschung erfolgt pro Arbeitsbereich, nicht pro Benutzerkonto, und nur ein Owner des Arbeitsbereichs kann sie starten. Sie plant die Löschung nach einer Karenzzeit, statt sofort zu löschen:

POST https://api.mail.land/v1/account/lifecycle/schedule-deletion

{
  "gracePeriodDays": 30
}

curl -X POST https://api.mail.land/v1/account/lifecycle/schedule-deletion \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"gracePeriodDays": 30}'

gracePeriodDays akzeptiert 7–90 (Standard 30); Werte außerhalb dieses Bereichs werden begrenzt, nicht abgelehnt. Die geplante Löschung kann jederzeit vor Ablauf der Karenzzeit storniert werden:

POST https://api.mail.land/v1/account/lifecycle/cancel-deletion

FehlerantwortenLink zum Abschnitt kopieren

Eine nicht verifizierte E-Mail-Adresse führt zu keinem Fehler: Der Login antwortet mit 200, requiresEmailVerification: true und einem neuen verificationTicket.

Nächste SchritteLink zum Abschnitt kopieren

• Zwei-Faktor-Authentifizierung: 2FA zu Ihrem Konto hinzufügen
• Teamverwaltung: Teammitglieder einladen
• Arbeitsbereiche: mehrere Arbeitsbereiche verwalten
• API-Schlüssel: API-Schlüssel für den Server-zu-Server-Zugriff erstellen