openapi: 3.0.0
info:
  title: Mail Unsubscribe API
  description: API for managing email unsubscription
  version: 1.0.0
servers:
  - url: https://api.repzo.me/v1
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Mail Unsubscribe
    description: Email unsubscription management operations
paths:
  /mail-unsubscribe:
    get:
      tags:
        - Mail Unsubscribe
      summary: Get all unsubscribed emails
      description: Retrieve a list of all unsubscribed email addresses with optional filtering and pagination
      parameters:
        - name: page
          in: query
          description: Page number for pagination
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: per_page
          in: query
          description: Number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: sort
          in: query
          description: Sort field
          required: false
          schema:
            type: string
        - name: email
          in: query
          description: Filter by email address
          required: false
          schema:
            type: string
        - name: company_namespace
          in: query
          description: Company namespace for filtering
          required: false
          schema:
            type: array
            items:
              type: string
        - name: _id
          in: query
          description: Filter by ID
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/MailUnsubscribe"
                  paging:
                    $ref: "#/components/schemas/PagingInfo"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
    post:
      tags:
        - Mail Unsubscribe
      summary: Add email to unsubscribe list
      description: Add an email address to the unsubscribe list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateMailUnsubscribeRequest"
      responses:
        "201":
          description: Email unsubscribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/MailUnsubscribe"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /mail-unsubscribe/{id}:
    get:
      tags:
        - Mail Unsubscribe
      summary: Get unsubscribe record by ID
      description: Retrieve a specific unsubscribe record by its ID
      parameters:
        - name: id
          in: path
          required: true
          description: Unsubscribe record ID
          schema:
            type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: "#/components/schemas/MailUnsubscribe"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
    delete:
      tags:
        - Mail Unsubscribe
      summary: Remove email from unsubscribe list
      description: Remove an email address from the unsubscribe list (re-subscribe)
      parameters:
        - name: id
          in: path
          required: true
          description: Unsubscribe record ID
          schema:
            type: string
      responses:
        "200":
          description: Email re-subscribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /mail-unsubscribe/remove:
    post:
      tags:
        - Mail Unsubscribe
      summary: Bulk remove emails from unsubscribe list
      description: Remove multiple email addresses from the unsubscribe list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                  description: Array of unsubscribe record IDs to remove
              required:
                - ids
      responses:
        "200":
          description: Emails re-subscribed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
  /mail-unsubscribe/check:
    post:
      tags:
        - Mail Unsubscribe
      summary: Check if email is unsubscribed
      description: Check if an email address is in the unsubscribe list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to check
              required:
                - email
      responses:
        "200":
          description: Check result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      is_unsubscribed:
                        type: boolean
                        description: Whether the email is unsubscribed
                      unsubscribe_date:
                        type: string
                        format: date-time
                        description: Date when email was unsubscribed (if applicable)
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalServerError"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: "Use format: Bearer {api_key}"
  schemas:
    MailUnsubscribe:
      type: object
      properties:
        _id:
          type: string
          description: Unique identifier
          example: "507f1f77bcf86cd799439011"
        email:
          type: string
          format: email
          description: Unsubscribed email address
          example: "user@example.com"
        reason:
          type: string
          description: Reason for unsubscribing
          example: "User requested unsubscribe"
        unsubscribe_types:
          type: array
          items:
            type: string
          description: Types of emails to unsubscribe from
          example: ["marketing", "newsletters"]
        company_namespace:
          type: array
          items:
            type: string
          description: Company namespace
        user_agent:
          type: string
          description: User agent of the request
        ip_address:
          type: string
          description: IP address of the request
        createdAt:
          type: string
          format: date-time
          description: Unsubscribe date
        modifiedAt:
          type: string
          format: date-time
          description: Last modification timestamp
        SVClient:
          type: integer
          description: Client version
        __v:
          type: integer
          description: Document version
      required:
        - email
    CreateMailUnsubscribeRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address to unsubscribe
          example: "user@example.com"
        reason:
          type: string
          description: Reason for unsubscribing
          example: "User requested unsubscribe"
        unsubscribe_types:
          type: array
          items:
            type: string
          description: Types of emails to unsubscribe from
          default: ["all"]
        company_namespace:
          type: array
          items:
            type: string
          description: Company namespace
        user_agent:
          type: string
          description: User agent of the request
        ip_address:
          type: string
          description: IP address of the request
      required:
        - email
    PagingInfo:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items
        page:
          type: integer
          description: Current page number
        per_page:
          type: integer
          description: Items per page
        pages:
          type: integer
          description: Total number of pages
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Invalid request parameters"
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Authentication required"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Insufficient permissions"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Resource not found"
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Validation failed"
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: "Internal server error"