Упътване за REST API

Базов адрес на API: https://sasho-dev.com/email-client/api/v1. Отговорите са JSON с обща структура: при успех success: true и поле data; при грешка success: false, съобщение в message и при валидационни грешки — обект errors.

Удостоверяване (Laravel Sanctum)

1. Изпратете POST https://sasho-dev.com/email-client/api/v1/login с JSON тяло (вижте по-долу).
2. В отговора вземете стойността data.token.
3. За всички защитени заявки добавете заглавка: Authorization: Bearer ВАШИЯТ_ТОКЕН.
4. Препоръчително е и Accept: application/json.

POST /api/v1/login

Без авторизационна заглавка.

{
  "email": "user@example.com",
  "password": "вашата-парола",
  "device_name": "опционално име на устройство или клиент"
}

При успех в data се връщат token, token_type (Bearer) и обект user.

POST /api/v1/logout

Изисква Bearer токен. Инвалидира текущия токен.

GET /api/v1/user

Връща текущия потребител в data.user: id, name, first_name, email, email_verified_at, avatar_url (или null).

Откриване на пощенски настройки

POST /api/v1/mail/discover

Тяло: { "email": "user@domain.com" }. При успех — открити IMAP/SMTP параметри в data.discovery.

Имейл акаунти

В маршрутите {account} е числовият идентификатор на акаунта в приложението (не имейл адресът).

GET /api/v1/email-accounts

Списък на акаунтите на потребителя: data.email_accounts.

POST /api/v1/email-accounts

Създаване на акаунт — същите полета като в уеб формата:

• manual — true за ръчни IMAP/SMTP полета, иначе автоматично откриване по имейл.
• Задължителни: email, mailbox_password.
• При manual: true: imap_host, imap_port, imap_security, imap_auth, smtp_host, smtp_port, smtp_security, smtp_auth и др. опционални полета като в уеб API.

DELETE /api/v1/email-accounts/{account}

Премахва акаунта на текущия потребител.

Пощенски папки и съобщения

{folder} е едно от: inbox, sent, spam, trash.

GET /api/v1/email-accounts/{account}/folders/{folder}/messages

Списък съобщения с преглед (заглавие, подател, дата, from_name, from_mail и др.). Опционални query параметри: sort=date_desc|date_asc (по подразбиране date_desc — най-новите отгоре), sender — част от името на изпращача, email — част от имейл адреса (филтърът се прилага върху последно заредения резултат от сървъра).

GET /api/v1/email-accounts/{account}/folders/{folder}/messages/{uid}

Пълно съобщение по IMAP UID — включително body_html / body_text.

DELETE /api/v1/email-accounts/{account}/folders/{folder}/messages/{uid}

Изтриване/обработка на съобщението според настройките на акаунта.

Настройки на пощата

PATCH /api/v1/mail/settings

Поле tab определя раздела: server, signature, profile, display, reply. По избор се подава account като query или в тялото — ID на имейл акаунта; без това се ползва първият акаунт на потребителя.

• server — IMAP/SMTP полета и опционално нова mailbox_password.
• signature — signature_html, signature_use_html.
• profile — име на профил, цвят, показвано име, reply-to, организация.
• display — inbox_group_by: none или date.
• reply — булеви reply_include_quote, reply_top_posting в JSON тялото.

При успех се връща обновеният акаунт в data.email_account.

Пример с curl (вход)

curl -X POST "https://sasho-dev.com/email-client/api/v1/login" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"email\":\"you@example.com\",\"password\":\"secret\",\"device_name\":\"curl\"}"

← Начало