Kimlik Doğrulama

MailLand iki kimlik doğrulama yöntemini destekler: kullanıcı oturumları için Bearer token (JWT) ve sunucular arası entegrasyon için API anahtarları. Tüm API istekleri, Authorization başlığı aracılığıyla kimlik doğrulaması gerektirir.

Kimlik Doğrulama YöntemleriBölüm bağlantısını kopyala

KayıtBölüm bağlantısını kopyala

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

Bilinmeyen alanlar (yanlışlıkla gönderilen bir tenantName gibi) sessizce yok sayılır.

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

Yanıt durumu 201'dir.

Kayıttan sonra, giriş yapmadan önce e-posta adresini doğrulayın.

E-posta DoğrulamaBölüm bağlantısını kopyala

Kayıt sırasında 6 haneli bir kod e-postayla gönderilir. { "ticket": "<verificationTicket>", "code": "123456" } gövdesiyle POST /v1/auth/verify-email-ticket çağrılır; başarılı olursa giriş token yanıtı döner.

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

Doğrulama e-postasını yeniden gönderin: { "ticket": "..." } gövdesiyle POST /v1/auth/resend-verification-ticket çağrılır. Bu istek hız sınırlıdır ve yeni bir ticket döner.

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

GirişBölüm bağlantısını kopyala

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

YanıtBölüm bağlantısını kopyala

Giriş yanıtı, hesap durumuna göre değişir:

Başarılı giriş:

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

Yanıtta bir user nesnesi ve role alanı yoktur. Doğrulanmamış bir hesap bir hata değil, requiresEmailVerification: true ve bir verificationTicket ile 200 alır.

İki faktörlü kimlik doğrulama gerekli:

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

requiresTwoFactor değeri true olduğunda, token almadan önce 2FA doğrulamasını tamamlayın.

Token YenilemeBölüm bağlantısını kopyala

Erişim tokenları 60 dakika sonra sona erer. Yeni bir erişim tokenı almak için yenileme tokenını kullanın:

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

Yanıt, yukarıdaki giriş yanıtıyla aynı biçimdedir (tam AuthResponse), yalnızca bu üç alan değil:

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

ÇıkışBölüm bağlantısını kopyala

Mevcut oturumu geçersiz kılın:

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

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

Tüm aktif oturumları iptal edin:

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

Şifre YönetimiBölüm bağlantısını kopyala

Şifremi UnuttumBölüm bağlantısını kopyala

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

Süresi sınırlı token içeren bir şifre sıfırlama e-postası gönderir.

Şifre SıfırlamaBölüm bağlantısını kopyala

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

confirmPassword zorunludur ve newPassword ile eşleşmelidir; kayıt sırasındaki aynı karmaşıklık kuralları geçerlidir.

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

Sıfırlama Tokenını DoğrulamaBölüm bağlantısını kopyala

Sıfırlama formunu göstermeden önce sıfırlama tokenının hâlâ geçerli olup olmadığını kontrol edin:

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

Şifre DeğiştirmeBölüm bağlantısını kopyala

Mevcut kimliği doğrulanmış kullanıcının şifresini değiştirin:

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

Profil YönetimiBölüm bağlantısını kopyala

Mevcut Kullanıcıyı GetirBölüm bağlantısını kopyala

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

Bu yanıtta firstName, lastName, phone, tenantId, role veya twoFactorEnabled alanı yoktur.

Profili GüncelleBölüm bağlantısını kopyala

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

fullName zorunludur; companyName gönderilmezse temizlenir. Bu güncelleme kullanıcının satırıyla yalnızca kullanıcı kimliğine göre eşleşir, bu nedenle hesabın oluşturulduğu çalışma alanıyla sınırlı kalmadan kullanıcının aktif olduğu her çalışma alanından çalışır.

{
  "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 YükleBölüm bağlantısını kopyala

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

Avatar resim dosyasıyla birlikte multipart/form-data isteği gönderin. Desteklenen formatlar: JPEG, PNG, GIF veya WebP (uzantı değil, dosya içeriği kontrol edilir). Maksimum boyut: 1 MB.

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

Sosyal Kimlik DoğrulamaBölüm bağlantısını kopyala

MailLand, Google, GitHub ve Microsoft aracılığıyla sosyal girişi destekler:

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

Hesabı SilBölüm bağlantısını kopyala

Silme işlemi kullanıcı hesabı bazında değil, çalışma alanı bazında yapılır ve yalnızca bir çalışma alanı Owner'ı bunu başlatabilir. Hemen silmek yerine bir bekleme süresinin ardından silmeyi planlar:

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 7-90 arası bir değer kabul eder (varsayılan 30); bu aralığın dışındaki değerler reddedilmez, sınıra çekilir. Planlanan silme, bekleme süresi bitmeden önce herhangi bir zamanda iptal edilebilir:

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

Hata YanıtlarıBölüm bağlantısını kopyala

Doğrulanmamış bir e-posta hata döndürmez: giriş, requiresEmailVerification: true ve yeni bir verificationTicket ile 200 yanıtı verir.

Sonraki AdımlarBölüm bağlantısını kopyala

• İki Faktörlü Kimlik Doğrulama: hesabınıza 2FA ekleyin
• Takım Yönetimi: takım üyelerini davet edin
• Çalışma Alanları: birden fazla çalışma alanını yönetin
• API Anahtarları: sunucular arası erişim için API anahtarları oluşturun