MailLandDocs

Account Setup

Create your Mail.Land account, verify your email, and set up your first workspace

Create an Account

Register

Send a POST request to the registration endpoint or sign up through the dashboard at app.mail.land.

register.sh
curl -X POST https://api.mail.land/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password",
    "fullName": "Jane Doe",
    "companyName": "Acme Inc"
  }'

The fullName and companyName fields are optional but recommended. Your password must be 8 to 128 characters and contain an uppercase letter, a lowercase letter, a digit and a special character.

Verify your email

After registration, MailLand sends a verification code to your email. You'll receive a verificationTicket in the registration response:

Registration Response
{
  "requiresEmailVerification": true,
  "verificationTicket": "vt_abc123...",
  "maskedEmail": "y***@company.com"
}

Submit the code from your inbox:

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

If you didn't receive the code, request a new one via POST /v1/auth/resend-verification-ticket. There's a cooldown between resends, and a daily limit.

Sign in

After verification, sign in to get your access token:

login.sh
curl -X POST https://api.mail.land/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }'
Login Response
{
  "userId": "abc123def456",
  "email": "[email protected]",
  "fullName": "Jane Doe",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_abc123...",
  "expiresAt": "2026-02-17T11:30:00Z",
  "tenantCount": 1,
  "activeTenantId": "k3m9x2p7qw4rtz",
  "activeTenantName": "Acme Inc"
}

If you have two-factor authentication enabled, the response will include requiresTwoFactor: true and a twoFactorChallengeId instead of tokens.

Workspaces (Tenants)

Every MailLand account has at least one workspace (also called a tenant). Workspaces isolate your domains, credentials, templates, and sending data.

When to use multiple workspaces

  • Separate environments: production vs staging
  • Separate products: if you run multiple apps that send email
  • Separate clients: if you're an agency managing email for multiple customers

Switch workspaces

Use your access token to switch between workspaces. tenantId is the workspace's public string id, get ids from GET /v1/account/tenants:

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

This returns a new access token scoped to the selected workspace.

Two-Factor Authentication

MailLand supports TOTP-based two-factor authentication (compatible with Google Authenticator, Authy, 1Password, etc).

Enable 2FA

  1. Call POST /v1/auth/2fa/setup to get a TOTP secret and QR code URI
  2. Scan the QR code with your authenticator app
  3. Confirm setup by submitting a valid code via POST /v1/auth/2fa/enable

Once enabled, every login will require a 6-digit code from your authenticator app.

Save your recovery codes in a secure location. If you lose access to your authenticator app, recovery codes are the only way to regain access.

API Authentication

MailLand uses two authentication methods:

Bearer tokens (Dashboard & Account management)

For account operations (login, workspace management, settings), use JWT bearer tokens in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Tokens expire after the duration specified in expiresAt. Use POST /v1/auth/refresh-token to get a new token before expiration.

API Keys (Email operations)

For email sending, domain management, and all operational API calls, use API keys in the X-API-Key header:

X-API-Key: ml_pet_Ab3Kx9mN2pQ7rT4wL8yD...

API keys are scoped to a workspace and don't expire unless you set an expiration date. See API Keys for details on creating and managing credentials.

Next Steps

On this page

Create an AccountRegisterVerify your emailSign inWorkspaces (Tenants)When to use multiple workspacesSwitch workspacesTwo-Factor AuthenticationEnable 2FAAPI AuthenticationBearer tokens (Dashboard & Account management)API Keys (Email operations)Next Steps