backbone-mailing 0.4.0

openapi: '3.0.3'
info:
  title: Backbone API
  version: '1.0.0'
  description: |
    Auto-generated by backbone-cli.
    This API provides 11 standard CRUD endpoints for each model.

servers:
  - url: /
    description: Development server

tags:
  - name: MailingAbTests
    description: MailingAbTest management endpoints
  - name: MailingAudiences
    description: MailingAudience management endpoints
  - name: MailingContacts
    description: MailingContact management endpoints
  - name: MailingSubscriptions
    description: MailingSubscription management endpoints
  - name: OptOutReasons
    description: OptOutReason management endpoints
  - name: Mailings
    description: Mailing management endpoints
  - name: MailingTraces
    description: MailingTrace management endpoints
  - name: MailingFilters
    description: MailingFilter management endpoints

paths:
  /api/v1/mailing/mailing_ab_tests:
    get:
      tags:
        - MailingAbTests
      summary: List MailingAbTests
      description: Get a paginated list of MailingAbTests with optional filtering and sorting
      operationId: listMailingAbTests
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTestList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - MailingAbTests
      summary: Create MailingAbTest
      description: Create a new MailingAbTest
      operationId: createMailingAbTest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailingAbTestRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTest'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/mailing_ab_tests/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - MailingAbTests
      summary: Get MailingAbTest by ID
      operationId: getMailingAbTest
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTest'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - MailingAbTests
      summary: Update MailingAbTest (full)
      operationId: updateMailingAbTest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingAbTestRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTest'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - MailingAbTests
      summary: Update MailingAbTest (partial)
      operationId: patchMailingAbTest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMailingAbTestRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTest'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - MailingAbTests
      summary: Delete MailingAbTest (soft)
      operationId: deleteMailingAbTest
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_ab_tests/bulk:
    post:
      tags:
        - MailingAbTests
      summary: Bulk create MailingAbTests
      operationId: bulkCreateMailingAbTests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateMailingAbTestRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MailingAbTest'
    put:
      tags:
        - MailingAbTests
      summary: Bulk update MailingAbTests (full, atomic)
      operationId: bulkUpdateMailingAbTests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateMailingAbTestRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTestBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - MailingAbTests
      summary: Bulk partial-update MailingAbTests (atomic)
      operationId: bulkPatchMailingAbTests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTestBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_ab_tests/upsert:
    post:
      tags:
        - MailingAbTests
      summary: Upsert MailingAbTest
      operationId: upsertMailingAbTest
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingAbTestRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTest'

  /api/v1/mailing/mailing_ab_tests/trash:
    get:
      tags:
        - MailingAbTests
      summary: List deleted MailingAbTests
      operationId: listDeletedMailingAbTests
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTestList'

  /api/v1/mailing/mailing_ab_tests/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - MailingAbTests
      summary: Restore deleted MailingAbTest
      operationId: restoreMailingAbTest
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTest'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_ab_tests/empty:
    delete:
      tags:
        - MailingAbTests
      summary: Empty trash for MailingAbTests
      operationId: emptyTrashMailingAbTests
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/mailing_ab_tests/delete/bulk:
    post:
      tags:
        - MailingAbTests
      summary: Bulk soft-delete MailingAbTests by ids (atomic)
      operationId: bulkDeleteMailingAbTests
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_ab_tests/restore/bulk:
    post:
      tags:
        - MailingAbTests
      summary: Bulk restore MailingAbTests by ids (atomic)
      operationId: bulkRestoreMailingAbTests
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAbTestBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_ab_tests/restore/all:
    post:
      tags:
        - MailingAbTests
      summary: Restore all soft-deleted MailingAbTests
      operationId: restoreAllMailingAbTests
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/mailing_ab_tests/trash/bulk:
    delete:
      tags:
        - MailingAbTests
      summary: Bulk permanently-delete MailingAbTests from trash by ids (atomic)
      operationId: bulkPermanentDeleteMailingAbTests
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_audiences:
    get:
      tags:
        - MailingAudiences
      summary: List MailingAudiences
      description: Get a paginated list of MailingAudiences with optional filtering and sorting
      operationId: listMailingAudiences
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudienceList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - MailingAudiences
      summary: Create MailingAudience
      description: Create a new MailingAudience
      operationId: createMailingAudience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailingAudienceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudience'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/mailing_audiences/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - MailingAudiences
      summary: Get MailingAudience by ID
      operationId: getMailingAudience
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudience'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - MailingAudiences
      summary: Update MailingAudience (full)
      operationId: updateMailingAudience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingAudienceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudience'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - MailingAudiences
      summary: Update MailingAudience (partial)
      operationId: patchMailingAudience
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMailingAudienceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudience'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - MailingAudiences
      summary: Delete MailingAudience (soft)
      operationId: deleteMailingAudience
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_audiences/bulk:
    post:
      tags:
        - MailingAudiences
      summary: Bulk create MailingAudiences
      operationId: bulkCreateMailingAudiences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateMailingAudienceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MailingAudience'
    put:
      tags:
        - MailingAudiences
      summary: Bulk update MailingAudiences (full, atomic)
      operationId: bulkUpdateMailingAudiences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateMailingAudienceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudienceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - MailingAudiences
      summary: Bulk partial-update MailingAudiences (atomic)
      operationId: bulkPatchMailingAudiences
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudienceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_audiences/upsert:
    post:
      tags:
        - MailingAudiences
      summary: Upsert MailingAudience
      operationId: upsertMailingAudience
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingAudienceRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudience'

  /api/v1/mailing/mailing_audiences/trash:
    get:
      tags:
        - MailingAudiences
      summary: List deleted MailingAudiences
      operationId: listDeletedMailingAudiences
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudienceList'

  /api/v1/mailing/mailing_audiences/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - MailingAudiences
      summary: Restore deleted MailingAudience
      operationId: restoreMailingAudience
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudience'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_audiences/empty:
    delete:
      tags:
        - MailingAudiences
      summary: Empty trash for MailingAudiences
      operationId: emptyTrashMailingAudiences
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/mailing_audiences/delete/bulk:
    post:
      tags:
        - MailingAudiences
      summary: Bulk soft-delete MailingAudiences by ids (atomic)
      operationId: bulkDeleteMailingAudiences
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_audiences/restore/bulk:
    post:
      tags:
        - MailingAudiences
      summary: Bulk restore MailingAudiences by ids (atomic)
      operationId: bulkRestoreMailingAudiences
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingAudienceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_audiences/restore/all:
    post:
      tags:
        - MailingAudiences
      summary: Restore all soft-deleted MailingAudiences
      operationId: restoreAllMailingAudiences
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/mailing_audiences/trash/bulk:
    delete:
      tags:
        - MailingAudiences
      summary: Bulk permanently-delete MailingAudiences from trash by ids (atomic)
      operationId: bulkPermanentDeleteMailingAudiences
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_contacts:
    get:
      tags:
        - MailingContacts
      summary: List MailingContacts
      description: Get a paginated list of MailingContacts with optional filtering and sorting
      operationId: listMailingContacts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContactList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - MailingContacts
      summary: Create MailingContact
      description: Create a new MailingContact
      operationId: createMailingContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailingContactRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContact'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/mailing_contacts/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - MailingContacts
      summary: Get MailingContact by ID
      operationId: getMailingContact
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContact'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - MailingContacts
      summary: Update MailingContact (full)
      operationId: updateMailingContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingContactRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContact'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - MailingContacts
      summary: Update MailingContact (partial)
      operationId: patchMailingContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMailingContactRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContact'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - MailingContacts
      summary: Delete MailingContact (soft)
      operationId: deleteMailingContact
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_contacts/bulk:
    post:
      tags:
        - MailingContacts
      summary: Bulk create MailingContacts
      operationId: bulkCreateMailingContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateMailingContactRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MailingContact'
    put:
      tags:
        - MailingContacts
      summary: Bulk update MailingContacts (full, atomic)
      operationId: bulkUpdateMailingContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateMailingContactRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContactBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - MailingContacts
      summary: Bulk partial-update MailingContacts (atomic)
      operationId: bulkPatchMailingContacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContactBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_contacts/upsert:
    post:
      tags:
        - MailingContacts
      summary: Upsert MailingContact
      operationId: upsertMailingContact
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingContactRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContact'

  /api/v1/mailing/mailing_contacts/trash:
    get:
      tags:
        - MailingContacts
      summary: List deleted MailingContacts
      operationId: listDeletedMailingContacts
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContactList'

  /api/v1/mailing/mailing_contacts/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - MailingContacts
      summary: Restore deleted MailingContact
      operationId: restoreMailingContact
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContact'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_contacts/empty:
    delete:
      tags:
        - MailingContacts
      summary: Empty trash for MailingContacts
      operationId: emptyTrashMailingContacts
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/mailing_contacts/delete/bulk:
    post:
      tags:
        - MailingContacts
      summary: Bulk soft-delete MailingContacts by ids (atomic)
      operationId: bulkDeleteMailingContacts
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_contacts/restore/bulk:
    post:
      tags:
        - MailingContacts
      summary: Bulk restore MailingContacts by ids (atomic)
      operationId: bulkRestoreMailingContacts
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingContactBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_contacts/restore/all:
    post:
      tags:
        - MailingContacts
      summary: Restore all soft-deleted MailingContacts
      operationId: restoreAllMailingContacts
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/mailing_contacts/trash/bulk:
    delete:
      tags:
        - MailingContacts
      summary: Bulk permanently-delete MailingContacts from trash by ids (atomic)
      operationId: bulkPermanentDeleteMailingContacts
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_subscriptions:
    get:
      tags:
        - MailingSubscriptions
      summary: List MailingSubscriptions
      description: Get a paginated list of MailingSubscriptions with optional filtering and sorting
      operationId: listMailingSubscriptions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscriptionList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - MailingSubscriptions
      summary: Create MailingSubscription
      description: Create a new MailingSubscription
      operationId: createMailingSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailingSubscriptionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/mailing_subscriptions/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - MailingSubscriptions
      summary: Get MailingSubscription by ID
      operationId: getMailingSubscription
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscription'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - MailingSubscriptions
      summary: Update MailingSubscription (full)
      operationId: updateMailingSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingSubscriptionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscription'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - MailingSubscriptions
      summary: Update MailingSubscription (partial)
      operationId: patchMailingSubscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMailingSubscriptionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscription'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - MailingSubscriptions
      summary: Delete MailingSubscription (soft)
      operationId: deleteMailingSubscription
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_subscriptions/bulk:
    post:
      tags:
        - MailingSubscriptions
      summary: Bulk create MailingSubscriptions
      operationId: bulkCreateMailingSubscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateMailingSubscriptionRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MailingSubscription'
    put:
      tags:
        - MailingSubscriptions
      summary: Bulk update MailingSubscriptions (full, atomic)
      operationId: bulkUpdateMailingSubscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateMailingSubscriptionRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscriptionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - MailingSubscriptions
      summary: Bulk partial-update MailingSubscriptions (atomic)
      operationId: bulkPatchMailingSubscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscriptionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_subscriptions/upsert:
    post:
      tags:
        - MailingSubscriptions
      summary: Upsert MailingSubscription
      operationId: upsertMailingSubscription
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingSubscriptionRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscription'

  /api/v1/mailing/mailing_subscriptions/trash:
    get:
      tags:
        - MailingSubscriptions
      summary: List deleted MailingSubscriptions
      operationId: listDeletedMailingSubscriptions
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscriptionList'

  /api/v1/mailing/mailing_subscriptions/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - MailingSubscriptions
      summary: Restore deleted MailingSubscription
      operationId: restoreMailingSubscription
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscription'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_subscriptions/empty:
    delete:
      tags:
        - MailingSubscriptions
      summary: Empty trash for MailingSubscriptions
      operationId: emptyTrashMailingSubscriptions
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/mailing_subscriptions/delete/bulk:
    post:
      tags:
        - MailingSubscriptions
      summary: Bulk soft-delete MailingSubscriptions by ids (atomic)
      operationId: bulkDeleteMailingSubscriptions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_subscriptions/restore/bulk:
    post:
      tags:
        - MailingSubscriptions
      summary: Bulk restore MailingSubscriptions by ids (atomic)
      operationId: bulkRestoreMailingSubscriptions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingSubscriptionBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_subscriptions/restore/all:
    post:
      tags:
        - MailingSubscriptions
      summary: Restore all soft-deleted MailingSubscriptions
      operationId: restoreAllMailingSubscriptions
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/mailing_subscriptions/trash/bulk:
    delete:
      tags:
        - MailingSubscriptions
      summary: Bulk permanently-delete MailingSubscriptions from trash by ids (atomic)
      operationId: bulkPermanentDeleteMailingSubscriptions
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/opt_out_reasons:
    get:
      tags:
        - OptOutReasons
      summary: List OptOutReasons
      description: Get a paginated list of OptOutReasons with optional filtering and sorting
      operationId: listOptOutReasons
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReasonList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - OptOutReasons
      summary: Create OptOutReason
      description: Create a new OptOutReason
      operationId: createOptOutReason
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOptOutReasonRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReason'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/opt_out_reasons/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - OptOutReasons
      summary: Get OptOutReason by ID
      operationId: getOptOutReason
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReason'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - OptOutReasons
      summary: Update OptOutReason (full)
      operationId: updateOptOutReason
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOptOutReasonRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReason'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - OptOutReasons
      summary: Update OptOutReason (partial)
      operationId: patchOptOutReason
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchOptOutReasonRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReason'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - OptOutReasons
      summary: Delete OptOutReason (soft)
      operationId: deleteOptOutReason
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/opt_out_reasons/bulk:
    post:
      tags:
        - OptOutReasons
      summary: Bulk create OptOutReasons
      operationId: bulkCreateOptOutReasons
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateOptOutReasonRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OptOutReason'
    put:
      tags:
        - OptOutReasons
      summary: Bulk update OptOutReasons (full, atomic)
      operationId: bulkUpdateOptOutReasons
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateOptOutReasonRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReasonBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - OptOutReasons
      summary: Bulk partial-update OptOutReasons (atomic)
      operationId: bulkPatchOptOutReasons
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReasonBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/opt_out_reasons/upsert:
    post:
      tags:
        - OptOutReasons
      summary: Upsert OptOutReason
      operationId: upsertOptOutReason
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOptOutReasonRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReason'

  /api/v1/mailing/opt_out_reasons/trash:
    get:
      tags:
        - OptOutReasons
      summary: List deleted OptOutReasons
      operationId: listDeletedOptOutReasons
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReasonList'

  /api/v1/mailing/opt_out_reasons/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - OptOutReasons
      summary: Restore deleted OptOutReason
      operationId: restoreOptOutReason
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReason'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/opt_out_reasons/empty:
    delete:
      tags:
        - OptOutReasons
      summary: Empty trash for OptOutReasons
      operationId: emptyTrashOptOutReasons
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/opt_out_reasons/delete/bulk:
    post:
      tags:
        - OptOutReasons
      summary: Bulk soft-delete OptOutReasons by ids (atomic)
      operationId: bulkDeleteOptOutReasons
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/opt_out_reasons/restore/bulk:
    post:
      tags:
        - OptOutReasons
      summary: Bulk restore OptOutReasons by ids (atomic)
      operationId: bulkRestoreOptOutReasons
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OptOutReasonBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/opt_out_reasons/restore/all:
    post:
      tags:
        - OptOutReasons
      summary: Restore all soft-deleted OptOutReasons
      operationId: restoreAllOptOutReasons
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/opt_out_reasons/trash/bulk:
    delete:
      tags:
        - OptOutReasons
      summary: Bulk permanently-delete OptOutReasons from trash by ids (atomic)
      operationId: bulkPermanentDeleteOptOutReasons
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailings:
    get:
      tags:
        - Mailings
      summary: List Mailings
      description: Get a paginated list of Mailings with optional filtering and sorting
      operationId: listMailings
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - Mailings
      summary: Create Mailing
      description: Create a new Mailing
      operationId: createMailing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailingRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailing'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/mailings/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - Mailings
      summary: Get Mailing by ID
      operationId: getMailing
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailing'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - Mailings
      summary: Update Mailing (full)
      operationId: updateMailing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailing'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - Mailings
      summary: Update Mailing (partial)
      operationId: patchMailing
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMailingRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailing'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - Mailings
      summary: Delete Mailing (soft)
      operationId: deleteMailing
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailings/bulk:
    post:
      tags:
        - Mailings
      summary: Bulk create Mailings
      operationId: bulkCreateMailings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateMailingRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Mailing'
    put:
      tags:
        - Mailings
      summary: Bulk update Mailings (full, atomic)
      operationId: bulkUpdateMailings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateMailingRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - Mailings
      summary: Bulk partial-update Mailings (atomic)
      operationId: bulkPatchMailings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailings/upsert:
    post:
      tags:
        - Mailings
      summary: Upsert Mailing
      operationId: upsertMailing
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailing'

  /api/v1/mailing/mailings/trash:
    get:
      tags:
        - Mailings
      summary: List deleted Mailings
      operationId: listDeletedMailings
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingList'

  /api/v1/mailing/mailings/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - Mailings
      summary: Restore deleted Mailing
      operationId: restoreMailing
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailing'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailings/empty:
    delete:
      tags:
        - Mailings
      summary: Empty trash for Mailings
      operationId: emptyTrashMailings
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/mailings/delete/bulk:
    post:
      tags:
        - Mailings
      summary: Bulk soft-delete Mailings by ids (atomic)
      operationId: bulkDeleteMailings
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailings/restore/bulk:
    post:
      tags:
        - Mailings
      summary: Bulk restore Mailings by ids (atomic)
      operationId: bulkRestoreMailings
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailings/restore/all:
    post:
      tags:
        - Mailings
      summary: Restore all soft-deleted Mailings
      operationId: restoreAllMailings
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/mailings/trash/bulk:
    delete:
      tags:
        - Mailings
      summary: Bulk permanently-delete Mailings from trash by ids (atomic)
      operationId: bulkPermanentDeleteMailings
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_traces:
    get:
      tags:
        - MailingTraces
      summary: List MailingTraces
      description: Get a paginated list of MailingTraces with optional filtering and sorting
      operationId: listMailingTraces
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTraceList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - MailingTraces
      summary: Create MailingTrace
      description: Create a new MailingTrace
      operationId: createMailingTrace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailingTraceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTrace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/mailing_traces/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - MailingTraces
      summary: Get MailingTrace by ID
      operationId: getMailingTrace
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTrace'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - MailingTraces
      summary: Update MailingTrace (full)
      operationId: updateMailingTrace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingTraceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTrace'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - MailingTraces
      summary: Update MailingTrace (partial)
      operationId: patchMailingTrace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMailingTraceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTrace'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - MailingTraces
      summary: Delete MailingTrace (soft)
      operationId: deleteMailingTrace
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_traces/bulk:
    post:
      tags:
        - MailingTraces
      summary: Bulk create MailingTraces
      operationId: bulkCreateMailingTraces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateMailingTraceRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MailingTrace'
    put:
      tags:
        - MailingTraces
      summary: Bulk update MailingTraces (full, atomic)
      operationId: bulkUpdateMailingTraces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateMailingTraceRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTraceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - MailingTraces
      summary: Bulk partial-update MailingTraces (atomic)
      operationId: bulkPatchMailingTraces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTraceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_traces/upsert:
    post:
      tags:
        - MailingTraces
      summary: Upsert MailingTrace
      operationId: upsertMailingTrace
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingTraceRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTrace'

  /api/v1/mailing/mailing_traces/trash:
    get:
      tags:
        - MailingTraces
      summary: List deleted MailingTraces
      operationId: listDeletedMailingTraces
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTraceList'

  /api/v1/mailing/mailing_traces/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - MailingTraces
      summary: Restore deleted MailingTrace
      operationId: restoreMailingTrace
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTrace'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_traces/empty:
    delete:
      tags:
        - MailingTraces
      summary: Empty trash for MailingTraces
      operationId: emptyTrashMailingTraces
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/mailing_traces/delete/bulk:
    post:
      tags:
        - MailingTraces
      summary: Bulk soft-delete MailingTraces by ids (atomic)
      operationId: bulkDeleteMailingTraces
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_traces/restore/bulk:
    post:
      tags:
        - MailingTraces
      summary: Bulk restore MailingTraces by ids (atomic)
      operationId: bulkRestoreMailingTraces
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingTraceBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_traces/restore/all:
    post:
      tags:
        - MailingTraces
      summary: Restore all soft-deleted MailingTraces
      operationId: restoreAllMailingTraces
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/mailing_traces/trash/bulk:
    delete:
      tags:
        - MailingTraces
      summary: Bulk permanently-delete MailingTraces from trash by ids (atomic)
      operationId: bulkPermanentDeleteMailingTraces
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_filters:
    get:
      tags:
        - MailingFilters
      summary: List MailingFilters
      description: Get a paginated list of MailingFilters with optional filtering and sorting
      operationId: listMailingFilters
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - $ref: '#/components/parameters/SortByParam'
        - $ref: '#/components/parameters/SortOrderParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilterList'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      tags:
        - MailingFilters
      summary: Create MailingFilter
      description: Create a new MailingFilter
      operationId: createMailingFilter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailingFilterRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilter'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /api/v1/mailing/mailing_filters/{id}:
    parameters:
      - $ref: '#/components/parameters/IdParam'

    get:
      tags:
        - MailingFilters
      summary: Get MailingFilter by ID
      operationId: getMailingFilter
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilter'
        '404':
          $ref: '#/components/responses/NotFound'

    put:
      tags:
        - MailingFilters
      summary: Update MailingFilter (full)
      operationId: updateMailingFilter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingFilterRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilter'
        '404':
          $ref: '#/components/responses/NotFound'

    patch:
      tags:
        - MailingFilters
      summary: Update MailingFilter (partial)
      operationId: patchMailingFilter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMailingFilterRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilter'
        '404':
          $ref: '#/components/responses/NotFound'

    delete:
      tags:
        - MailingFilters
      summary: Delete MailingFilter (soft)
      operationId: deleteMailingFilter
      responses:
        '204':
          description: Deleted
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_filters/bulk:
    post:
      tags:
        - MailingFilters
      summary: Bulk create MailingFilters
      operationId: bulkCreateMailingFilters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CreateMailingFilterRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MailingFilter'
    put:
      tags:
        - MailingFilters
      summary: Bulk update MailingFilters (full, atomic)
      operationId: bulkUpdateMailingFilters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                allOf:
                  - type: object
                    required: [id]
                    properties:
                      id:
                        type: string
                  - $ref: '#/components/schemas/UpdateMailingFilterRequest'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilterBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'
    patch:
      tags:
        - MailingFilters
      summary: Bulk partial-update MailingFilters (atomic)
      operationId: bulkPatchMailingFilters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required: [ids, patch]
                  properties:
                    ids:
                      type: array
                      items: { type: string }
                    patch:
                      type: object
                      additionalProperties: true
                - type: object
                  required: [items]
                  properties:
                    items:
                      type: array
                      items:
                        type: object
                        required: [id, patch]
                        properties:
                          id: { type: string }
                          patch: { type: object, additionalProperties: true }
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilterBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_filters/upsert:
    post:
      tags:
        - MailingFilters
      summary: Upsert MailingFilter
      operationId: upsertMailingFilter
      parameters:
        - name: key_field
          in: query
          schema:
            type: string
        - name: key_value
          in: query
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailingFilterRequest'
      responses:
        '200':
          description: Upserted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilter'

  /api/v1/mailing/mailing_filters/trash:
    get:
      tags:
        - MailingFilters
      summary: List deleted MailingFilters
      operationId: listDeletedMailingFilters
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilterList'

  /api/v1/mailing/mailing_filters/{id}/restore:
    parameters:
      - $ref: '#/components/parameters/IdParam'
    post:
      tags:
        - MailingFilters
      summary: Restore deleted MailingFilter
      operationId: restoreMailingFilter
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilter'
        '404':
          $ref: '#/components/responses/NotFound'

  /api/v1/mailing/mailing_filters/empty:
    delete:
      tags:
        - MailingFilters
      summary: Empty trash for MailingFilters
      operationId: emptyTrashMailingFilters
      responses:
        '200':
          description: Trash emptied
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted_count:
                    type: integer

  /api/v1/mailing/mailing_filters/delete/bulk:
    post:
      tags:
        - MailingFilters
      summary: Bulk soft-delete MailingFilters by ids (atomic)
      operationId: bulkDeleteMailingFilters
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Soft-deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  soft_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_filters/restore/bulk:
    post:
      tags:
        - MailingFilters
      summary: Bulk restore MailingFilters by ids (atomic)
      operationId: bulkRestoreMailingFilters
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MailingFilterBulkResult'
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/mailing/mailing_filters/restore/all:
    post:
      tags:
        - MailingFilters
      summary: Restore all soft-deleted MailingFilters
      operationId: restoreAllMailingFilters
      responses:
        '200':
          description: Restored
          content:
            application/json:
              schema:
                type: object
                properties:
                  restored: { type: integer }

  /api/v1/mailing/mailing_filters/trash/bulk:
    delete:
      tags:
        - MailingFilters
      summary: Bulk permanently-delete MailingFilters from trash by ids (atomic)
      operationId: bulkPermanentDeleteMailingFilters
      requestBody:
        $ref: '#/components/requestBodies/BatchIds'
      responses:
        '200':
          description: Permanently deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  permanently_deleted: { type: integer }
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    MailingAbTest:
      type: object
      required:
        - id
        - campaign_id
        - winner_selection
        - completed
        - sampling_seed
        - metadata
      properties:
        id:
          type: string
          format: uuid
        campaign_id:
          type: string
          format: uuid
        winner_selection:
          type: string
        winner_selection_sms:
          nullable: true
          type: string
        promote_at:
          nullable: true
          type: string
          format: date-time
        completed:
          type: boolean
        winner_mailing_id:
          nullable: true
          type: string
          format: uuid
        sampling_seed:
          type: string
          maxLength: 64
        metadata:
          type: object

    MailingAbTestBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingAbTest'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateMailingAbTestRequest:
      type: object
      required:
        - campaign_id
        - winner_selection
        - completed
        - sampling_seed
        - metadata
      properties:
        campaign_id:
          type: string
          format: uuid
        winner_selection:
          type: string
        winner_selection_sms:
          nullable: true
          type: string
        promote_at:
          nullable: true
          type: string
          format: date-time
        completed:
          type: boolean
        winner_mailing_id:
          nullable: true
          type: string
          format: uuid
        sampling_seed:
          type: string
          maxLength: 64
        metadata:
          type: object

    UpdateMailingAbTestRequest:
      type: object
      required:
        - campaign_id
        - winner_selection
        - completed
        - sampling_seed
        - metadata
      properties:
        campaign_id:
          type: string
          format: uuid
        winner_selection:
          type: string
        winner_selection_sms:
          nullable: true
          type: string
        promote_at:
          nullable: true
          type: string
          format: date-time
        completed:
          type: boolean
        winner_mailing_id:
          nullable: true
          type: string
          format: uuid
        sampling_seed:
          type: string
          maxLength: 64
        metadata:
          type: object

    PatchMailingAbTestRequest:
      type: object
      properties:
        campaign_id:
          type: string
          format: uuid
        winner_selection:
          type: string
        winner_selection_sms:
          nullable: true
          type: string
        promote_at:
          nullable: true
          type: string
          format: date-time
        completed:
          type: boolean
        winner_mailing_id:
          nullable: true
          type: string
          format: uuid
        sampling_seed:
          type: string
          maxLength: 64
        metadata:
          type: object

    MailingAbTestList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingAbTest'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    MailingAudience:
      type: object
      required:
        - id
        - name
        - active
        - is_public
        - metadata
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 120
        active:
          type: boolean
        is_public:
          type: boolean
        metadata:
          type: object

    MailingAudienceBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingAudience'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateMailingAudienceRequest:
      type: object
      required:
        - name
        - active
        - is_public
        - metadata
      properties:
        name:
          type: string
          maxLength: 120
        active:
          type: boolean
        is_public:
          type: boolean
        metadata:
          type: object

    UpdateMailingAudienceRequest:
      type: object
      required:
        - name
        - active
        - is_public
        - metadata
      properties:
        name:
          type: string
          maxLength: 120
        active:
          type: boolean
        is_public:
          type: boolean
        metadata:
          type: object

    PatchMailingAudienceRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        active:
          type: boolean
        is_public:
          type: boolean
        metadata:
          type: object

    MailingAudienceList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingAudience'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    MailingContact:
      type: object
      required:
        - id
        - email
        - metadata
      properties:
        id:
          type: string
          format: uuid
        name:
          nullable: true
          type: string
          maxLength: 120
        first_name:
          nullable: true
          type: string
          maxLength: 120
        last_name:
          nullable: true
          type: string
          maxLength: 120
        email:
          type: string
          maxLength: 255
        company_name:
          nullable: true
          type: string
          maxLength: 120
        country_code:
          nullable: true
          type: string
          maxLength: 2
        phone:
          nullable: true
          type: string
          maxLength: 64
        metadata:
          type: object

    MailingContactBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingContact'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateMailingContactRequest:
      type: object
      required:
        - email
        - metadata
      properties:
        name:
          nullable: true
          type: string
          maxLength: 120
        first_name:
          nullable: true
          type: string
          maxLength: 120
        last_name:
          nullable: true
          type: string
          maxLength: 120
        email:
          type: string
          maxLength: 255
        company_name:
          nullable: true
          type: string
          maxLength: 120
        country_code:
          nullable: true
          type: string
          maxLength: 2
        phone:
          nullable: true
          type: string
          maxLength: 64
        metadata:
          type: object

    UpdateMailingContactRequest:
      type: object
      required:
        - email
        - metadata
      properties:
        name:
          nullable: true
          type: string
          maxLength: 120
        first_name:
          nullable: true
          type: string
          maxLength: 120
        last_name:
          nullable: true
          type: string
          maxLength: 120
        email:
          type: string
          maxLength: 255
        company_name:
          nullable: true
          type: string
          maxLength: 120
        country_code:
          nullable: true
          type: string
          maxLength: 2
        phone:
          nullable: true
          type: string
          maxLength: 64
        metadata:
          type: object

    PatchMailingContactRequest:
      type: object
      properties:
        name:
          nullable: true
          type: string
          maxLength: 120
        first_name:
          nullable: true
          type: string
          maxLength: 120
        last_name:
          nullable: true
          type: string
          maxLength: 120
        email:
          type: string
          maxLength: 255
        company_name:
          nullable: true
          type: string
          maxLength: 120
        country_code:
          nullable: true
          type: string
          maxLength: 2
        phone:
          nullable: true
          type: string
          maxLength: 64
        metadata:
          type: object

    MailingContactList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingContact'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    MailingSubscription:
      type: object
      required:
        - id
        - contact_id
        - mailing_audience_id
        - opt_out
        - metadata
      properties:
        id:
          type: string
          format: uuid
        contact_id:
          type: string
          format: uuid
        mailing_audience_id:
          type: string
          format: uuid
        opt_out:
          type: boolean
        opt_out_datetime:
          nullable: true
          type: string
          format: date-time
        opt_out_reason_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    MailingSubscriptionBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingSubscription'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateMailingSubscriptionRequest:
      type: object
      required:
        - contact_id
        - mailing_audience_id
        - opt_out
        - metadata
      properties:
        contact_id:
          type: string
          format: uuid
        mailing_audience_id:
          type: string
          format: uuid
        opt_out:
          type: boolean
        opt_out_datetime:
          nullable: true
          type: string
          format: date-time
        opt_out_reason_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    UpdateMailingSubscriptionRequest:
      type: object
      required:
        - contact_id
        - mailing_audience_id
        - opt_out
        - metadata
      properties:
        contact_id:
          type: string
          format: uuid
        mailing_audience_id:
          type: string
          format: uuid
        opt_out:
          type: boolean
        opt_out_datetime:
          nullable: true
          type: string
          format: date-time
        opt_out_reason_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    PatchMailingSubscriptionRequest:
      type: object
      properties:
        contact_id:
          type: string
          format: uuid
        mailing_audience_id:
          type: string
          format: uuid
        opt_out:
          type: boolean
        opt_out_datetime:
          nullable: true
          type: string
          format: date-time
        opt_out_reason_id:
          nullable: true
          type: string
          format: uuid
        metadata:
          type: object

    MailingSubscriptionList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingSubscription'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    OptOutReason:
      type: object
      required:
        - id
        - name
        - sequence
        - is_feedback
        - metadata
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 120
        sequence:
          type: integer
          format: int32
        is_feedback:
          type: boolean
        metadata:
          type: object

    OptOutReasonBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OptOutReason'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateOptOutReasonRequest:
      type: object
      required:
        - name
        - sequence
        - is_feedback
        - metadata
      properties:
        name:
          type: string
          maxLength: 120
        sequence:
          type: integer
          format: int32
        is_feedback:
          type: boolean
        metadata:
          type: object

    UpdateOptOutReasonRequest:
      type: object
      required:
        - name
        - sequence
        - is_feedback
        - metadata
      properties:
        name:
          type: string
          maxLength: 120
        sequence:
          type: integer
          format: int32
        is_feedback:
          type: boolean
        metadata:
          type: object

    PatchOptOutReasonRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        sequence:
          type: integer
          format: int32
        is_feedback:
          type: boolean
        metadata:
          type: object

    OptOutReasonList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OptOutReason'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    Mailing:
      type: object
      required:
        - id
        - subject
        - body_html
        - email_from
        - keep_archives
        - state
        - schedule_type
        - mailing_type
        - target_model
        - mailing_domain
        - use_exclusion_list
        - ab_testing_enabled
        - ab_testing_pc
        - kpi_mail_required
        - metadata
      properties:
        id:
          type: string
          format: uuid
        subject:
          type: string
          maxLength: 255
        preview:
          nullable: true
          type: string
          maxLength: 255
        body_html:
          type: string
        body_plaintext:
          nullable: true
          type: string
        email_from:
          type: string
          maxLength: 255
        reply_to:
          nullable: true
          type: string
          maxLength: 255
        keep_archives:
          type: boolean
        state:
          type: string
        schedule_type:
          type: string
        schedule_date:
          nullable: true
          type: string
          format: date-time
        sent_date:
          nullable: true
          type: string
          format: date-time
        mailing_type:
          type: string
        target_model:
          type: string
        mailing_domain:
          type: object
        use_exclusion_list:
          type: boolean
        campaign_id:
          nullable: true
          type: string
          format: uuid
        medium_id:
          nullable: true
          type: string
          format: uuid
        source_id:
          nullable: true
          type: string
          format: uuid
        user_id:
          nullable: true
          type: string
          format: uuid
        ab_testing_enabled:
          type: boolean
        ab_testing_pc:
          type: integer
          format: int32
        ab_test_id:
          nullable: true
          type: string
          format: uuid
        kpi_mail_required:
          type: boolean
        metadata:
          type: object

    MailingBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Mailing'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateMailingRequest:
      type: object
      required:
        - subject
        - body_html
        - email_from
        - keep_archives
        - state
        - schedule_type
        - mailing_type
        - target_model
        - mailing_domain
        - use_exclusion_list
        - ab_testing_enabled
        - ab_testing_pc
        - kpi_mail_required
        - metadata
      properties:
        subject:
          type: string
          maxLength: 255
        preview:
          nullable: true
          type: string
          maxLength: 255
        body_html:
          type: string
        body_plaintext:
          nullable: true
          type: string
        email_from:
          type: string
          maxLength: 255
        reply_to:
          nullable: true
          type: string
          maxLength: 255
        keep_archives:
          type: boolean
        state:
          type: string
        schedule_type:
          type: string
        schedule_date:
          nullable: true
          type: string
          format: date-time
        sent_date:
          nullable: true
          type: string
          format: date-time
        mailing_type:
          type: string
        target_model:
          type: string
        mailing_domain:
          type: object
        use_exclusion_list:
          type: boolean
        campaign_id:
          nullable: true
          type: string
          format: uuid
        medium_id:
          nullable: true
          type: string
          format: uuid
        source_id:
          nullable: true
          type: string
          format: uuid
        user_id:
          nullable: true
          type: string
          format: uuid
        ab_testing_enabled:
          type: boolean
        ab_testing_pc:
          type: integer
          format: int32
        ab_test_id:
          nullable: true
          type: string
          format: uuid
        kpi_mail_required:
          type: boolean
        metadata:
          type: object

    UpdateMailingRequest:
      type: object
      required:
        - subject
        - body_html
        - email_from
        - keep_archives
        - state
        - schedule_type
        - mailing_type
        - target_model
        - mailing_domain
        - use_exclusion_list
        - ab_testing_enabled
        - ab_testing_pc
        - kpi_mail_required
        - metadata
      properties:
        subject:
          type: string
          maxLength: 255
        preview:
          nullable: true
          type: string
          maxLength: 255
        body_html:
          type: string
        body_plaintext:
          nullable: true
          type: string
        email_from:
          type: string
          maxLength: 255
        reply_to:
          nullable: true
          type: string
          maxLength: 255
        keep_archives:
          type: boolean
        state:
          type: string
        schedule_type:
          type: string
        schedule_date:
          nullable: true
          type: string
          format: date-time
        sent_date:
          nullable: true
          type: string
          format: date-time
        mailing_type:
          type: string
        target_model:
          type: string
        mailing_domain:
          type: object
        use_exclusion_list:
          type: boolean
        campaign_id:
          nullable: true
          type: string
          format: uuid
        medium_id:
          nullable: true
          type: string
          format: uuid
        source_id:
          nullable: true
          type: string
          format: uuid
        user_id:
          nullable: true
          type: string
          format: uuid
        ab_testing_enabled:
          type: boolean
        ab_testing_pc:
          type: integer
          format: int32
        ab_test_id:
          nullable: true
          type: string
          format: uuid
        kpi_mail_required:
          type: boolean
        metadata:
          type: object

    PatchMailingRequest:
      type: object
      properties:
        subject:
          type: string
          maxLength: 255
        preview:
          nullable: true
          type: string
          maxLength: 255
        body_html:
          type: string
        body_plaintext:
          nullable: true
          type: string
        email_from:
          type: string
          maxLength: 255
        reply_to:
          nullable: true
          type: string
          maxLength: 255
        keep_archives:
          type: boolean
        state:
          type: string
        schedule_type:
          type: string
        schedule_date:
          nullable: true
          type: string
          format: date-time
        sent_date:
          nullable: true
          type: string
          format: date-time
        mailing_type:
          type: string
        target_model:
          type: string
        mailing_domain:
          type: object
        use_exclusion_list:
          type: boolean
        campaign_id:
          nullable: true
          type: string
          format: uuid
        medium_id:
          nullable: true
          type: string
          format: uuid
        source_id:
          nullable: true
          type: string
          format: uuid
        user_id:
          nullable: true
          type: string
          format: uuid
        ab_testing_enabled:
          type: boolean
        ab_testing_pc:
          type: integer
          format: int32
        ab_test_id:
          nullable: true
          type: string
          format: uuid
        kpi_mail_required:
          type: boolean
        metadata:
          type: object

    MailingList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Mailing'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    MailingTrace:
      type: object
      required:
        - id
        - trace_type
        - is_test_trace
        - mailing_id
        - recipient_model
        - recipient_id
        - recipient_email
        - trace_status
        - metadata
      properties:
        id:
          type: string
          format: uuid
        trace_type:
          type: string
        is_test_trace:
          type: boolean
        mailing_id:
          type: string
          format: uuid
        campaign_id:
          nullable: true
          type: string
          format: uuid
        recipient_model:
          type: string
          maxLength: 64
        recipient_id:
          type: string
          format: uuid
        recipient_email:
          type: string
          maxLength: 255
        mail_id:
          nullable: true
          type: string
          format: uuid
        sms_uuid:
          nullable: true
          type: string
          maxLength: 64
        recipient_phone:
          nullable: true
          type: string
          maxLength: 16
        message_id:
          nullable: true
          type: string
          maxLength: 255
        trace_status:
          type: string
        failure_type:
          nullable: true
          type: string
        failure_reason:
          nullable: true
          type: string
        sent_datetime:
          nullable: true
          type: string
          format: date-time
        open_datetime:
          nullable: true
          type: string
          format: date-time
        reply_datetime:
          nullable: true
          type: string
          format: date-time
        links_click_datetime:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    MailingTraceBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingTrace'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateMailingTraceRequest:
      type: object
      required:
        - trace_type
        - is_test_trace
        - mailing_id
        - recipient_model
        - recipient_id
        - recipient_email
        - trace_status
        - metadata
      properties:
        trace_type:
          type: string
        is_test_trace:
          type: boolean
        mailing_id:
          type: string
          format: uuid
        campaign_id:
          nullable: true
          type: string
          format: uuid
        recipient_model:
          type: string
          maxLength: 64
        recipient_id:
          type: string
          format: uuid
        recipient_email:
          type: string
          maxLength: 255
        mail_id:
          nullable: true
          type: string
          format: uuid
        sms_uuid:
          nullable: true
          type: string
          maxLength: 64
        recipient_phone:
          nullable: true
          type: string
          maxLength: 16
        message_id:
          nullable: true
          type: string
          maxLength: 255
        trace_status:
          type: string
        failure_type:
          nullable: true
          type: string
        failure_reason:
          nullable: true
          type: string
        sent_datetime:
          nullable: true
          type: string
          format: date-time
        open_datetime:
          nullable: true
          type: string
          format: date-time
        reply_datetime:
          nullable: true
          type: string
          format: date-time
        links_click_datetime:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    UpdateMailingTraceRequest:
      type: object
      required:
        - trace_type
        - is_test_trace
        - mailing_id
        - recipient_model
        - recipient_id
        - recipient_email
        - trace_status
        - metadata
      properties:
        trace_type:
          type: string
        is_test_trace:
          type: boolean
        mailing_id:
          type: string
          format: uuid
        campaign_id:
          nullable: true
          type: string
          format: uuid
        recipient_model:
          type: string
          maxLength: 64
        recipient_id:
          type: string
          format: uuid
        recipient_email:
          type: string
          maxLength: 255
        mail_id:
          nullable: true
          type: string
          format: uuid
        sms_uuid:
          nullable: true
          type: string
          maxLength: 64
        recipient_phone:
          nullable: true
          type: string
          maxLength: 16
        message_id:
          nullable: true
          type: string
          maxLength: 255
        trace_status:
          type: string
        failure_type:
          nullable: true
          type: string
        failure_reason:
          nullable: true
          type: string
        sent_datetime:
          nullable: true
          type: string
          format: date-time
        open_datetime:
          nullable: true
          type: string
          format: date-time
        reply_datetime:
          nullable: true
          type: string
          format: date-time
        links_click_datetime:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    PatchMailingTraceRequest:
      type: object
      properties:
        trace_type:
          type: string
        is_test_trace:
          type: boolean
        mailing_id:
          type: string
          format: uuid
        campaign_id:
          nullable: true
          type: string
          format: uuid
        recipient_model:
          type: string
          maxLength: 64
        recipient_id:
          type: string
          format: uuid
        recipient_email:
          type: string
          maxLength: 255
        mail_id:
          nullable: true
          type: string
          format: uuid
        sms_uuid:
          nullable: true
          type: string
          maxLength: 64
        recipient_phone:
          nullable: true
          type: string
          maxLength: 16
        message_id:
          nullable: true
          type: string
          maxLength: 255
        trace_status:
          type: string
        failure_type:
          nullable: true
          type: string
        failure_reason:
          nullable: true
          type: string
        sent_datetime:
          nullable: true
          type: string
          format: date-time
        open_datetime:
          nullable: true
          type: string
          format: date-time
        reply_datetime:
          nullable: true
          type: string
          format: date-time
        links_click_datetime:
          nullable: true
          type: string
          format: date-time
        metadata:
          type: object

    MailingTraceList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingTrace'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    MailingFilter:
      type: object
      required:
        - id
        - name
        - target_model
        - domain
        - metadata
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          maxLength: 120
        target_model:
          type: string
        domain:
          type: object
        metadata:
          type: object

    MailingFilterBulkResult:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingFilter'
        total: { type: integer }
        failed: { type: integer }
        errors:
          type: array
          items: { type: string }

    CreateMailingFilterRequest:
      type: object
      required:
        - name
        - target_model
        - domain
        - metadata
      properties:
        name:
          type: string
          maxLength: 120
        target_model:
          type: string
        domain:
          type: object
        metadata:
          type: object

    UpdateMailingFilterRequest:
      type: object
      required:
        - name
        - target_model
        - domain
        - metadata
      properties:
        name:
          type: string
          maxLength: 120
        target_model:
          type: string
        domain:
          type: object
        metadata:
          type: object

    PatchMailingFilterRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 120
        target_model:
          type: string
        domain:
          type: object
        metadata:
          type: object

    MailingFilterList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/MailingFilter'
        meta:
          $ref: '#/components/schemas/PaginationMeta'

    PaginationMeta:
      type: object
      properties:
        total:
          type: integer
          example: 100
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 20
        total_pages:
          type: integer
          example: 5

    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        message:
          type: string
          example: Invalid input data
        details:
          type: object
          additionalProperties: true

  parameters:
    IdParam:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid

    PageParam:
      name: page
      in: query
      schema:
        type: integer
        minimum: 1
        default: 1

    PerPageParam:
      name: per_page
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

    SortByParam:
      name: sort_by
      in: query
      schema:
        type: string

    SortOrderParam:
      name: sort_order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: asc

  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  requestBodies:
    BatchIds:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [ids]
            properties:
              ids:
                type: array
                items: { type: string }

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []