Authentication

MailLand supports two authentication methods: Bearer tokens (JWT) for user sessions and API keys for server-to-server integration. Dashboard sessions send Authorization: Bearer <token>; server-to-server calls send X-API-Key: <key>.

Authentication MethodsCopy Anchor Link

RegisterCopy Anchor Link

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"
  }'

Unknown fields (such as a tenantName sent by mistake) are dropped silently.

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

The response status is 201.

After registration, verify the email address before logging in.

Email VerificationCopy Anchor Link

Registration emails a 6-digit code. Call POST /v1/auth/verify-email-ticket with { "ticket": "<verificationTicket>", "code": "123456" }; on success it returns the login token response.

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"}'

Resend the verification email: POST /v1/auth/resend-verification-ticket with { "ticket": "..." }. It is rate-limited and returns a fresh ticket.

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..."}'

LoginCopy Anchor Link

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!"
  }'

ResponseCopy Anchor Link

The login response varies based on the account state:

Successful login:

{
  "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
}

There is no user object and no role in the response. An unverified account gets 200 with requiresEmailVerification: true and a verificationTicket, not an error.

Two-factor authentication required:

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

When requiresTwoFactor is true, complete the 2FA verification before receiving tokens.

Refresh TokenCopy Anchor Link

Access tokens expire after 60 minutes. Use the refresh token to obtain a new access token:

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..."}'

The response is the same shape as the login response above (the full AuthResponse), not just these three fields:

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

LogoutCopy Anchor Link

Invalidate the current session:

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

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

Revoke all active sessions:

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..."

Password ManagementCopy Anchor Link

Forgot PasswordCopy Anchor Link

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]"}'

Sends a password reset email with a time-limited token.

Reset PasswordCopy Anchor Link

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

confirmPassword is required and must match newPassword; the same complexity rules apply as at registration.

{
  "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!"
  }'

Validate Reset TokenCopy Anchor Link

Check if a reset token is still valid before showing the reset form:

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"
}

Change PasswordCopy Anchor Link

Change the password for the currently authenticated user:

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!"
  }'

Profile ManagementCopy Anchor Link

Get Current UserCopy Anchor Link

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
  }
}

There is no firstName, lastName, phone, tenantId, role or twoFactorEnabled field in this response.

Update ProfileCopy Anchor Link

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

fullName is required; omitting companyName clears it. The update matches the user's row by user id alone, so it works from any workspace the user is active in, not only the one the account was created in.

{
  "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"
  }'

Upload AvatarCopy Anchor Link

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

Send a multipart/form-data request with the avatar image file. Supported formats: JPEG, PNG, GIF or WebP (the content is sniffed, not just the extension). Maximum size: 1 MB.

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

Social AuthenticationCopy Anchor Link

MailLand supports social login via Google, GitHub, and 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"}'

Delete AccountCopy Anchor Link

Deletion is per workspace, not per user account, and only a workspace Owner can start it. It schedules deletion after a grace period rather than deleting immediately:

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 accepts 7–90 (default 30); values outside that range are clamped, not refused. Cancel the pending deletion any time before the grace period ends:

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

Error ResponsesCopy Anchor Link

An unverified email does not return an error: login responds 200 with requiresEmailVerification: true and a fresh verificationTicket.

Next StepsCopy Anchor Link

• Two-Factor Authentication: add 2FA to your account
• Team Management: invite team members
• Workspaces: manage multiple workspaces
• API Keys: create API keys for server-to-server access