openapi: 3.1.0
info:
  title: Examining your emails API
  description: |-
    The application programming interface (API) of the
    Mailexam.io email testing system will allow you to set up
    automated testing and CI/CD scenarios

    [Knowledge Base](https://wiki.mailexam.io)
  termsOfService: https://mailexam.io/agreement
  contact:
    name: to support
    email: support@mailexam.io
  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.io
servers:
  - url: https://mailexam.io/api/v1
    description: Product server (uses real data)
tags:
  - name: project
    description: Project
  - name: inbox
    description: Mailbox
  - name: email
    description: Email
paths:
  /project:
    get:
      tags:
        - project
      summary: List of projects
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Insufficient access rights
      security:
        - token:
  /project/store:
    post:
      tags:
        - project
      summary: Creating a project
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '201':
          description: Successful operation
        '403':
          description: Insufficient access rights
      security:
        - token:
  /project/{uuid}:
    get:
      tags:
        - project
      summary: Project information
      parameters:
        - name: uuid
          in: path
          description: Project ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Insufficient access rights
        '404':
          description: Project not found by ID
      security:
        - token:
  /project/{uuid}/update:
    put:
      tags:
        - project
      summary: Updating project information
      parameters:
        - name: uuid
          in: path
          description: Project ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '403':
          description: Insufficient access rights
        '404':
          description: Project not found by ID
      security:
        - token:
  /project/{uuid}/delete:
    delete:
      tags:
        - project
      summary: Deleting a project
      parameters:
        - name: uuid
          in: path
          description: Project ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
        '403':
          description: Insufficient access rights
        '404':
          description: Project not found by ID
      security:
        - token:
  /inbox:
    get:
      tags:
        - inbox
      summary: List of mailboxes
      parameters:
        - name: project
          in: query
          description: 'Project ID'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Insufficient access rights
      security:
        - token:
  /inbox/store:
    post:
      tags:
        - inbox
      summary: Creating a mailbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxRequest'
      responses:
        '201':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Insufficient access rights
      security:
        - token:
  /inbox/{uuid}:
    get:
      tags:
        - inbox
      summary: Mailbox information
      parameters:
        - name: uuid
          in: path
          description: Mailbox ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Insufficient access rights
        '404':
          description: Mailbox not found by ID
      security:
        - token:
  /inbox/{uuid}/default:
    put:
      tags:
        - inbox
      summary: Setting the "default" mailbox flag
      parameters:
        - name: uuid
          in: path
          description: Mailbox ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Insufficient access rights
        '404':
          description: Mailbox not found by ID
      security:
        - token:
  /inbox/{uuid}/update:
    put:
      tags:
        - inbox
      summary: Updating mailbox information
      parameters:
        - name: uuid
          in: path
          description: Mailbox ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxRequest'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxResponse'
        '403':
          description: Insufficient access rights
        '404':
          description: Mailbox not found by ID
      security:
        - token:
  /inbox/{uuid}/delete:
    delete:
      tags:
        - inbox
      summary: Deleting a mailbox
      parameters:
        - name: uuid
          in: path
          description: Mailbox ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
        '403':
          description: Insufficient access rights
        '404':
          description: Mailbox not found by ID
      security:
        - token:
  /email:
    get:
      tags:
        - email
      summary: List of emails
      parameters:
        - name: inbox
          in: query
          description: 'Mailbox ID'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EmailShort'
        '403':
          description: Insufficient access rights
      security:
        - token:
  /email/{uuid}:
    get:
      tags:
        - email
      summary: Email Information
      parameters:
        - name: uuid
          in: path
          description: Email ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Insufficient access rights
        '404':
          description: Email not found by ID
      security:
        - token:
  /email/{uuid}/attachment:
    get:
      tags:
        - email
      summary: Email attachment
      parameters:
        - name: uuid
          in: path
          description: Email ID
          required: true
          schema:
            type: string
            format: uuid
        - name: cid
          in: query
          description: 'Attachment ID'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Insufficient access rights
        '404':
          description: Email not found by ID
      security:
        - token:
  /email/{uuid}/unread:
    put:
      tags:
        - email
      summary: Set/unset the "unread" flag for an email
      parameters:
        - name: uuid
          in: path
          description: Email ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                unread:
                  type: boolean
                  examples: [true]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Insufficient access rights
        '404':
          description: Email not found by ID
      security:
        - token:
  /email/{uuid}/like:
    put:
      tags:
        - email
      summary: Like an email
      parameters:
        - name: uuid
          in: path
          description: Email ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                like:
                  type: boolean
                  examples: [true]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Insufficient access rights
        '404':
          description: Email not found by ID
      security:
        - token:
  /email/{uuid}/dislike:
    put:
      tags:
        - email
      summary: Dislike an email
      parameters:
        - name: uuid
          in: path
          description: Email ID
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                dislike:
                  type: boolean
                  examples: [true]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Insufficient access rights
        '404':
          description: Email not found by ID
      security:
        - token:
  /email/{uuid}/relay:
    put:
      tags:
        - email
      summary: Sending an email to a relay server
      parameters:
        - name: uuid
          in: path
          description: Email ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDetailed'
        '403':
          description: Insufficient access rights
        '404':
          description: Email not found by ID
        '422':
          description: Retransmission error
      security:
        - token:
  /email/{uuid}/delete:
    delete:
      tags:
        - email
      summary: Deleting an email
      parameters:
        - name: uuid
          in: path
          description: Email ID
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful operation
        '403':
          description: Insufficient access rights
        '404':
          description: Email not found by ID
      security:
        - token:
components:
  schemas:
    ProjectRequest:
      type: object
      properties:
        name:
          type: string
          examples: ["My project"]
        description:
          type: string
          examples: [null]
    ProjectResponse:
      type: object
      properties:
        uuid:
          type: string
          examples: ["536a47df-5aad-44d0-8163-a39bb55abe0b"]
        name:
          type: string
          examples: ["My project"]
        description:
          type: string
          examples: [null]
        user:
          type: object
          properties:
            uuid:
              type: string
              examples: ["984f1f70-21e1-4244-bbb7-734ac151dcdc"]
            name:
              type: string
              examples: ["Support Mailexam.io"]
            email:
              type: string
              examples: ["support@mailexam.io"]
    InboxRequest:
      type: object
      properties:
        project_uuid:
          type: string
          examples: ["984f1f70-21e1-4244-bbb7-734ac151dcdc"]
        name:
          type: string
          examples: ["All emails"]
        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: ["All emails"]
        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.io\" <support@mailexam.io>"]
        to:
          type: string
          examples: ["Support Mailexam.io <support@mailexam.io>"]
        cc:
          type: string
          examples: [null]
        subject:
          type: string
          examples: ["Mailexam.io connection parameters"]
        human_size:
          type: string
          examples: ["113 Byte"]
        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.io\" <support@mailexam.io>"]
        to:
          type: string
          examples: ["Support Mailexam.io <support@mailexam.io>"]
        cc:
          type: string
          examples: [null]
        subject:
          type: string
          examples: ["Mailexam.io connection parameters"]
        size:
          type: integer
          examples: [115710]
        human_size:
          type: string
          examples: ["113 Byte"]
        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