مساحات العمل

مساحات العمل (المستأجرون) هي بيئات معزولة لعمليات البريد الإلكتروني الخاصة بك. تمتلك كل مساحة عمل نطاقاتها ومشتركيها ومفاتيح API وفوترتها الخاصة. يمكن لحساب مستخدم واحد أن ينتمي إلى مساحات عمل متعددة.

المساحات الفرعية تنظّم، والمستأجرون (tenants) يفصلوننسخ رابط القسم

المساحة الفرعية (/v1/account/workspaces) تنظّم الموارد داخل مستأجر (tenant) واحد فقط، وباستخدام الأدوار الحالية. وهي ليست حدًّا للفوترة أو قابلية التسليم أو الأمان. العناصر التالية تعود دائمًا إلى المستأجر:

• الفوترة: الخطة والاشتراك والفواتير
• قائمة الحظر (suppression)
• حدود الإرسال والحصص
• عناوين IP الخاصة بالإرسال وسمعة المرسل
• أمان مفاتيح API

إذا كنت تدير نشاطًا تجاريًا مستقلًا أو تخدم عميلًا منفصلًا، فأنشئ له مستأجرًا (tenant) منفصلًا بدلًا من مساحة فرعية. وإلا فسيشارك هذا العميل قائمة الحظر وحدود الإرسال والسمعة مع الجميع داخل المستأجر.

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

لكل مساحة عمل مستوى تحقق يحدد قدرات الإرسال:

عرض مساحات العملنسخ رابط القسم

الحصول على جميع مساحات العمل التي ينتمي إليها المستخدم الحالي:

GET https://api.mail.land/v1/account/tenants

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

[
  {
    "publicId": "k3m9x2p7qw4rtz",
    "name": "My Company",
    "role": "owner",
    "isActive": true,
    "status": "active"
  },
  {
    "publicId": "t2p9k4m7x1n6w3",
    "name": "Client Project",
    "role": "member",
    "isActive": true,
    "status": "active"
  }
]

الاستجابة هي مصفوفة مجردة، وليست { "tenants": [...] }. لا يوجد roleName أو verificationLevel أو verificationLevelName أو isCurrent أو createdAt هنا: isActive وstatus يحلان محل isCurrent، ويتم جلب مستوى التحقق بشكل منفصل (راجع الفوترة). id هو المعرّف الرقمي الداخلي للمستأجر؛ publicId هو القيمة التي يجب استخدامها في استدعاءات API وواجهات المستخدم (حقل id الرقمي يُعرض هنا فقط لأن الواجهة الحالية تُعيده: لا تبنِ منطق العميل حوله، لأنه في طور الإزالة من الاستجابات الموجهة للعميل).

إنشاء مساحة عملنسخ رابط القسم

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

{
  "name": "New Project",
  "description": "Optional workspace description"
}

curl -X POST https://api.mail.land/v1/account/tenants \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "New Project" }'

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

يُعيد 201 Created بنفس شكل استجابة تبديل مساحة العمل: رموز جديدة مخصصة لمساحة العمل الجديدة، بالإضافة إلى سجل مساحة العمل المتداخل تحت tenant:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-02-17T13:00:00Z",
  "tenant": {
    "publicId": "u6w1m8k3p5x9n2",
    "name": "New Project",
    "role": "owner",
    "isActive": true,
    "status": "active"
  }
}

يتم تعيين دور Owner للمستخدم المُنشئ تلقائياً. لا يوجد verificationLevel/verificationLevelName في هذه الاستجابة، راجع الفوترة لحالة التحقق/السياسة.

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

تبديل مساحة العمل النشطة لاستدعاءات API اللاحقة:

POST https://api.mail.land/v1/account/tenants/switch

{
  "tenantId": "t2p9k4m7x1n6w3",
  "refreshToken": "rt_a1b2c3d4e5..."
}

refreshToken اختياري: إذا لم يُرسل، تُستخدم القيمة من كوكي رمز التحديث بدلاً منه. tenantId هو publicId الخاص بمساحة العمل من قائمة مساحات العمل.

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

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "rt_new_token...",
  "expiresAt": "2026-09-25T15:00:00Z",
  "tenant": {
    "publicId": "t2p9k4m7x1n6w3",
    "name": "Client Project",
    "role": "member",
    "isActive": true,
    "status": "active"
  }
}

يؤدي تبديل مساحات العمل إلى إصدار رموز جديدة مخصصة لمساحة العمل المستهدفة. حقول tenant لها نفس شكل استجابة عرض مساحات العمل، متداخلة تحت tenant بدلاً من أن تكون مسطحة كـ tenantId/tenantName/role.

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

تحديث إعدادات مساحة العمل الحالية:

PUT https://api.mail.land/v1/account/tenants/current

{
  "name": "Updated Project Name",
  "description": "Optional workspace description"
}

name من 2 إلى 100 حرف؛ description اختياري، حتى 500 حرف.

curl -X PUT https://api.mail.land/v1/account/tenants/current \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Updated Project Name" }'

يمكن فقط لأصحاب الملكية (Owner) والمسؤولين (Admin) تحديث مساحة العمل. الأعضاء (Member) والمشاهدون (Viewer) ومفاتيح API تحصل على 403 INSUFFICIENT_PERMISSIONS مُصنَّف (مع الصلاحية المفقودة tenant.edit في details.permission).

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

تُرجع 200 OK:

{
  "publicId": "t2p9k4m7x1n6w3",
  "name": "Updated Project Name",
  "description": "Optional workspace description",
  "status": "Active",
  "createdAt": "2026-01-15T08:00:00Z"
}

سياق مساحة العملنسخ رابط القسم

جميع طلبات API محددة النطاق بمساحة العمل النشطة. يتم تحديد مساحة العمل من خلال خاصية مساحة العمل النشطة في الرمز. الموارد (النطاقات، المشتركون، الحملات، مفاتيح API) معزولة بين مساحات العمل.

عند استخدام مفاتيح API، يكون كل مفتاح محدداً لمساحة عمل واحدة. لا حاجة لتبديل مساحة العمل، يحدد المفتاح السياق تلقائياً.

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

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

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