Skip to main content
#P1697

GET /v2/mail/address/list

Mail: Get Address List

این اندپوینت لیستی از آدرس‌های ایمیل تعریف شده روی یک سرور خاص را برمی‌گرداند.
نکته کلیدی در این اندپوینت، سیستم دسترسی است: تنها آدرس‌هایی بازگردانده می‌شوند که شناسه اپراتور درخواست‌دهنده در لیست کاربران مجاز آن آدرس (`users` JSON column) وجود داشته باشد. همچنین آدرس نهایی با ترکیب نام کاربری و دامنه سرور ساخته می‌شود.

Request Overview

URL: /v2/mail/address/list
Method: GET
Controller: MailController@mailAddress
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT (شناسه اپراتور از توکن/درخواست استخراج می‌شود).

Query Parameters

Field Type Description
server integer (الزامی) شناسه سرور ایمیل (`mail_servers.id`) که آدرس‌ها باید از آن خوانده شوند.
operator object/id (ضمنی) آبجکت اپراتور که معمولاً توسط میدل‌ور احراز هویت به درخواست تزریق می‌شود (برای بررسی دسترسی).

Example Request

GET /v2/mail/address/list?server=5

Logic Details

مراحل پردازش در متد mailAddress به شرح زیر است:

  1. دریافت اطلاعات پایه:
    • شناسه اپراتور (`operator->id`) از درخواست استخراج می‌شود.
    • اطلاعات سرور ایمیل بر اساس پارامتر `server` از جدول `mail_servers` واکشی می‌شود (جهت دسترسی به دامنه سرور).
  2. جستجو در دیتابیس (فیلترینگ امنیتی):
    کوئری به جدول `mail_address` زده می‌شود با شروط زیر:
    • server: منطبق با شناسه سرور درخواستی باشد.
    • status: برابر با 1 (فعال) باشد.
    • users: این فیلد یک آرایه JSON است. سیستم با استفاده از دستور JSON_CONTAINS بررسی می‌کند که آیا شناسه اپراتور جاری در لیست کاربران مجاز این ایمیل وجود دارد یا خیر.
  3. آماده‌سازی خروجی (Data Mutation):
    • فیلدهای داخلی و حساس (`users` و `status`) از شیء نتیجه حذف می‌شوند.
    • آدرس کامل ایمیل ساخته می‌شود: مقدار فیلد `address` (نام کاربری) با کاراکتر `@` و `domain` (از جدول سرور) ترکیب می‌شود.
      مثال: `info` + `@` + `example.com` = `info@example.com`

Response Structure

پاسخ موفق

لیست آدرس‌های مجاز به همراه آدرس کامل ساخته شده بازگردانده می‌شود.

  • Status Code: 200 OK
  • Body: 
    {
  "status": true,
  "time": 1670154900,
  "data": [
    {
      "id": 12,
      "server": 5,
      "address": "support@mydomain.com", // <-- Full address constructed dynamically
      "name": "Support Team", // Other fields from DB
      "created_at": "2023-01-01 10:00:00",
      "updated_at": "2023-01-01 10:00:00"
    },
    {
      "id": 14,
      "server": 5,
      "address": "sales@mydomain.com",
      "name": "Sales Department",
      "created_at": "2023-02-01 11:00:00",
      "updated_at": "2023-02-01 11:00:00"
    }
  ]
}

پاسخ خطا

در صورت بروز خطا (مثلاً سرور یافت نشود یا خطای دیتابیس)، پاسخ 400 بازگردانده می‌شود.

  • Status Code: 400 Bad Request
  • Body: 
    {
  "status": false,
  "error": "Trying to get property 'id' of non-object", // Example if server not found
  "trace": [...]
}

Flowchart

Start (GET /mail/address/list)
↓
Fetch Server Info
Get `mail_servers` row by ID.
(Retrieve Domain)
↓
Query Addresses (Security Check)
From `mail_address` WHERE:
1. `server` matches
2. `status` = 1
3. `JSON_CONTAINS(users, operator_id)`
↓
Format Loop
1. Remove `users`, `status`.
2. `address` = `address` + '@' + `server.domain`.
↓
Return 200 OK (List)
→ On Exception
Return 400 Bad Request
Back to top