openapi: 3.1.0
info:
  title: Изучите свои электронные письма API
  description: |-
    Программный интерфейс (API - Application programming interface) системы
    тестирования электронной почты Mailexam.ru позволит настроить
    автотестирование и CI/CD сценарии

    [База знаний](https://wiki.mailexam.ru)
  termsOfService: https://mailexam.ru/agreement
  contact:
    name: to support
    email: support@mailexam.ru
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
externalDocs:
  description: Website
  url: https://mailexam.ru
servers:
  - url: https://mailexam.ru/api/v1
    description: Продуктовый сервер (использует реальные данные)
tags:
  - name: project
    description: Проект
  - name: inbox
    description: Почтовый ящик
  - name: email
    description: Электронная почта
paths:
  /project:
    get:
      tags:
        - project
      summary: Список проектов
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Недостаточно прав доступа
      security:
        - token:
  /project/store:
    post:
      tags:
        - project
      summary: Создание проекта
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '201':
          description: Успешная операция
        '403':
          description: Недостаточно прав доступа
      security:
        - token:
  /project/{uuid}:
    get:
      tags:
        - project
      summary: Информация о проекте
      parameters:
        - name: uuid
          in: path
          description: Идентификатор проекта
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Проект по идентификатору не найден
      security:
        - token:
  /project/{uuid}/update:
    put:
      tags:
        - project
      summary: Обновление информации о проекте
      parameters:
        - name: uuid
          in: path
          description: Идентификатор проекта
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Проект по идентификатору не найден
      security:
        - token:
  /project/{uuid}/delete:
    delete:
      tags:
        - project
      summary: Удаление проекта
      parameters:
        - name: uuid
          in: path
          description: Идентификатор проекта
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Проект по идентификатору не найден
      security:
        - token:
  /inbox:
    get:
      tags:
        - inbox
      summary: Список почтовых ящиков
      parameters:
        - name: project
          in: query
          description: 'Идентификатор проекта'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Недостаточно прав доступа
      security:
        - token:
  /inbox/store:
    post:
      tags:
        - inbox
      summary: Создание почтового ящика
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxRequest'
      responses:
        '201':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Недостаточно прав доступа
      security:
        - token:
  /inbox/{uuid}:
    get:
      tags:
        - inbox
      summary: Информация о почтовом ящике
      parameters:
        - name: uuid
          in: path
          description: Идентификатор почтового ящика
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Почтовый ящик по идентификатору не найден
      security:
        - token:
  /inbox/{uuid}/default:
    put:
      tags:
        - inbox
      summary: Установка признака "по умолчанию" почтового ящика
      parameters:
        - name: uuid
          in: path
          description: Идентификатор почтового ящика
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Почтовый ящик по идентификатору не найден
      security:
        - token:
  /inbox/{uuid}/update:
    put:
      tags:
        - inbox
      summary: Обновление информации о почтовом ящике
      parameters:
        - name: uuid
          in: path
          description: Идентификатор почтового ящика
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxRequest'
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Почтовый ящик по идентификатору не найден
      security:
        - token:
  /inbox/{uuid}/delete:
    delete:
      tags:
        - inbox
      summary: Удаление почтового ящика
      parameters:
        - name: uuid
          in: path
          description: Идентификатор почтового ящика
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Почтовый ящик по идентификатору не найден
      security:
        - token:
  /email:
    get:
      tags:
        - email
      summary: Список электронных писем
      parameters:
        - name: inbox
          in: query
          description: 'Идентификатор почтового ящика'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailShort'
        '403':
          description: Недостаточно прав доступа
      security:
        - token:
  /email/{uuid}:
    get:
      tags:
        - email
      summary: Информация об электронном письме
      parameters:
        - name: uuid
          in: path
          description: Идентификатор электронного письма
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Электронное письмо по идентификатору не найдено
      security:
        - token:
  /email/{uuid}/attachment:
    get:
      tags:
        - email
      summary: Вложение электронного письма
      parameters:
        - name: uuid
          in: path
          description: Идентификатор электронного письма
          required: true
          schema:
            type: string
            format: uuid
        - name: cid
          in: query
          description: 'Идентификатор вложения'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Электронное письмо по идентификатору не найдено
      security:
        - token:
  /email/{uuid}/unread:
    put:
      tags:
        - email
      summary: Установка/отмена признака "не прочтено" электронного письма
      parameters:
        - name: uuid
          in: path
          description: Идентификатор электронного письма
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                unread:
                  type: boolean
                  examples: [true]
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Электронное письмо по идентификатору не найдено
      security:
        - token:
  /email/{uuid}/like:
    put:
      tags:
        - email
      summary: Установка/отмена признака "нравится" электронного письма
      parameters:
        - name: uuid
          in: path
          description: Идентификатор электронного письма
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                like:
                  type: boolean
                  examples: [true]
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Электронное письмо по идентификатору не найдено
      security:
        - token:
  /email/{uuid}/dislike:
    put:
      tags:
        - email
      summary: Установка/отмена признака "не нравится" электронного письма
      parameters:
        - name: uuid
          in: path
          description: Идентификатор электронного письма
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dislike:
                  type: boolean
                  examples: [true]
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Электронное письмо по идентификатору не найдено
      security:
        - token:
  /email/{uuid}/relay:
    put:
      tags:
        - email
      summary: Отправка электронного письма на сервер ретрансляции
      parameters:
        - name: uuid
          in: path
          description: Идентификатор электронного письма
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Электронное письмо по идентификатору не найдено
        '422':
          description: Ошибка ретрансляции
      security:
        - token:
  /email/{uuid}/delete:
    delete:
      tags:
        - email
      summary: Удаление электронного письма
      parameters:
        - name: uuid
          in: path
          description: Идентификатор электронного письма
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Успешная операция
        '403':
          description: Недостаточно прав доступа
        '404':
          description: Электронное письмо по идентификатору не найдено
      security:
        - token:
components:
  schemas:
    ProjectRequest:
      type: object
      properties:
        name:
          type: string
          examples: ["Мой проект"]
        description:
          type: string
          examples: [null]
    ProjectResponse:
      type: object
      properties:
        uuid:
          type: string
          examples: ["536a47df-5aad-44d0-8163-a39bb55abe0b"]
        name:
          type: string
          examples: ["Мой проект"]
        description:
          type: string
          examples: [null]
        user:
          type: object
          properties:
            uuid:
              type: string
              examples: ["984f1f70-21e1-4244-bbb7-734ac151dcdc"]
            name:
              type: string
              examples: ["Служба поддержки Mailexam"]
            email:
              type: string
              examples: ["support@mailexam.ru"]
    InboxRequest:
      type: object
      properties:
        project_uuid:
          type: string
          examples: ["984f1f70-21e1-4244-bbb7-734ac151dcdc"]
        name:
          type: string
          examples: ["Все письма"]
        has_autorelay:
          type: boolean
          examples: [false]
        relay_host:
          type: string
          examples: [null]
        relay_port:
          type: string
          examples: [null]
        relay_pass:
          type: string
          examples: [null]
    InboxResponse:
      type: object
      properties:
        uuid:
          type: string
          examples: ["deab7974-a252-4412-9169-b965116b63cf"]
        project_uuid:
          type: string
          examples: ["984f1f70-21e1-4244-bbb7-734ac151dcdc"]
        name:
          type: string
          examples: ["Все письма"]
        is_default:
          type: boolean
          examples: [false]
        has_autorelay:
          type: boolean
          examples: [false]
        relay_host:
          type: string
          examples: [null]
        relay_port:
          type: string
          examples: [null]
        relay_user:
          type: string
          examples: [null]
        relay_pass:
          type: string
          examples: [null]
    EmailShort:
      type: object
      properties:
        uuid:
          type: string
          examples: ["e2f9a506-d766-4935-be11-c413384de020"]
        from:
          type: string
          examples: ["\"Mailexam\" <support@mailexam.ru>"]
        to:
          type: string
          examples: ["Служба поддержки Mailexam <support@mailexam.ru>"]
        cc:
          type: string
          examples: [null]
        subject:
          type: string
          examples: ["Параметры подключения к Mailexam"]
        human_size:
          type: string
          examples: ["113 Байт"]
        date:
          type: string
          examples: ["2025-03-01T08:58:49.000000Z"]
        attachments:
          type: boolean
          examples: [true]
        unread:
          type: boolean
          examples: [false]
        like:
          type: boolean
          examples: [true]
        dislike:
          type: boolean
          examples: [false]
    EmailDetailed:
      type: object
      properties:
        uuid:
          type: string
          examples: ["e2f9a506-d766-4935-be11-c413384de020"]
        from:
          type: string
          examples: ["\"Mailexam\" <support@mailexam.ru>"]
        to:
          type: string
          examples: ["Служба поддержки Mailexam <support@mailexam.ru>"]
        cc:
          type: string
          examples: [null]
        subject:
          type: string
          examples: ["Параметры подключения к Mailexam"]
        size:
          type: integer
          examples: [115710]
        human_size:
          type: string
          examples: ["113 Байт"]
        date:
          type: string
          examples: ["2025-03-01T08:58:49.000000Z"]
        attachments:
          type: boolean
          examples: [true]
        unread:
          type: boolean
          examples: [false]
        like:
          type: boolean
          examples: [true]
        dislike:
          type: boolean
          examples: [false]
        body:
          type: object
          properties:
            html:
              type: string
              examples: [null]
            text:
              type: string
              examples: [null]
            raw:
              type: string
              examples: [null]
            attachments:
              type: array
              examples: []
        headers:
          type: array
          examples: []
        relay:
          type: array
          examples: []
  securitySchemes:
    token:
      type: apiKey
      name: token
      in: query