إدارة الفريق

تعاون مع فريقك عن طريق دعوة الأعضاء إلى مساحة العمل. يُعيَّن لكل عضو دور يحدد صلاحياته.

الأدوارنسخ رابط القسم

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

عضو (Member) ليس للقراءة فقط ولا مستبعداً من إدارة المفاتيح، يمكنه إنشاء وتعديل معظم الأشياء. فقط حذف مفاتيح API والنطاقات والويب هوك، بالإضافة إلى إدارة الفريق والملكية، مقصور على Admin.

نظرة عامة على الفريقنسخ رابط القسم

الحصول على أعضاء الفريق الحاليين والدعوات المعلقة:

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

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

{
  "members": [
    {
      "publicId": "mbr_a1b2c3d4e5",
      "email": "[email protected]",
      "fullName": "John Doe",
      "role": "owner",
      "status": "active",
      "joinedAt": "2026-01-15T08:00:00Z",
      "invitedByEmail": null,
      "isCurrentUser": true
    },
    {
      "publicId": "mbr_f6g7h8i9j0",
      "email": "[email protected]",
      "fullName": "Jane Smith",
      "role": "admin",
      "status": "active",
      "joinedAt": "2026-01-20T10:00:00Z",
      "invitedByEmail": "[email protected]",
      "isCurrentUser": false
    }
  ],
  "pendingInvitations": [
    {
      "publicId": "inv_k1l2m3n4o5",
      "email": "[email protected]",
      "role": "member",
      "status": "pending",
      "createdAt": "2026-02-17T08:00:00Z",
      "expiresAt": "2026-02-24T08:00:00Z",
      "invitedByEmail": "[email protected]",
      "invitedByName": "John Doe",
      "isExpired": false
    }
  ],
  "totalMembers": 2,
  "totalPendingInvitations": 1,
  "maxMembers": 10
}

لا يوجد id أو userId أو firstName/lastName أو roleName/statusName أو invitedBy أو memberCount أو invitationCount في هذه الاستجابة: استخدم أسماء الحقول أعلاه بدلاً من ذلك. تعكس maxMembers خطة مساحة العمل: 10 في Free وPro، وغير محدودة في Max. المقعد هو عضو نشط (بما في ذلك المالك) أو دعوة معلقة لم تنتهِ صلاحيتها؛ الأعضاء الموقوفون والدعوات المنتهية أو الملغاة أو المقبولة لا تُحتسب. عند بلوغ الحد، تُعيد الدعوة أو القبول أو إعادة التفعيل أو أول تسجيل دخول عبر SSO الرمز 400 PLAN_LIMIT_REACHED. لا يؤدي خفض الخطة إلى إزالة أو إيقاف أي عضو، بل يمنع فقط قبول أعضاء جدد ما دامت مساحة العمل تتجاوز الحد الجديد.

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

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

تُعاد كسلاسل نصية بحروف صغيرة:

دعوة عضو في الفريقنسخ رابط القسم

POST https://api.mail.land/v1/account/team/invite

{
  "email": "[email protected]",
  "role": 2
}

curl -X POST https://api.mail.land/v1/account/team/invite \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "role": 2 }'

يتلقى المستخدم المدعو بريداً إلكترونياً يحتوي على رابط لقبول الدعوة. تنتهي صلاحية الدعوات بعد 7 أيام.

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

يوجد مسار عام واحد لقبول الدعوة: وهو غير مُرقّم بالإصدار (/v1 ليست جزءاً من المسار)، ومُعرَّف بواسطة رمز الدعوة (token) وليس بمعرّف (id):

POST https://api.mail.land/invitations/{token}/accept

بالنسبة إلى مستخدم MailLand حالي، سجّل الدخول بعنوان البريد الإلكتروني المدعو أولاً، ثم استدعِ هذا المسار بجسم فارغ أو بحد أدنى، لا حاجة إلى firstName/lastName/password. أما بالنسبة إلى مستخدم جديد تماماً، أرسل fullName وpassword في نفس الاستدعاء لإنشاء الحساب والقبول في خطوة واحدة.

{
  "fullName": "New Member",
  "password": "SecureP@ssw0rd!"
}

curl -X POST https://api.mail.land/invitations/invitation-token-from-email/accept \
  -H "Content-Type: application/json" \
  -d '{"fullName": "New Member", "password": "SecureP@ssw0rd!"}'

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

استرجع تفاصيل الدعوة قبل قبولها (عام، لا يتطلب مصادقة، ومُعرَّف بواسطة الرمز، وليس /v1):

