smtpbiz-exporter/openapi.yaml

openapi: 3.0.0
info:
  title: SMTP Client API
  description: API для взаимодействия с SMTP-сервисом
  version: "1.0.0"

paths:
  /user:
    get:
      summary: Получить данные о пользователе
      description: Возвращает информацию о текущем пользователе, включая лимиты на отправку писем, тарифный план и баланс
      tags:
        - User
      parameters:
        - name: Authorization
          in: header
          description: Токен авторизации API
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDataResponse'
        "401":
          description: Не авторизован
  /user/stats:
    get:
      summary: Статистика по рассылкам
      description: Возвращает статистику по отправленным сообщениям
      tags:
        - User
      parameters:
        - name: Authorization
          in: header
          description: Токен авторизации API
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStatsResponse'
        "401":
          description: Не авторизован
  /user/domain:
    get:
      summary: Домены отправителя
      description: Информация о доменах
      tags:
        - User
      parameters:
        - name: Authorization
          in: header
          description: Токен авторизации API
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainsResponse'
        "401":
          description: Не авторизован
  /user/ip:
    get:
      summary: Выделенные IP-адреса пользователя
      description: Информация о IP-адресах пользователя
      tags:
        - User
      parameters:
        - name: Authorization
          in: header
          description: Токен авторизации API
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpsResponse'
        "400":
          description: IP-адреса не найдены
        "401":
          description: Не авторизован
  /log/message:
    get:
      summary: Получить отправленные письма
      description: Журнал с информацией о отправленных письмах
      tags:
        - Log
      parameters:
        - name: Authorization
          in: header
          description: Токен авторизации API
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Количество строк возврата
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: Шаг (пагинация)
          required: false
          schema:
            type: integer
        - name: from
          in: query
          description: Email отправителя
          required: false
          schema:
            type: string
        - name: to
          in: query
          description: Email получателя
          required: false
          schema:
            type: string
        - name: is_open
          in: query
          description: Открытые письма
          required: false
          schema:
            type: boolean
        - name: is_unsubscribe
          in: query
          description: Отписка
          required: false
          schema:
            type: boolean
        - name: startDate
          in: query
          description: Дата начала, формат 2020-01-01
          required: false
          schema:
            type: string
        - name: endDate
          in: query
          description: Дата конца, формат 2020-01-01
          required: false
          schema:
            type: string
        - name: tag
          in: query
          description: Индификатор X-Tag
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Статус письма (sent, resent, return, bounce, cancel)
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogMsgResponse'
        "401":
          description: Не авторизован
        "404":
          description: Отправленные письма не найдены

  /unsubscribe:
    get:
      summary: Получить список отписчиков
      description: Выводит информацию о отписчиках
      tags:
        - Unsubscribe
      parameters:
        - name: Authorization
          in: header
          description: Токен авторизации API
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Количество строк возврата
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: Шаг (пагинация)
          required: false
          schema:
            type: integer
        - name: address
          in: query
          description: Email адрес
          required: false
          schema:
            type: string
        - name: reason
          in: query
          description: Причина отписки (bounce, user, unsubscribe)
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Успешный ответ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnsubscribeResponse'
        "404":
          description: Отписчики не найдены

components:
  schemas:
    UserDataResponse:
      type: object
      properties:
        hsent:
          type: integer
          description: Количество писем, отправленных за последний час
        hlimit:
          type: integer
          description: Лимит на количество писем, которые можно отправить за час
        dsent:
          type: integer
          description: Количество писем, отправленных за текущий день
        dlimit:
          type: integer
          description: Лимит на количество писем, которые можно отправить за день
        quota:
          type: integer
          description: Оставшееся количество писем, которые можно отправить в рамках текущего тарифа
        validate:
          type: integer
          description: Лимит на количество проверок email адресов
        tarif:
          type: string
          description: Название текущего тарифа
        expires_quota:
          type: string
          format: date
          description: Дата окончания квоты
        tarif_quota:
          type: integer
          description: Общая квота на отправку писем по тарифу
        balance:
          type: number
          format: float
          description: Баланс в валюте
        tarif_price:
          type: number
          format: float
          description: Стоимость тарифного плана в месяц

    UserStatsResponse:
      type: object
      properties:
        sent:
          type: integer
          description: Общее количество отправленных писем
        open:
          type: integer
          description: Количество открытых писем
        spam:
          type: integer
          description: Количество писем, попавших в спам
        bounce:
          type: integer
          description: Количество писем, которые вернулись как недоставленные
        unsub:
          type: integer
          description: Количество отписавшихся пользователей
        tracking:
          $ref: '#/components/schemas/TrackingStats'

    TrackingStats:
      type: object
      properties:
        device:
          $ref: '#/components/schemas/DeviceStats'
        activity:
          $ref: '#/components/schemas/ActivityStats'
        country:
          type: object
          additionalProperties:
            type: integer
          description: Статистика по странам (код страны и количество взаимодействий)

    DeviceStats:
      type: object
      properties:
        computer:
          type: integer
          description: Количество взаимодействий с компьютеров
        tablet:
          type: integer
          description: Количество взаимодействий с планшетов
        mobile:
          type: integer
          description: Количество взаимодействий с мобильных устройств

    ActivityStats:
      type: object
      properties:
        morning:
          type: integer
          description: Взаимодействия утром
        day:
          type: integer
          description: Взаимодействия днем
        evening:
          type: integer
          description: Взаимодействия вечером
        night:
          type: integer
          description: Взаимодействия ночью
    DomainsResponse:
      type: array
      items:
        type: object
        properties:
          domain:
            type: string
            description: Имя домена
          spf:
            type: boolean
            description: SPF запись
          dkim:
            type: boolean
            description: DKIM запись
          cname:
            type: boolean
            description: CNAME запись
          isModeration:
            type: boolean
            description: Статус модерации
          isActive:
            type: boolean
            description: Статус активности домена
    IpsResponse:
      type: array
      items:
        type: object
        properties:
          sent:
            type: integer
            description: Количество отправленных писем
          bounce:
            type: integer
            description: Количество возвратов
          ip:
            type: string
            format: ipv4
            description: IP адрес
          isInstall:
            type: boolean
            description: Установлен ли IP
          isActive:
            type: boolean
            description: Активен ли IP
          expiresDate:
            type: string
            format: date
            description: Дата окончания
          createDate:
            type: string
            format: date
            description: Дата создания
    LogMsgResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              mailfrom:
                type: string
                description: От кого отправлено письмо
              mailto:
                type: string
                description: Кому отправлено письмо
              status:
                type: string
                description: Статус письма
              is_open:
                type: boolean
                description: Было ли письмо открыто
              subject:
                type: string
                description: Тема письма
              is_unsubscribe:
                type: boolean
                description: Является ли письмо отпиской
              tag:
                type: string
                description: Тег сообщения
              response:
                type: string
                description: Ответ от сервера
              messageid:
                type: string
                description: Уникальный идентификатор сообщения
              date:
                type: string
                format: date-time
                description: Дата и время отправки сообщения
        totalPages:
          type: integer
          description: Всего страниц
        totalCount:
          type: integer
          description: Всего записей
        perPagesCount:
          type: integer
          description: Количество записей на странице
    UnsubscribeResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/UnsubscribeData'
        totalPages:
          type: integer
          description: Общее количество страниц
        totalCount:
          type: integer
          description: Общее количество записей

    UnsubscribeData:
      type: object
      properties:
        mailto:
          type: string
          description: Адрес электронной почты
        reason:
          type: string
          description: Причина отписки
        date:
          type: string
          format: date-time
          description: Дата и время события