openapi: 3.0.3
info:
  title: Snov.io API
  description: >-
    Snov.io is a sales automation and lead generation platform. The REST API
    enables programmatic access to email finding, domain search, email
    verification, drip campaign management, email warm-up, prospect management,
    CRM pipeline, and webhook subscriptions. Authentication uses OAuth 2.0
    client credentials to obtain short-lived Bearer tokens. All API operations
    consume credits from the account balance.
  version: '2.0'
  contact:
    name: Snov.io Support
    url: https://snov.io/knowledgebase/
  termsOfService: https://snov.io/terms-of-service/
  license:
    name: Proprietary
    url: https://snov.io/terms-of-service/
servers:
  - url: https://api.snov.io
    description: Snov.io API server
tags:
  - name: Authentication
    description: OAuth 2.0 token management
  - name: Domain Search
    description: Search for company information and email addresses by domain
  - name: Email Finder
    description: Find email addresses by name, LinkedIn, or domain
  - name: Email Verification
    description: Verify email deliverability and validity
  - name: Email Accounts
    description: Manage sender email accounts
  - name: Email Warm-up
    description: Manage email warm-up campaigns for improved deliverability
  - name: Campaigns
    description: Create and manage multi-channel outreach campaigns
  - name: Prospects
    description: Manage prospect records and lists
  - name: CRM Pipeline
    description: CRM pipeline and stage management
  - name: Webhooks
    description: Real-time event webhook subscriptions
  - name: User
    description: User account management
