# GET /v2/mail/servers/list

# Mail: Get Server List

این اندپوینت لیستی از سرورهای ایمیل **فعال** (Status = 1) را برای یک شعبه (Branch) خاص بازیابی می‌کند.   
خروجی شامل اطلاعات پیکربندی سرویس و محدودیت‌های ماهانه هر سرور است که برای مدیریت ارسال ایمیل‌ها استفاده می‌شود.

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

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fmail%2Fserver"><div class="endpoint-info"><div>**URL:** `/v2/mail/servers/list`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** MailController@mailServer</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%A7%D8%AD">- دسترسی معتبر 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>branch</td><td>mixed</td><td>**(فیلتر)** شناسه شعبه مورد نظر برای فیلتر کردن سرورهای ایمیل.</td></tr></tbody></table>

</div>#### Example Request

```bash
GET /v2/mail/servers/list?branch=10
```

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

فرآیند پردازش در متد `mailServer` به صورت زیر است:

<div class="api-docs" id="bkmrk-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%88%D8%B1%D9%88%D8%AF%DB%8C%3A-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA">1. **دریافت ورودی:** پارامتر `branch` از درخواست دریافت می‌شود.
2. **کوئری دیتابیس:** به جدول `mail_servers` کوئری زده می‌شود با دو شرط: 
    - `branch` برابر با پارامتر ورودی باشد.
    - `status` برابر با `1` باشد (فقط سرورهای فعال).
3. **تغییر ساختار (Transformation):** روی نتایج حلقه زده می‌شود تا ساختار خروجی استاندارد شود: 
    - یک شیء تو در تو به نام `service` ایجاد می‌شود که شامل نام سرویس (از فیلد `service`) و شناسه سرویس (از فیلد `service_id`) است.
    - سایر فیلدها مثل `monthly_limit` و تاریخ‌ها مستقیماً منتقل می‌شوند.
4. **ارسال پاسخ:** لیست نهایی در قالب استاندارد با وضعیت `true` بازگردانده می‌شود.

</div>## Response Structure

### پاسخ موفق

در صورت موفقیت، لیست سرورها در آرایه `data` قرار می‌گیرد.

<div class="api-docs" id="bkmrk-status-code%3A-200-ok-">- **Status Code:** `200 OK`
- **Body:**```json
    {
      "status": true,
      "time": 1670154800,
      "data": [
        {
          "id": 5,
          "service": {
            "title": "SendGrid",
            "id": 101
          },
          "monthly_limit": 5000,
          "created_at": "2023-01-10 12:00:00",
          "updated_at": "2023-05-15 14:30:00"
        },
        {
          "id": 8,
          "service": {
            "title": "SMTP Internal",
            "id": 202
          },
          "monthly_limit": 10000,
          "created_at": "2023-02-20 09:00:00",
          "updated_at": "2023-02-20 09:00:00"
        }
      ]
    }
    ```

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

در صورت بروز هرگونه خطا (Exception) در طول پردازش، کد وضعیت 400 بازگردانده می‌شود.

<div class="api-docs" id="bkmrk-status-code%3A-400-bad">- **Status Code:** `400 Bad Request`
- **Body:**```json
    {
      "status": false,
      "error": "Error message description..."
    }
    ```

</div>## Flowchart

<div class="api-docs" id="bkmrk-start-%28get-%2Fmail%2Fser"><div class="flowchart"><div class="flow-item">Start (GET /mail/servers/list)</div><div class="flow-arrow">↓</div><div class="flow-item-process">**Database Query**  
Table: `mail_servers`  
Where `branch` == Request input  
AND `status` == 1</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fffde7; border: 1px solid #fbc02d;">**Data Transformation Loop**  
For each server:  
Format `service` object {title, id}</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 200 OK (JSON 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 (Error Message)</div></div></div></div>