Kairon Integrations API

openapi: 3.2.0
info:
  title: Kairon Integrations API
  description: B2B agentic go-to-market platform
  version: 0.0.0
  contact: {}
servers: []
security:
- api-key: []
tags:
- name: Integrations
paths:
  /api/integrations/unipile-mailbox:
    get:
      operationId: UnipileMailboxController_view
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Unipile mailbox controller view
      x-summary-source: derived
    delete:
      operationId: UnipileMailboxController_disconnect
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - Integrations
      summary: Unipile mailbox controller disconnect
      x-summary-source: derived
  /api/integrations/unipile-mailbox/link:
    post:
      operationId: UnipileMailboxController_link
      parameters:
      - name: origin
        required: true
        in: header
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Unipile mailbox controller link
      x-summary-source: derived
  /api/integrations/whatsapp:
    get:
      operationId: WhatsappAccountController_view
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Whatsapp account controller view
      x-summary-source: derived
    patch:
      operationId: WhatsappAccountController_update
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappAccountUpdateDto'
      responses:
        '204':
          description: ''
      tags:
      - Integrations
      summary: Whatsapp account controller update
      x-summary-source: derived
    delete:
      operationId: WhatsappAccountController_disconnect
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - Integrations
      summary: Whatsapp account controller disconnect
      x-summary-source: derived
  /api/integrations/whatsapp/link:
    post:
      operationId: WhatsappAccountController_link
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WhatsappLinkInputDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Whatsapp account controller link
      x-summary-source: derived
  /api/integrations/mcp:
    get:
      operationId: IntegrationsController_mcpConnection
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller mcp connection
      x-summary-source: derived
  /api/integrations/instantly:
    get:
      operationId: IntegrationsController_instantly
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller instantly
      x-summary-source: derived
    post:
      operationId: IntegrationsController_connectInstantly
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectInstantlyDto'
      responses:
        '201':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller connect instantly
      x-summary-source: derived
    delete:
      operationId: IntegrationsController_disconnectInstantly
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller disconnect instantly
      x-summary-source: derived
  /api/integrations/instantly/webhooks/repair:
    post:
      operationId: IntegrationsController_repairInstantlyWebhooks
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller repair instantly webhooks
      x-summary-source: derived
  /api/integrations/instantly/kairon-workspace:
    post:
      operationId: IntegrationsController_adoptKaironWorkspace
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdoptKaironWorkspaceDto'
      responses:
        '201':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller adopt kairon workspace
      x-summary-source: derived
    delete:
      operationId: IntegrationsController_releaseKaironWorkspace
      parameters: []
      responses:
        '204':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller release kairon workspace
      x-summary-source: derived
  /api/integrations/instantly/domains/search:
    post:
      operationId: IntegrationsController_searchSendingDomain
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchSendingDomainDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller search sending domain
      x-summary-source: derived
  /api/integrations/instantly/domains/pre-warmed:
    get:
      operationId: IntegrationsController_preWarmedSendingDomains
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller pre warmed sending domains
      x-summary-source: derived
  /api/integrations/instantly/domains/quote:
    post:
      operationId: IntegrationsController_quoteSendingDomain
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteSendingDomainDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller quote sending domain
      x-summary-source: derived
  /api/integrations/instantly/domains:
    get:
      operationId: IntegrationsController_listSendingDomains
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller list sending domains
      x-summary-source: derived
  /api/integrations/instantly/domains/buy:
    post:
      operationId: IntegrationsController_buySendingDomain
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuySendingDomainDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller buy sending domain
      x-summary-source: derived
  /api/integrations/instantly/domains/{domain}/mailboxes:
    get:
      operationId: IntegrationsController_provisionedMailboxes
      parameters:
      - name: domain
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller provisioned mailboxes
      x-summary-source: derived
  /api/integrations/instantly/domains/{domain}/attach:
    post:
      operationId: IntegrationsController_attachSendingDomain
      parameters:
      - name: domain
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller attach sending domain
      x-summary-source: derived
  /api/integrations/instantly/plan:
    get:
      operationId: IntegrationsController_emailPlan
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller email plan
      x-summary-source: derived
  /api/integrations/instantly/plan/requests:
    post:
      operationId: IntegrationsController_requestEmailPlan
      parameters: []
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller request email plan
      x-summary-source: derived
  /api/integrations/instantly/mailboxes:
    post:
      operationId: IntegrationsController_addOwnedMailbox
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOwnedMailboxDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller add owned mailbox
      x-summary-source: derived
  /api/integrations/instantly/mailboxes/oauth:
    post:
      operationId: IntegrationsController_startMailboxOauth
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartMailboxOauthDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller start mailbox oauth
      x-summary-source: derived
  /api/integrations/instantly/mailboxes/oauth/status:
    post:
      operationId: IntegrationsController_mailboxOauthStatus
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MailboxOauthStatusDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller mailbox oauth status
      x-summary-source: derived
  /api/integrations/instantly/domains/{domain}/check:
    post:
      operationId: IntegrationsController_checkSendingDomain
      parameters:
      - name: domain
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller check sending domain
      x-summary-source: derived
  /api/integrations/instantly/domains/{domain}/warmup:
    post:
      operationId: IntegrationsController_startSendingDomainWarmup
      parameters:
      - name: domain
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller start sending domain warmup
      x-summary-source: derived
  /api/integrations/instantly/mailboxes/daily-limit:
    put:
      operationId: IntegrationsController_setMailboxDailyLimit
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetMailboxDailyLimitDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller set mailbox daily limit
      x-summary-source: derived
  /api/integrations/instantly/email-format:
    put:
      operationId: IntegrationsController_setEmailFormat
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEmailFormatDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller set email format
      x-summary-source: derived
  /api/integrations/instantly/mailboxes/signature:
    put:
      operationId: IntegrationsController_setMailboxSignature
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetMailboxSignatureDto'
      responses:
        '200':
          description: ''
      tags:
      - Integrations
      summary: Integrations controller set mailbox signature
      x-summary-source: derived
