SubmitEmail:
  post:
    tags:
      - mail
    summary: Submit an email for verification
    description: Store a new email for the authenticated user and send a verification code
    operationId: submitEmailForVerification
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubmitEmail'
    responses:
      '201':
        description: Verification email sent
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MailResponse'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
VerifyCode:
  post:
    tags:
      - mail
    summary: Verify an email using a code
    description: Verify the email for the authenticated user by providing the received code
    operationId: verifyEmailCode
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/VerifyCode'
    responses:
      '200':
        description: Email verified successfully
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MailResponse'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
ResendEmail:
  post:
    tags:
      - mail
    summary: Resend verification email
    description: Request a new verification email to be sent for a pending email
    operationId: resendVerificationEmail
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubmitEmail'
    responses:
      '200':
        description: Verification email resent
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MailResponse'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
DeleteEmail:
  delete:
    tags:
      - mail
    summary: Delete an email
    description: Delete an email associated with the authenticated user
    operationId: deleteEmail
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SubmitEmail'
    responses:
      '204':
        description: Email deleted
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../../generic/errors.yml#/components/schemas/ApiError'
GetEmails:
  get:
    tags:
      - mail
    summary: Get all emails for the authenticated user
    description: Returns both verified and unverified emails for the authenticated user
    operationId: getUserEmails
    responses:
      '200':
        description: Emails retrieved successfully
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EmailEntry'
      default:
        description: Unexpected error
        content:
          application/json:
            schema:
              $ref: '../../generic/errors.yml#/components/schemas/ApiError'

components:
  schemas:
    SubmitEmail:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          description: Email address to verify
    VerifyCode:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: Verification code received by email
    MailResponse:
      type: object
      required:
        - message
        - email
        - verified
      properties:
        email:
          type: string
        message:
          type: string
        verified:
          type: boolean
    EmailEntry:
      type: object
      required:
        - email
        - verified
      properties:
        email:
          type: string
          description: The user's email address
        verified:
          type: boolean
          description: Whether the email has been verified