paths:

  # ─── Authentication ───────────────────────────────────────────────────────

  /v1/oauth/access_token:
    post:
      tags:
        - Authentication
      summary: Get access token
      description: >-
        Obtain a short-lived Bearer token using OAuth 2.0 client credentials
        flow. Tokens expire after 3600 seconds.
      operationId: getAccessToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - grant_type
                - client_id
                - client_secret
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  example: client_credentials
                client_id:
                  type: string
                  description: Client ID from account settings
                client_secret:
                  type: string
                  description: Client secret from account settings
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── Domain Search ────────────────────────────────────────────────────────

  /v2/domain-search/start:
    post:
      tags:
        - Domain Search
      summary: Start domain search
      description: >-
        Initiate an async domain search. Returns a task_hash to retrieve results.
        Costs 1 credit per unique domain request.
      operationId: startDomainSearch
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  description: Company domain name to search
                  example: example.com
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/domain-search/result/{task_hash}:
    get:
      tags:
        - Domain Search
      summary: Get domain search results
      description: Retrieve results of a previously started domain search task.
      operationId: getDomainSearchResult
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TaskHash'
      responses:
        '200':
          description: Domain search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainSearchResult'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /v2/domain-search/prospects/start:
    post:
      tags:
        - Domain Search
      summary: Start domain prospect search
      description: Initiate an async search for prospect profiles associated with a domain.
      operationId: startDomainProspectSearch
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  example: example.com
                positions:
                  type: array
                  items:
                    type: string
                  description: Filter by job positions
                  example:
                    - CEO
                    - CTO
                page:
                  type: integer
                  description: Page number for pagination
                  default: 1
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/domain-search/prospects/result/{task_hash}:
    get:
      tags:
        - Domain Search
      summary: Get domain prospect search results
      operationId: getDomainProspectSearchResult
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TaskHash'
      responses:
        '200':
          description: Prospect search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProspectListResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/domain-search/domain-emails/start:
    post:
      tags:
        - Domain Search
      summary: Start domain emails search
      description: Initiate an async search for all email addresses associated with a domain.
      operationId: startDomainEmailsSearch
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  example: example.com
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/domain-search/domain-emails/result/{task_hash}:
    get:
      tags:
        - Domain Search
      summary: Get domain emails search results
      operationId: getDomainEmailsSearchResult
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TaskHash'
      responses:
        '200':
          description: Domain emails results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailListResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/domain-search/generic-contacts/start:
    post:
      tags:
        - Domain Search
      summary: Start generic contacts search
      description: Initiate an async search for generic company contact addresses (e.g. info@, support@).
      operationId: startGenericContactsSearch
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  example: example.com
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/domain-search/generic-contacts/result/{task_hash}:
    get:
      tags:
        - Domain Search
      summary: Get generic contacts search results
      operationId: getGenericContactsSearchResult
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/TaskHash'
      responses:
        '200':
          description: Generic contacts results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailListResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/get-domain-emails-count:
    post:
      tags:
        - Domain Search
      summary: Check available emails count (free)
      description: Returns the count of available email addresses for a domain. Free endpoint.
      operationId: getDomainEmailsCount
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - domain
              properties:
                domain:
                  type: string
                  example: example.com
      responses:
        '200':
          description: Email count for domain
          content:
            application/json:
              schema:
                type: object
                properties:
                  domain:
                    type: string
                  result:
                    type: integer
                    description: Number of available emails
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── Email Finder ─────────────────────────────────────────────────────────

  /v2/emails-by-domain-by-name/start:
    post:
      tags:
        - Email Finder
      summary: Start find emails by name and domain
      description: >-
        Find email addresses by providing first name, last name, and domain.
        Costs 1 credit per valid or unknown email found.
      operationId: startFindEmailsByName
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rows
              properties:
                rows:
                  type: array
                  description: Array of name+domain rows to look up
                  items:
                    type: object
                    required:
                      - first_name
                      - last_name
                      - domain
                    properties:
                      first_name:
                        type: string
                        example: John
                      last_name:
                        type: string
                        example: Doe
                      domain:
                        type: string
                        example: example.com
                webhook_url:
                  type: string
                  format: uri
                  description: Optional webhook URL to receive results when ready
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/emails-by-domain-by-name/result:
    get:
      tags:
        - Email Finder
      summary: Get find emails by name results
      operationId: getFindEmailsByNameResult
      security:
        - bearerAuth: []
      parameters:
        - name: task_hash
          in: query
          required: true
          schema:
            type: string
          description: Task hash returned from the start endpoint
      responses:
        '200':
          description: Email finder results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailFinderResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/company-domain-by-name/start:
    post:
      tags:
        - Email Finder
      summary: Start find domain by company name
      description: >-
        Find company domains by company name. Costs 1 credit per domain found.
      operationId: startFindDomainByCompanyName
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - names
              properties:
                names:
                  type: array
                  items:
                    type: string
                  description: List of company names to look up
                  example:
                    - Acme Corp
                    - Example Inc
                webhook_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/company-domain-by-name/result:
    get:
      tags:
        - Email Finder
      summary: Get find domain by company name results
      operationId: getFindDomainByCompanyNameResult
      security:
        - bearerAuth: []
      parameters:
        - name: task_hash
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Company domain lookup results
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        domain:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/li-profiles-by-urls/start:
    post:
      tags:
        - Email Finder
      summary: Start LinkedIn profile enrichment
      description: >-
        Enrich LinkedIn profiles by URL. Costs 1 credit per profile retrieved.
      operationId: startLinkedInProfileEnrichment
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - urls
              properties:
                urls:
                  type: array
                  items:
                    type: string
                    format: uri
                  description: LinkedIn profile URLs
                  example:
                    - https://www.linkedin.com/in/johndoe
                webhook_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/li-profiles-by-urls/result:
    get:
      tags:
        - Email Finder
      summary: Get LinkedIn profile enrichment results
      operationId: getLinkedInProfileEnrichmentResult
      security:
        - bearerAuth: []
      parameters:
        - name: task_hash
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: LinkedIn profile enrichment results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProspectListResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/get-profile-by-email:
    post:
      tags:
        - Email Finder
      summary: Enrich profile by email
      description: >-
        Retrieve prospect profile information by email address. Costs 1 credit
        per request; free if no results are found.
      operationId: getProfileByEmail
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  example: john.doe@example.com
      responses:
        '200':
          description: Prospect profile data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProspectProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── Email Verification ───────────────────────────────────────────────────

  /v2/email-verification/start:
    post:
      tags:
        - Email Verification
      summary: Start email verification
      description: >-
        Initiate async verification of up to 10 email addresses. Returns a
        task_hash to poll for results.
      operationId: startEmailVerification
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emails
              properties:
                emails:
                  type: array
                  maxItems: 10
                  items:
                    type: string
                    format: email
                  example:
                    - john@example.com
                    - jane@example.com
                webhook_url:
                  type: string
                  format: uri
      responses:
        '200':
          description: Task started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStarted'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/email-verification/result:
    get:
      tags:
        - Email Verification
      summary: Get email verification results
      operationId: getEmailVerificationResult
      security:
        - bearerAuth: []
      parameters:
        - name: task_hash
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Email verification results
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailVerificationResult'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── Email Accounts ───────────────────────────────────────────────────────

  /v2/sender-accounts/emails:
    get:
      tags:
        - Email Accounts
      summary: List email accounts (free)
      description: Returns all connected sender email accounts with status information.
      operationId: listEmailAccounts
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of email accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - Email Accounts
      summary: Add email account
      description: Connect a new sender email account with SMTP/IMAP configuration.
      operationId: addEmailAccount
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailAccountCreate'
      responses:
        '201':
          description: Email account created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAccount'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/sender-accounts/emails/{id}:
    patch:
      tags:
        - Email Accounts
      summary: Update email account
      description: Update an existing sender email account configuration.
      operationId: updateEmailAccount
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Email account ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailAccountUpdate'
      responses:
        '200':
          description: Email account updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailAccount'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /v2/sender-accounts/check-sender-status:
    get:
      tags:
        - Email Accounts
      summary: Check sender account status
      description: >-
        Check SMTP and IMAP connection status for a sender account.
        Returns pending/valid/invalid status with error messages if applicable.
      operationId: checkSenderStatus
      security:
        - bearerAuth: []
      parameters:
        - name: sender_account_id
          in: query
          required: true
          schema:
            type: string
          description: ID of the sender account to check
      responses:
        '200':
          description: Sender account status
          content:
            application/json:
              schema:
                type: object
                properties:
                  smtp_status:
                    type: string
                    enum:
                      - pending
                      - valid
                      - invalid
                  imap_status:
                    type: string
                    enum:
                      - pending
                      - valid
                      - invalid
                  smtp_error:
                    type: string
                    nullable: true
                  imap_error:
                    type: string
                    nullable: true
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── Email Warm-up ────────────────────────────────────────────────────────

  /v2/warm-up:
    get:
      tags:
        - Email Warm-up
      summary: List warm-up campaigns
      description: Returns a paginated list of all email warm-up campaigns.
      operationId: listWarmUpCampaigns
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            enum:
              - 20
              - 50
              - 100
            default: 20
        - name: status
          in: query
          schema:
            type: string
            description: Filter by campaign status
      responses:
        '200':
          description: Paginated list of warm-up campaigns
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WarmUpCampaign'
                  total:
                    type: integer
                  page:
                    type: integer
                  per_page:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - Email Warm-up
      summary: Create warm-up campaign
      description: Create a new email warm-up campaign to improve deliverability scores.
      operationId: createWarmUpCampaign
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarmUpCampaignCreate'
      responses:
        '201':
          description: Warm-up campaign created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarmUpCampaign'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v2/warm-up/{id}:
    get:
      tags:
        - Email Warm-up
      summary: Get warm-up campaign
      description: Retrieve full details of a specific warm-up campaign.
      operationId: getWarmUpCampaign
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CampaignId'
      responses:
        '200':
          description: Warm-up campaign details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarmUpCampaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
        - Email Warm-up
      summary: Update warm-up campaign
      description: Update settings of an existing warm-up campaign.
      operationId: updateWarmUpCampaign
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CampaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WarmUpCampaignUpdate'
      responses:
        '200':
          description: Warm-up campaign updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WarmUpCampaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  # ─── Campaigns ────────────────────────────────────────────────────────────

  /v1/user-campaigns:
    get:
      tags:
        - Campaigns
      summary: List campaigns
      description: Returns all multi-channel outreach campaigns for the user.
      operationId: listCampaigns
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of campaigns
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/create-campaign:
    post:
      tags:
        - Campaigns
      summary: Create campaign
      description: Create a new multi-channel outreach campaign.
      operationId: createCampaign
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreate'
      responses:
        '201':
          description: Campaign created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/campaign/{id}:
    get:
      tags:
        - Campaigns
      summary: Get campaign
      description: Retrieve details of a specific campaign by ID.
      operationId: getCampaign
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CampaignId'
      responses:
        '200':
          description: Campaign details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - Campaigns
      summary: Update campaign
      description: Update an existing campaign's settings.
      operationId: updateCampaign
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CampaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CampaignCreate'
      responses:
        '200':
          description: Campaign updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Campaigns
      summary: Delete campaign
      description: Permanently delete a campaign.
      operationId: deleteCampaign
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CampaignId'
      responses:
        '204':
          description: Campaign deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/campaign/{id}/state:
    post:
      tags:
        - Campaigns
      summary: Change campaign state
      description: Start, pause, or stop a campaign.
      operationId: changeCampaignState
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CampaignId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - state
              properties:
                state:
                  type: string
                  enum:
                    - start
                    - pause
                    - stop
      responses:
        '200':
          description: State changed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/email-schedules:
    get:
      tags:
        - Campaigns
      summary: List email schedules
      description: Returns all available email send schedules.
      operationId: listEmailSchedules
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of email schedules
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/email-step-content:
    post:
      tags:
        - Campaigns
      summary: Create email step content
      description: Create content for a campaign email step.
      operationId: createEmailStepContent
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailStepContent'
      responses:
        '201':
          description: Email step content created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailStepContent'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/email-step-content/{id}:
    get:
      tags:
        - Campaigns
      summary: Get email step content
      operationId: getEmailStepContent
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Email step content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailStepContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
        - Campaigns
      summary: Update email step content
      operationId: updateEmailStepContent
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailStepContent'
      responses:
        '200':
          description: Email step content updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailStepContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Campaigns
      summary: Delete email step content
      operationId: deleteEmailStepContent
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '204':
          description: Email step content deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/recipient-status:
    get:
      tags:
        - Campaigns
      summary: Check recipient status
      description: Check the campaign status of a specific recipient.
      operationId: getRecipientStatus
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
        - name: email
          in: query
          required: true
          schema:
            type: string
            format: email
      responses:
        '200':
          description: Recipient status
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                  status:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - Campaigns
      summary: Change recipient status
      description: Update the campaign status of a recipient.
      operationId: changeRecipientStatus
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - campaign_id
                - email
                - status
              properties:
                campaign_id:
                  type: integer
                email:
                  type: string
                  format: email
                status:
                  type: string
      responses:
        '200':
          description: Status changed
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/finished-prospects:
    get:
      tags:
        - Campaigns
      summary: List completed prospects
      description: Returns prospects who have completed all campaign steps.
      operationId: listFinishedProspects
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Completed prospects list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Prospect'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/do-not-email-list:
    post:
      tags:
        - Campaigns
      summary: Add to do-not-email list
      description: Add email addresses to a do-not-email suppression list.
      operationId: addToDoNotEmailList
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - emails
              properties:
                emails:
                  type: array
                  items:
                    type: string
                    format: email
                list_id:
                  type: integer
      responses:
        '200':
          description: Emails added to suppression list
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/do-not-email-lists:
    get:
      tags:
        - Campaigns
      summary: List do-not-email lists
      description: Returns all do-not-email suppression lists for the account.
      operationId: listDoNotEmailLists
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of suppression lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        count:
                          type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/campaign-analytics:
    get:
      tags:
        - Campaigns
      summary: Get campaign analytics
      description: Returns aggregate analytics data for a campaign.
      operationId: getCampaignAnalytics
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Campaign analytics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CampaignAnalytics'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/campaign-progress:
    get:
      tags:
        - Campaigns
      summary: Get campaign progress
      description: Returns progress statistics for a running campaign.
      operationId: getCampaignProgress
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Campaign progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                  sent:
                    type: integer
                  pending:
                    type: integer
                  finished:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/campaign-recipients-activity:
    get:
      tags:
        - Campaigns
      summary: Get recipients activity report
      description: Returns detailed activity report for campaign recipients.
      operationId: getCampaignRecipientsActivity
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Recipients activity report
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecipientActivity'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/emails-sent:
    get:
      tags:
        - Campaigns
      summary: Get sent emails
      description: Returns list of emails sent in a campaign.
      operationId: getSentEmails
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Sent emails
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SentEmail'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/emails-opens:
    get:
      tags:
        - Campaigns
      summary: Get campaign opens
      description: Returns email open events for a campaign.
      operationId: getCampaignOpens
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Campaign opens
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/emails-clicks:
    get:
      tags:
        - Campaigns
      summary: Get campaign link clicks
      description: Returns link click events for a campaign.
      operationId: getCampaignClicks
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Campaign link clicks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailEvent'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/campaign-replies:
    get:
      tags:
        - Campaigns
      summary: Get all campaign replies
      description: Returns all reply events across all email steps in a campaign.
      operationId: getCampaignReplies
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Campaign replies
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailReply'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/campaign-email-replies:
    get:
      tags:
        - Campaigns
      summary: Get campaign email replies
      description: Returns reply events scoped to a specific email step.
      operationId: getCampaignEmailReplies
      security:
        - bearerAuth: []
      parameters:
        - name: campaign_id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Campaign email replies
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailReply'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── Prospects ────────────────────────────────────────────────────────────

  /v1/add-prospect:
    post:
      tags:
        - Prospects
      summary: Add prospect to list
      description: Add a new prospect record to a prospect list.
      operationId: addProspect
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProspectCreate'
      responses:
        '201':
          description: Prospect added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/find-prospect-by-id:
    post:
      tags:
        - Prospects
      summary: Find prospect by ID
      operationId: findProspectById
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: string
                  description: Prospect ID
      responses:
        '200':
          description: Prospect details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/find-prospect-by-email:
    post:
      tags:
        - Prospects
      summary: Find prospect by email
      operationId: findProspectByEmail
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
      responses:
        '200':
          description: Prospect details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prospect'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

  /v1/prospect-custom-fields:
    get:
      tags:
        - Prospects
      summary: Get prospect custom fields
      description: Returns all custom fields defined for prospects.
      operationId: getProspectCustomFields
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Custom fields
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        name:
                          type: string
                        type:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/user-lists:
    get:
      tags:
        - Prospects
      summary: List prospect lists
      description: Returns all prospect lists for the user.
      operationId: listProspectLists
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Prospect lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProspectList'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/view-prospects-in-list:
    post:
      tags:
        - Prospects
      summary: View prospects in list
      description: Returns prospects belonging to a specific prospect list.
      operationId: viewProspectsInList
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - list_id
              properties:
                list_id:
                  type: integer
                page:
                  type: integer
                  default: 1
                per_page:
                  type: integer
                  default: 20
      responses:
        '200':
          description: Prospects in list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Prospect'
                  total:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/create-prospect-list:
    post:
      tags:
        - Prospects
      summary: Create prospect list
      description: Create a new prospect list.
      operationId: createProspectList
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: Name for the new prospect list
      responses:
        '201':
          description: Prospect list created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProspectList'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── CRM Pipeline ─────────────────────────────────────────────────────────

  /v1/pipelines:
    get:
      tags:
        - CRM Pipeline
      summary: List pipelines
      description: Returns all CRM pipelines for the account.
      operationId: listPipelines
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of pipelines
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pipeline'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/pipeline-stages:
    get:
      tags:
        - CRM Pipeline
      summary: List pipeline stages
      description: Returns all stages within CRM pipelines.
      operationId: listPipelineStages
      security:
        - bearerAuth: []
      parameters:
        - name: pipeline_id
          in: query
          schema:
            type: integer
          description: Filter stages by pipeline ID
      responses:
        '200':
          description: List of pipeline stages
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PipelineStage'
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── User Account ─────────────────────────────────────────────────────────

  /v1/user-balance:
    get:
      tags:
        - User
      summary: Check user balance
      description: Returns the current credit balance and usage information for the account.
      operationId: getUserBalance
      security:
        - bearerAuth: []
      responses:
        '200':
          description: User balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: integer
                    description: Current credit balance
                  used:
                    type: integer
                    description: Credits used this period
                  total:
                    type: integer
                    description: Total credits in plan
        '401':
          $ref: '#/components/responses/Unauthorized'

  # ─── Webhooks ─────────────────────────────────────────────────────────────

  /v1/webhooks:
    get:
      tags:
        - Webhooks
      summary: List webhooks
      description: Returns all webhook subscriptions for the account.
      operationId: listWebhooks
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
        - Webhooks
      summary: Add webhook
      description: Create a new webhook subscription for real-time event notifications.
      operationId: addWebhook
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /v1/webhooks/{id}:
    put:
      tags:
        - Webhooks
      summary: Update webhook
      description: Update an existing webhook subscription (e.g. change status or URL).
      operationId: updateWebhook
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreate'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
        - Webhooks
      summary: Delete webhook
      description: Remove a webhook subscription.
      operationId: deleteWebhook
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '204':
          description: Webhook deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Obtain a Bearer token via POST /v1/oauth/access_token using client
        credentials. Tokens expire after 3600 seconds.

  parameters:
    TaskHash:
      name: task_hash
      in: path
      required: true
      schema:
        type: string
      description: Task hash returned from the corresponding start endpoint
    CampaignId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: Campaign ID
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: Resource ID

  responses:
    BadRequest:
      description: Bad request — missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — missing or invalid Bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message

    AccessToken:
      type: object
      properties:
        access_token:
          type: string
          description: Bearer token for API authentication
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Token lifetime in seconds
          example: 3600

    TaskStarted:
      type: object
      properties:
        task_hash:
          type: string
          description: Unique identifier for the async task; use to poll for results
        status:
          type: string
          description: Current task status

    DomainSearchResult:
      type: object
      properties:
        status:
          type: string
        data:
          type: object
          properties:
            domain:
              type: string
            company_name:
              type: string
            industry:
              type: string
            size:
              type: string
            prospect_count:
              type: integer
            email_count:
              type: integer
            related_domains:
              type: array
              items:
                type: string

    EmailFinderResult:
      type: object
      properties:
        status:
          type: string
        data:
          type: array
          items:
            type: object
            properties:
              first_name:
                type: string
              last_name:
                type: string
              domain:
                type: string
              email:
                type: string
                format: email
              confidence:
                type: integer
                description: Confidence score 0-100
              status:
                type: string
                description: Email status (valid/unknown/not_valid)

    EmailVerificationResult:
      type: object
      properties:
        email:
          type: string
          format: email
        status:
          type: string
          enum:
            - valid
            - unknown
            - not_valid
        format_valid:
          type: boolean
        mx_valid:
          type: boolean
        disposable:
          type: boolean
        gibberish:
          type: boolean

    EmailListResult:
      type: object
      properties:
        status:
          type: string
        data:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
                format: email
              first_name:
                type: string
              last_name:
                type: string
              position:
                type: string
              confidence:
                type: integer

    ProspectListResult:
      type: object
      properties:
        status:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProspectProfile'

    ProspectProfile:
      type: object
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        position:
          type: string
        company:
          type: string
        location:
          type: string
        industry:
          type: string
        social:
          type: object
          properties:
            linkedin:
              type: string
              format: uri
            twitter:
              type: string
              format: uri
        job_history:
          type: array
          items:
            type: object
            properties:
              title:
                type: string
              company:
                type: string
              start_date:
                type: string
              end_date:
                type: string

    EmailAccount:
      type: object
      properties:
        id:
          type: string
        email_from:
          type: string
          format: email
        sender_name:
          type: string
        smtp_status:
          type: string
          enum:
            - pending
            - valid
            - invalid
        imap_status:
          type: string
          enum:
            - pending
            - valid
            - invalid
        provider:
          type: string
        limitation:
          type: integer
          description: Daily sending limit

    EmailAccountCreate:
      type: object
      required:
        - sender_name
        - email_from
        - password
        - smtp
      properties:
        sender_name:
          type: string
        email_from:
          type: string
          format: email
        password:
          type: string
        smtp:
          type: object
          required:
            - host
            - port
            - encryption
          properties:
            host:
              type: string
            port:
              type: integer
            encryption:
              type: string
              enum:
                - ssl
                - tls
                - none
        imap:
          type: object
          properties:
            host:
              type: string
            port:
              type: integer
            encryption:
              type: string
              enum:
                - ssl
                - tls
                - none
        reply_to:
          type: string
          format: email
        limitation:
          type: integer
        delay:
          type: integer
          description: Delay between sends in seconds
        signature:
          type: string
        bcc_email:
          type: string
          format: email
        tags:
          type: array
          items:
            type: string
        timezoneId:
          type: string

    EmailAccountUpdate:
      type: object
      properties:
        sender_name:
          type: string
        email_from:
          type: string
          format: email
        password:
          type: string
        smtp:
          type: object
          properties:
            host:
              type: string
            port:
              type: integer
            encryption:
              type: string
        imap:
          type: object
          properties:
            host:
              type: string
            port:
              type: integer
            encryption:
              type: string
        delay:
          type: integer
        signature:
          type: string
        bcc_email:
          type: string
          format: email
        tags:
          type: array
          items:
            type: string

    WarmUpCampaign:
      type: object
      properties:
        id:
          type: integer
        email_account_id:
          type: string
        status:
          type: string
        strategy:
          type: string
          enum:
            - progressive
            - steady
        per_day:
          type: integer
        reply_rate:
          type: integer
        campaign_deadline:
          type: string
          format: date
        deliverability_score:
          type: number
          format: float

    WarmUpCampaignCreate:
      type: object
      required:
        - email_account_id
        - per_day
      properties:
        email_account_id:
          type: string
        per_day:
          type: integer
          description: Number of warm-up emails per day
        strategy:
          type: string
          enum:
            - progressive
            - steady
          default: progressive
        from:
          type: integer
          description: Starting daily count for progressive strategy
        increase:
          type: integer
          description: Daily increase amount for progressive strategy
        email_content:
          type: string
          enum:
            - default
            - custom
        subject:
          type: string
        body:
          type: string
        reply_rate:
          type: integer
          description: Percentage of warm-up emails to reply to (0-100)
        campaign_deadline:
          type: string
          format: date
        providers:
          type: array
          items:
            type: string
        send_to_paid_domain:
          type: boolean
        enable_ctd:
          type: boolean
        enable_proxy:
          type: boolean
        schedule_id:
          type: integer
        template_name:
          type: string

    WarmUpCampaignUpdate:
      type: object
      properties:
        status:
          type: string
          enum:
            - active
            - paused
            - stopped
        strategy:
          type: string
          enum:
            - progressive
            - steady
        per_day:
          type: integer
        from:
          type: integer
        increase:
          type: integer
        email_content:
          type: string
        reply_rate:
          type: integer
        campaign_deadline:
          type: string
          format: date
        make_endless:
          type: boolean
        providers:
          type: array
          items:
            type: string
        enable_ctd:
          type: boolean
        enable_proxy:
          type: boolean

    Campaign:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: string
          enum:
            - draft
            - active
            - paused
            - stopped
            - finished
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CampaignCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        schedule_id:
          type: integer
        sender_account_id:
          type: string
        track_opens:
          type: boolean
        track_clicks:
          type: boolean

    EmailStepContent:
      type: object
      properties:
        id:
          type: integer
        campaign_id:
          type: integer
        subject:
          type: string
        body:
          type: string
        step_number:
          type: integer
        delay_days:
          type: integer

    CampaignAnalytics:
      type: object
      properties:
        total_recipients:
          type: integer
        sent:
          type: integer
        delivered:
          type: integer
        opened:
          type: integer
        clicked:
          type: integer
        replied:
          type: integer
        bounced:
          type: integer
        unsubscribed:
          type: integer
        open_rate:
          type: number
          format: float
        click_rate:
          type: number
          format: float
        reply_rate:
          type: number
          format: float

    RecipientActivity:
      type: object
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        status:
          type: string
        opened:
          type: boolean
        clicked:
          type: boolean
        replied:
          type: boolean
        last_activity:
          type: string
          format: date-time

    SentEmail:
      type: object
      properties:
        id:
          type: integer
        recipient_email:
          type: string
          format: email
        subject:
          type: string
        sent_at:
          type: string
          format: date-time

    EmailEvent:
      type: object
      properties:
        email:
          type: string
          format: email
        occurred_at:
          type: string
          format: date-time
        step_number:
          type: integer

    EmailReply:
      type: object
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        reply_text:
          type: string
        replied_at:
          type: string
          format: date-time

    Prospect:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        position:
          type: string
        company:
          type: string
        location:
          type: string
        custom_fields:
          type: object
          additionalProperties: true

    ProspectCreate:
      type: object
      required:
        - email
        - list_id
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        position:
          type: string
        company:
          type: string
        company_website:
          type: string
          format: uri
        location:
          type: string
        phone:
          type: string
        linkedin:
          type: string
          format: uri
        list_id:
          type: integer
        custom_fields:
          type: object
          additionalProperties: true

    ProspectList:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        count:
          type: integer
        created_at:
          type: string
          format: date-time

    Pipeline:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        stages_count:
          type: integer

    PipelineStage:
      type: object
      properties:
        id:
          type: integer
        pipeline_id:
          type: integer
        name:
          type: string
        position:
          type: integer

    Webhook:
      type: object
      properties:
        id:
          type: integer
        url:
          type: string
          format: uri
        event:
          type: string
        status:
          type: string
          enum:
            - active
            - inactive
        created_at:
          type: string
          format: date-time

    WebhookCreate:
      type: object
      required:
        - url
        - event
      properties:
        url:
          type: string
          format: uri
          description: URL to receive webhook POST requests
        event:
          type: string
          description: Event type to subscribe to
        status:
          type: string
          enum:
            - active
            - inactive
          default: active