components:
  schemas:
    SetMailboxSignatureDto:
      type: object
      properties:
        email:
          type: string
          format: email
          pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
          description: The mailbox, as `email_setup_get` lists it under its domain.
        signature:
          type: string
          maxLength: 1000
          description: 'The text Instantly puts under every campaign email this mailbox sends — a name, a role, a phone. Line breaks are kept. Empty removes it. No `{{ }}` variables. HTML only when `email_setup_get` says `emailFormat: "html"` (switch it with `email_format_set`); in plain-text sending it is refused.'
      required:
      - email
      - signature
    StartMailboxOauthDto:
      type: object
      properties:
        provider:
          type: string
          enum:
          - google
          - microsoft
      required:
      - provider
    ConnectInstantlyDto:
      type: object
      properties:
        apiKey:
          type: string
          minLength: 1
          maxLength: 500
        timeZone:
          type: string
          maxLength: 100
      required:
      - apiKey
    WhatsappAccountUpdateDto:
      type: object
      properties:
        dailyNewChatLimit:
          type: integer
          minimum: 1
          maximum: 30
      required:
      - dailyNewChatLimit
    SearchSendingDomainDto:
      type: object
      properties:
        domain:
          type: string
          minLength: 4
          maxLength: 253
          pattern: ^[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)*\.(com|org)$
          description: The domain name to buy and send from, like `acme-outreach.com`. Only `.com` and `.org` can be registered, and a name carrying a well-known trademark is refused. Not the customer's real website — a sending domain is a separate name, so a problem with it never touches their main domain's reputation.
      required:
      - domain
    AddOwnedMailboxDto:
      type: object
      properties:
        email:
          type: string
          maxLength: 254
          format: email
          pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
          description: The full address of a mailbox the customer already owns, like `ada@acme.com`.
        firstName:
          type: string
          minLength: 1
          maxLength: 100
          description: The mailbox owner's first name — it appears in the From line of every send.
        lastName:
          type: string
          minLength: 1
          maxLength: 100
          description: The mailbox owner's last name.
        provider:
          type: string
          enum:
          - google
          - microsoft
          - custom
          description: Who hosts the mailbox. `google` for Google Workspace or Gmail, `microsoft` for Microsoft 365 or Outlook — both fill in their own server settings. `custom` for anything else, and then all four host and port fields are required.
        password:
          type: string
          minLength: 1
          maxLength: 500
          description: An APP PASSWORD for the mailbox, not the account password. For Google the operator creates one in their Google account with 2-step verification on. Ask them for it directly and never invent one; it is passed straight to the sending provider and stored nowhere in Kairon.
        smtpHost:
          description: Outgoing mail server, `custom` provider only (Google and Microsoft are known).
          type: string
          maxLength: 253
        smtpPort:
          description: Outgoing mail port, `custom` provider only — usually 465 or 587.
          type: integer
          minimum: 1
          maximum: 65535
        imapHost:
          description: Incoming mail server, `custom` provider only.
          type: string
          maxLength: 253
        imapPort:
          description: Incoming mail port, `custom` provider only — usually 993.
          type: integer
          minimum: 1
          maximum: 65535
      required:
      - email
      - firstName
      - lastName
      - provider
      - password
    SetEmailFormatDto:
      type: object
      properties:
        format:
          type: string
          enum:
          - text
          - html
          description: '`text` sends plain text (the default). `html` sends formatted email, so mailbox signatures may use HTML — links, bold, a logo. It applies to every email the managed campaign sends. Switching back to `text` is refused while a mailbox signature still has HTML in it.'
      required:
      - format
    QuoteSendingDomainDto:
      type: object
      properties:
        domain:
          type: string
          minLength: 4
          maxLength: 253
          pattern: ^[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)*\.(com|org)$
          description: The domain name to buy and send from, like `acme-outreach.com`. Only `.com` and `.org` can be registered, and a name carrying a well-known trademark is refused. Not the customer's real website — a sending domain is a separate name, so a problem with it never touches their main domain's reputation.
        mailboxes:
          minItems: 1
          maxItems: 5
          type: array
          items:
            type: object
            properties:
              emailAddressPrefix:
                type: string
                minLength: 1
                maxLength: 64
                description: The part before the `@` — `ada` becomes `ada@the-domain.com`.
              firstName:
                type: string
                minLength: 1
                maxLength: 100
                description: The mailbox owner's first name, as it appears in the From line of every email sent from it.
              lastName:
                type: string
                minLength: 1
                maxLength: 100
                description: The mailbox owner's last name.
            required:
            - emailAddressPrefix
            - firstName
            - lastName
          description: The mailboxes to create on the domain — one to five, each a real person on the team, since a recipient who replies is replying to that name. More mailboxes means more sending capacity and more monthly cost.
        forwardingDomain:
          description: 'The customer''s real website, where a visitor to the sending domain is sent — `acme.com`. Worth setting: a sending domain that resolves to nothing is exactly what a suspicious recipient checks. Any extension, not just .com/.org. Ask the operator; never guess it from their email address.'
          type: string
      required:
      - domain
      - mailboxes
    MailboxOauthStatusDto:
      type: object
      properties:
        sessionId:
          type: string
          minLength: 1
      required:
      - sessionId
    WhatsappLinkInputDto:
      type: object
      properties:
        method:
          type: string
          enum:
          - qr
          - code
        phoneNumber:
          type: string
          minLength: 6
          maxLength: 32
      required:
      - method
    SetMailboxDailyLimitDto:
      type: object
      properties:
        email:
          type: string
          format: email
          pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
          description: The mailbox, as `email_setup_get` lists it under its domain.
        dailyLimit:
          type: integer
          minimum: 1
          maximum: 30
          description: Campaign emails this mailbox may send per day, 1 to 30. Some mailboxes allow fewer — `email_setup_get` names each one's `dailyLimitMax`. Warmup email does not count against it.
      required:
      - email
      - dailyLimit
    BuySendingDomainDto:
      type: object
      properties:
        domain:
          type: string
          minLength: 4
          maxLength: 253
          pattern: ^[a-z0-9][a-z0-9-]*(\.[a-z0-9-]+)*\.(com|org)$
          description: The domain name to buy and send from, like `acme-outreach.com`. Only `.com` and `.org` can be registered, and a name carrying a well-known trademark is refused. Not the customer's real website — a sending domain is a separate name, so a problem with it never touches their main domain's reputation.
        mailboxes:
          minItems: 1
          maxItems: 5
          type: array
          items:
            type: object
            properties:
              emailAddressPrefix:
                type: string
                minLength: 1
                maxLength: 64
                description: The part before the `@` — `ada` becomes `ada@the-domain.com`.
              firstName:
                type: string
                minLength: 1
                maxLength: 100
                description: The mailbox owner's first name, as it appears in the From line of every email sent from it.
              lastName:
                type: string
                minLength: 1
                maxLength: 100
                description: The mailbox owner's last name.
            required:
            - emailAddressPrefix
            - firstName
            - lastName
          description: The mailboxes to create on the domain — one to five, each a real person on the team, since a recipient who replies is replying to that name. More mailboxes means more sending capacity and more monthly cost.
        forwardingDomain:
          description: 'The customer''s real website, where a visitor to the sending domain is sent — `acme.com`. Worth setting: a sending domain that resolves to nothing is exactly what a suspicious recipient checks. Any extension, not just .com/.org. Ask the operator; never guess it from their email address.'
          type: string
        agreedTotal:
          type: number
          minimum: 0
          maximum: 10000
          description: The `dueNow` from the quote, in whole dollars, passed back unchanged. It is Instantly's own total, not what the operator pays (that is `upfrontUsd` once and `monthlyUsd` a month). The order is re-priced against the vendor immediately before buying and refused if the number moved, so a stale quote can never buy at a price nobody saw.
      required:
      - domain
      - mailboxes
      - agreedTotal
    AdoptKaironWorkspaceDto:
      type: object
      properties:
        kaironWorkspaceId:
          type: string
          format: uuid
          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
        timeZone:
          type: string
          maxLength: 100
      required:
      - kaironWorkspaceId
  securitySchemes:
    api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: 'A Kairon API key (Settings → Integrations → API access), sent as `x-api-key`. NOT an `Authorization: Bearer` token — that header belongs to the separate /mcp door and is ignored here.'
    session:
      type: apiKey
      in: cookie
      name: better-auth.session_token