# GET /v2/mail/address/list

# Mail: Get Address List

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

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fmail%2Faddres"><div class="endpoint-info"><div>**URL:** `/v2/mail/address/list`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** MailController@mailAddress</div><div>**Middleware Stack:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-jwt-%28%D8%B4%D9%86">- دسترسی معتبر JWT (شناسه اپراتور از توکن/درخواست استخراج می‌شود).

</div>## Query Parameters

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>server</td><td>integer</td><td>**(الزامی)** شناسه سرور ایمیل (`mail\_servers.id`) که آدرس‌ها باید از آن خوانده شوند.</td></tr><tr><td>operator</td><td>object/id</td><td>**(ضمنی)** آبجکت اپراتور که معمولاً توسط میدل‌ور احراز هویت به درخواست تزریق می‌شود (برای بررسی دسترسی).</td></tr></tbody></table>

</div>#### Example Request

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

<div class="api-docs" id="bkmrk--1"></div>## Logic Details

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

<div class="api-docs" id="bkmrk-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D8%A7%D8%B7%D9%84%D8%A7%D8%B9%D8%A7%D8%AA-%D9%BE%D8%A7%DB%8C%D9%87%3A">1. **دریافت اطلاعات پایه:**
    - شناسه اپراتور (`operator-&gt;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`

</div>## Response Structure

### پاسخ موفق

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

<div class="api-docs" id="bkmrk-status-code%3A-200-ok-">- **Status Code:** `200 OK`
- **Body:**```json
    {
      "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"
        }
      ]
    }
    ```

</div>### پاسخ خطا

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

<div class="api-docs" id="bkmrk-status-code%3A-400-bad">- **Status Code:** `400 Bad Request`
- **Body:**```json
    {
      "status": false,
      "error": "Trying to get property 'id' of non-object", // Example if server not found
      "trace": [...]
    }
    ```

</div>## Flowchart

<div class="api-docs" id="bkmrk-start-%28get-%2Fmail%2Fadd"><div class="flowchart"><div class="flow-item">Start (GET /mail/address/list)</div><div class="flow-arrow">↓</div><div class="flow-item-process">**Fetch Server Info**  
Get `mail_servers` row by ID.  
(Retrieve Domain)</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Query Addresses (Security Check)**  
From `mail_address` WHERE:  
1. `server` matches  
2. `status` = 1  
3. `JSON_CONTAINS(users, operator_id)`</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fffde7; border: 1px solid #fbc02d;">**Format Loop**  
1. Remove `users`, `status`.  
2. `address` = `address` + '@' + `server.domain`.</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 200 OK (List)</div><div class="flow-error-path" style="margin-top: 20px;"><div class="flow-arrow-error">→ On Exception</div><div class="flow-item-error">Return 400 Bad Request</div></div></div></div>