GET https://api.mail.land/invitations/{token}

curl "https://api.mail.land/invitations/invitation-token-from-email"

{
  "tenantName": "My Company",
  "role": "member",
  "invitedByName": "John Doe",
  "expiresAt": "2026-02-24T08:00:00Z",
  "isExpired": false,
  "alreadyAccepted": false,
  "existingUserEmail": "[email protected]"
}

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

إلغاء دعوةنسخ رابط القسم

DELETE https://api.mail.land/v1/account/team/invitations/{id}

curl -X DELETE https://api.mail.land/v1/account/team/invitations/{id} \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تُعيد 204 No Content عند النجاح.

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

POST https://api.mail.land/v1/account/team/invitations/{id}/resend

curl -X POST https://api.mail.land/v1/account/team/invitations/{id}/resend \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

تؤدي إعادة إرسال الدعوة إلى إعادة تعيين مهلة انتهاء الصلاحية البالغة 7 أيام.

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

PATCH https://api.mail.land/v1/account/team/members/{id}/role

{
  "role": 1
}

curl -X PATCH https://api.mail.land/v1/account/team/members/{id}/role \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "role": 1 }'

يمكن لمسؤولي Admin إدارة أدوار Member/Viewer فقط: لا يمكنهم ترقية عضو إلى Admin أو تغيير دور مسؤول Admin آخر. المالك (Owner) وحده يستطيع ذلك.

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

تعليق وصول عضو مؤقتاً:

POST https://api.mail.land/v1/account/team/members/{id}/suspend

جسم { reason?, credentialDecision?, transferToMemberId? } يتحكم في ما يحدث لمفاتيح API الخاصة بهذا العضو أثناء التعليق. credentialDecision إلزامي فقط عندما يمتلك العضو مفتاح API نشطاً واحداً على الأقل: عدم إرساله في هذه الحالة يُرجع 400 CREDENTIAL_DECISION_REQUIRED مع سرد المفاتيح المكشوفة في details. بخلاف ذلك يمكن حذف الجسم بالكامل.

curl -X POST https://api.mail.land/v1/account/team/members/{id}/suspend \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

استعادة عضو موقوف:

POST https://api.mail.land/v1/account/team/members/{id}/reactivate

curl -X POST https://api.mail.land/v1/account/team/members/{id}/reactivate \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

لا يمكن للأعضاء الموقوفين تسجيل الدخول إلى مساحة العمل؛ مفاتيح API الخاصة بهم تتبع قرار بيانات الاعتماد الذي اتُّخذ عند التعليق: مع keep، تستمر مفاتيح العضو في العمل.

إزالة عضونسخ رابط القسم

DELETE https://api.mail.land/v1/account/team/members/{id}

تقبل الإزالة نفس قرار بيانات الاعتماد، كمعاملات استعلام:

DELETE https://api.mail.land/v1/account/team/members/{id}?reason=offboarding&credentialDecision=revoke&transferToMemberId=mbr_f6g7h8i9j0

كما في التعليق، credentialDecision إلزامي عندما يمتلك العضو مفتاح API نشطاً، وإلا يُرجع الاستدعاء 400 CREDENTIAL_DECISION_REQUIRED.

curl -X DELETE https://api.mail.land/v1/account/team/members/{id} \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

يُزال العضو من مساحة العمل ويفقد الوصول إلى جميع موارد مساحة العمل فوراً.

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

نقل ملكية مساحة العمل إلى عضو آخر:

POST https://api.mail.land/v1/account/team/transfer-ownership

{
  "newOwnerMemberId": "mbr_f6g7h8i9j0"
}

curl -X POST https://api.mail.land/v1/account/team/transfer-ownership \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "newOwnerMemberId": "mbr_f6g7h8i9j0" }'

يجب أن يكون الهدف مسؤولاً (Admin) نشطاً (وليس Member أو Viewer).

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

لا يوجد رمز MEMBER_ALREADY_EXISTS: كل من "عضو بالفعل" و"الدعوة موجودة مسبقاً" تُعيدان 409 CONFLICT.

يوجد أيضاً POST /v1/account/team/leave (لمغادرة المساحة بنفسك) وGET /v1/account/team/me (سجل عضويتك الخاص)، وهما غير موثّقين في مكان آخر من هذه الصفحة.

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

• مساحات العمل: إدارة إعدادات مساحة العمل
• المصادقة: المصادقة والجلسات
• الفوترة: إدارة الاشتراك والدفع