Skip to main content
#P1698

POST /v2/mail/address/store

Mail: Create Address

این اندپوینت برای ایجاد یک حساب ایمیل جدید استفاده می‌شود.
این متد یک فرآیند دو مرحله‌ای دارد: ابتدا درخواست ساخت اکانت را به سرویس‌دهنده خارجی (External API) ارسال می‌کند و در صورت موفقیت، اطلاعات آن را در دیتابیس محلی ذخیره کرده و به اپراتور درخواست‌دهنده تخصیص می‌دهد.

Request Overview

URL: /v2/mail/address/store
Method: POST
Controller: MailController@mailAddressStore
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT (الزامی برای شناسایی اپراتور سازنده).

Body Parameters

Field Type Description
service_id string/int (الزامی) شناسه سرویس در سیستم خارجی (Third-party) که برای فراخوانی API آن استفاده می‌شود.
server integer (الزامی) شناسه رکورد سرور در دیتابیس داخلی (`mail_servers.id`) برای اتصال ایمیل به سرور.
address string (اختیاری) نام کاربری ایمیل (بدون @domain).
اگر ارسال نشود، سیستم به طور خودکار بر اساس نام لاتین اپراتور (`f.lastname`) آن را تولید می‌کند.

Logic Details

فرآیند متد mailAddressStore به شرح زیر است:

  1. تعیین نام کاربری (Address Generation):
    • اگر پارامتر address ارسال شده باشد، همان استفاده می‌شود.
    • اگر ارسال نشده باشد، سیستم حرف اول first_name_en و کل last_name_en اپراتور را با نقطه ترکیب کرده و کوچک (lowercase) می‌کند. (مثال: `a.rezayi`).
  2. فراخوانی سرویس خارجی:
    • یک درخواست POST به آدرس baseUrl/{service_id}/accounts ارسال می‌شود.
    • پارامتر ارسالی: { "name": mailAddress }.
    • هدر: توکن Bearer داخلی سیستم (`$this->token`).
  3. بررسی پاسخ و ذخیره‌سازی:
    • اگر پاسخ سرویس خارجی موفق (`status == 'success'`) باشد:
      یک رکورد در جدول mail_address درج می‌شود شامل:
      • server: شناسه سرور داخلی.
      • address: نام کاربری ایمیل.
      • title: نام کامل فارسی اپراتور.
      • users: آرایه JSON حاوی شناسه اپراتور سازنده (به عنوان مالک).
      • avatar و service_id.
    • اگر پاسخ ناموفق باشد، پیام خطای سرویس خارجی بازگردانده می‌شود.

Response Structure

پاسخ موفق (Created)

حساب کاربری هم در سرویس خارجی و هم در دیتابیس داخلی ایجاد شده است.

  • Status Code: 200 OK
  • Body: 
    {
  "status": true,
  "time": 1670155000,
  "data": "a.username" // The created mail address
}

پاسخ ناموفق (API Reject)

سرویس خارجی درخواست ساخت اکانت را رد کرده است (مثلاً نام کاربری تکراری است).

  • Status Code: 200 OK
  • Body: 
    {
  "status": false,
  "time": 1670155005,
  "message": "User already exists or invalid name." // Error from external API
}

پاسخ خطا (Exception)

  • Status Code: 400 Bad Request
  • Body: 
    {
  "status": false,
  "error": "Http request failed...",
  "trace": [...]
}

Flowchart

Start (POST /mail/address/store)
↓
Has `address` Input?
No
Yes
Generate: lower(f.lastname)
Use Input Address
↓
External API Call
POST /accounts
(Payload: name)
↓
API Result Success?
↓ (Yes)
DB Insert (mail_address)
Set `users` = [operator_id]
Set `title`, `avatar` from operator
↓
Return Status True + Address
→ (No)
Return Status False + API Message
→ On Exception
Return 400 Bad Request
Back to top