فضاهای کاری

فضاهای کاری (tenant‌ها) محیط‌های ایزوله برای عملیات ایمیل شما هستند. هر فضای کاری دامنه‌ها، مشترکین، کلیدهای API و صورتحساب مخصوص به خود را دارد. یک حساب کاربری واحد می‌تواند عضو چندین فضای کاری باشد.

زیرفضاهای کاری سازمان‌دهی می‌کنند، tenant‌ها جدا می‌کنندکپی پیوند بخش

زیرفضای کاری (/v1/account/workspaces) فقط منابع را درون یک tenant و با همان نقش‌های موجود سازمان‌دهی می‌کند. مرز صورتحساب، تحویل‌پذیری یا امنیت نیست. موارد زیر همیشه به tenant تعلق دارند:

• صورتحساب: پلن، اشتراک و فاکتورها
• فهرست سرکوب (suppression)
• محدودیت‌ها و سهمیه‌های ارسال
• IP‌های ارسال و اعتبار فرستنده
• امنیت کلیدهای API

اگر کسب‌وکار مستقلی دارید یا برای مشتری جداگانه‌ای ارسال می‌کنید، برای او یک tenant جداگانه بسازید، نه یک زیرفضای کاری. در غیر این صورت آن مشتری فهرست سرکوب، محدودیت‌های ارسال و اعتبار فرستنده را با بقیهٔ 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 شناسه‌ی عددی داخلی tenant است؛ publicId مقداری است که باید در فراخوانی‌های API و رابط‌های کاربری استفاده شود (فیلد عددی id تنها به این دلیل اینجا نمایش داده می‌شود که API فعلی آن را برمی‌گرداند: منطق کلاینت را حول آن نسازید، چون در حال حذف از پاسخ‌های سمت کلاینت است).

ایجاد فضای کاریکپی پیوند بخش

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 اختیاری است: اگر ارسال نشود، مقدار کوکی refresh token به‌جای آن استفاده می‌شود. 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 بین ۲ تا ۱۰۰ کاراکتر است؛ description اختیاری است و حداکثر ۵۰۰ کاراکتر.

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 در محدوده فضای کاری فعال هستند. فضای کاری از طریق claim فضای کاری فعالِ توکن تعیین می‌شود. منابع (دامنه‌ها، مشترکین، کمپین‌ها، کلیدهای API) بین فضاهای کاری ایزوله هستند.

هنگام استفاده از کلیدهای API، هر کلید به یک فضای کاری واحد متعلق است. نیازی به تغییر فضای کاری نیست: کلید به صورت خودکار زمینه را تعیین می‌کند.

پاسخ‌های خطاکپی پیوند بخش

مراحل بعدیکپی پیوند بخش

• مدیریت تیم: دعوت اعضا به فضای کاری
• صورتحساب: مدیریت اشتراک فضای کاری
• احراز هویت: مدیریت توکن و نشست
• کلیدهای API: ایجاد کلیدهای API متعلق به فضای کاری