المصادقة

تدعم MailLand طريقتين للمصادقة: رموز Bearer (JWT) لجلسات المستخدمين ومفاتيح API للتكامل بين الخوادم. تتطلب جميع طلبات API المصادقة عبر ترويسة Authorization.

طرق المصادقةنسخ رابط القسم

التسجيلنسخ رابط القسم

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

الحقول غير المعروفة (مثل tenantName إذا أُرسل بالخطأ) يتم تجاهلها بصمت.

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

رمز حالة الاستجابة هو 201.

بعد التسجيل، قم بالتحقق من عنوان البريد الإلكتروني قبل تسجيل الدخول.

التحقق من البريد الإلكترونينسخ رابط القسم

يرسل التسجيل بريدًا إلكترونيًا يحتوي على رمز من 6 أرقام. استدعِ POST /v1/auth/verify-email-ticket مع { "ticket": "<verificationTicket>", "code": "123456" }؛ عند النجاح تُعاد استجابة رموز تسجيل الدخول.

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

إعادة إرسال بريد التحقق: استدعِ POST /v1/auth/resend-verification-ticket مع { "ticket": "..." }. هذا الطلب محكوم بحدّ معدل ويعيد بطاقة (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..."}'

تسجيل الدخولنسخ رابط القسم

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

الاستجابةنسخ رابط القسم

تختلف استجابة تسجيل الدخول بناءً على حالة الحساب:

تسجيل دخول ناجح:

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

لا يوجد كائن user ولا حقل role في الاستجابة. الحساب غير المُتحقَّق منه يحصل على 200 مع requiresEmailVerification: true وverificationTicket، وليس خطأً.

المصادقة الثنائية مطلوبة:

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

عندما يكون requiresTwoFactor يساوي true، أكمل التحقق بخطوتين قبل استلام الرموز.

تحديث الرمزنسخ رابط القسم

تنتهي صلاحية رموز الوصول بعد 60 دقيقة. استخدم رمز التحديث للحصول على رمز وصول جديد:

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

الاستجابة لها نفس شكل استجابة تسجيل الدخول أعلاه (كائن AuthResponse الكامل)، وليس فقط هذه الحقول الثلاثة:

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

تسجيل الخروجنسخ رابط القسم

إلغاء الجلسة الحالية:

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

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

إلغاء جميع الجلسات النشطة:

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

إدارة كلمة المرورنسخ رابط القسم

نسيت كلمة المرورنسخ رابط القسم

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

يرسل بريداً إلكترونياً لإعادة تعيين كلمة المرور يحتوي على رمز محدود الصلاحية.

إعادة تعيين كلمة المرورنسخ رابط القسم

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

confirmPassword مطلوب ويجب أن يطابق newPassword؛ تنطبق نفس قواعد التعقيد المستخدمة عند التسجيل.

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

التحقق من صحة رمز الإعادةنسخ رابط القسم

تحقق مما إذا كان رمز الإعادة لا يزال صالحاً قبل عرض نموذج الإعادة:

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

تغيير كلمة المرورنسخ رابط القسم

تغيير كلمة المرور للمستخدم المصادق عليه حالياً:

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

إدارة الملف الشخصينسخ رابط القسم

الحصول على المستخدم الحالينسخ رابط القسم

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

لا يوجد حقل firstName أو lastName أو phone أو tenantId أو role أو twoFactorEnabled في هذه الاستجابة.

تحديث الملف الشخصينسخ رابط القسم

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

حقل fullName مطلوب؛ وعدم إرسال companyName يؤدي إلى مسحه. يطابق هذا التحديث صف المستخدم بمعرّف المستخدم وحده، لذا يعمل من أي مساحة عمل نشط فيها المستخدم، وليس فقط تلك التي أُنشئ فيها الحساب.

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

رفع الصورة الشخصيةنسخ رابط القسم

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

أرسل طلب multipart/form-data مع ملف صورة الملف الشخصي. الصيغ المدعومة: JPEG وPNG وGIF وWebP (يتم فحص محتوى الملف وليس الامتداد فقط). الحجم الأقصى: 1 ميغابايت.

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

المصادقة الاجتماعيةنسخ رابط القسم

تدعم MailLand تسجيل الدخول الاجتماعي عبر Google وGitHub و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"}'

حذف الحسابنسخ رابط القسم

الحذف يتم على مستوى مساحة العمل، وليس على مستوى حساب المستخدم، ولا يمكن أن يبدأه سوى مالك (Owner) مساحة العمل. تتم جدولة الحذف بعد فترة سماح بدلاً من الحذف الفوري:

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 (الافتراضي 30)؛ والقيم خارج هذا النطاق تُقيَّد إلى الحد الأقرب بدلاً من رفضها. يمكن إلغاء الحذف المجدول في أي وقت قبل انتهاء فترة السماح:

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

استجابات الخطأنسخ رابط القسم

البريد الإلكتروني غير المتحقَّق منه لا يُعيد خطأً: يستجيب تسجيل الدخول بـ 200 مع requiresEmailVerification: true وبطاقة (verificationTicket) جديدة.

الخطوات التاليةنسخ رابط القسم

• المصادقة الثنائية: إضافة المصادقة الثنائية إلى حسابك
• إدارة الفريق: دعوة أعضاء الفريق
• مساحات العمل: إدارة مساحات عمل متعددة
• مفاتيح API: إنشاء مفاتيح API للوصول بين الخوادم