Instantly Campaign API

openapi: 3.2.0
info:
  title: Explorer Campaign API
  description: The entire API V2 documentation is interactive and can be tested here. To the right side of every endpoint you will see a box with an example request. You can click on the "Try it" button to send a request to the server right from the docs. You will need to provide an API key by clicking the `ApiKeyAuth_token` blue text.
  version: 2.0.0
servers:
- url: https://api.instantly.ai
  description: Instantly API Server
security:
- ApiKeyAuth: []
tags:
- name: Campaign
  description: A campaign that can be sent to a list of recipients
  x-group: Campaign
paths:
  /api/v2/campaigns:
    post:
      operationId: createCampaign
      summary: Create campaign
      tags:
      - Campaign
      description: 'Requires one of the following scopes: `campaigns:create`, `campaigns:all`, `all:create`, `all:all`'
      requestBody:
        content:
          application/json:
            schema:
              title: CreateCampaign
              description: The Campaign to create
              type: object
              properties:
                name:
                  type: string
                  description: Name of the campaign
                  example: My First Campaign
                pl_value:
                  type:
                  - number
                  - 'null'
                  description: Value of every positive lead
                  example: 100
                is_evergreen:
                  type:
                  - boolean
                  - 'null'
                  description: Whether the campaign is evergreen
                  example: false
                campaign_schedule:
                  type: object
                  description: Campaign schedule
                  properties:
                    start_date:
                      type:
                      - string
                      - 'null'
                      format: date
                      description: Start date in YYYY-MM-DD format. Uses the campaign's timezone.
                      example: '2025-09-25'
                    end_date:
                      type:
                      - string
                      - 'null'
                      format: date
                      description: End date in YYYY-MM-DD format. Uses the campaign's timezone.
                      example: '2025-09-25'
                    schedules:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            example: My Schedule
                          timing:
                            type: object
                            properties:
                              from:
                                type: string
                                pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$
                                example: 09:00
                              to:
                                type: string
                                pattern: ^([01][0-9]|2[0-3]):([0-5][0-9])$
                                example: '17:00'
                            required:
                            - from
                            - to
                          days:
                            type: object
                            minProperties: 1
                            properties:
                              '0':
                                type: boolean
                                example: true
                              '1':
                                type: boolean
                                example: true
                              '2':
                                type: boolean
                                example: true
                              '3':
                                type: boolean
                                example: true
                              '4':
                                type: boolean
                                example: true
                              '5':
                                type: boolean
                                example: false
                              '6':
                                type: boolean
                                example: false
                          timezone:
                            type: string
                            enum:
                            - Etc/GMT+12
                            - Etc/GMT+11
                            - Etc/GMT+10
                            - America/Anchorage
                            - America/Dawson
                            - America/Creston
                            - America/Chihuahua
                            - America/Boise
                            - America/Belize
                            - America/Chicago
                            - America/Bahia_Banderas
                            - America/Regina
                            - America/Bogota
                            - America/Detroit
                            - America/Indiana/Marengo
                            - America/Caracas
                            - America/Asuncion
                            - America/Glace_Bay
                            - America/Campo_Grande
                            - America/Anguilla
                            - America/Santiago
                            - America/St_Johns
                            - America/Sao_Paulo
                            - America/Argentina/La_Rioja
                            - America/Araguaina
                            - America/Godthab
                            - America/Montevideo
                            - America/Bahia
                            - America/Noronha
                            - America/Scoresbysund
                            - Atlantic/Cape_Verde
                            - Africa/Casablanca
                            - America/Danmarkshavn
                            - Europe/Isle_of_Man
                            - Atlantic/Canary
                            - Africa/Abidjan
                            - Arctic/Longyearbyen
                            - Europe/Belgrade
                            - Africa/Ceuta
                            - Europe/Sarajevo
                            - Africa/Algiers
                            - Africa/Windhoek
                            - Asia/Nicosia
                            - Asia/Beirut
                            - Africa/Cairo
                            - Asia/Damascus
                            - Europe/Bucharest
                            - Africa/Blantyre
                            - Europe/Helsinki
                            - Europe/Istanbul
                            - Asia/Jerusalem
                            - Africa/Tripoli
                            - Asia/Amman
                            - Asia/Baghdad
                            - Europe/Kaliningrad
                            - Asia/Aden
                            - Africa/Addis_Ababa
                            - Europe/Kirov
                            - Europe/Astrakhan
                            - Asia/Tehran
                            - Asia/Dubai
                            - Asia/Baku
                            - Indian/Mahe
                            - Asia/Tbilisi
                            - Asia/Yerevan
                            - Asia/Kabul
                            - Antarctica/Mawson
                            - Asia/Yekaterinburg
                            - Asia/Karachi
                            - Asia/Kolkata
                            - Asia/Colombo
                            - Asia/Kathmandu
                            - Antarctica/Vostok
                            - Asia/Dhaka
                            - Asia/Rangoon
                            - Antarctica/Davis
                            - Asia/Novokuznetsk
                            - Asia/Hong_Kong
                            - Asia/Krasnoyarsk
                            - Asia/Brunei
                            - Australia/Perth
                            - Asia/Taipei
                            - Asia/Choibalsan
                            - Asia/Irkutsk
                            - Asia/Dili
                            - Asia/Pyongyang
                            - Australia/Adelaide
                            - Australia/Darwin
                            - Australia/Brisbane
                            - Australia/Melbourne
                            - Antarctica/DumontDUrville
                            - Australia/Currie
                            - Asia/Chita
                            - Antarctica/Macquarie
                            - Asia/Sakhalin
                            - Pacific/Auckland
                            - Etc/GMT-12
                            - Pacific/Fiji
                            - Asia/Anadyr
                            - Asia/Kamchatka
                            - Etc/GMT-13
                            - Pacific/Apia
                            example: Etc/GMT+12
                        required:
                        - name
                        - timing
                        - days
                        - timezone
                      minItems: 1
                  required:
                  - schedules
                sequences:
                  type: array
                  description: List of sequences (the actual email copy). Even though this field is an array, only the first element is used, so please provide only one array item, and add the steps to that array
                  items:
                    type: object
                    properties:
                      steps:
                        type: array
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              enum:
                              - email
                              x-enumDescriptions:
                                email: This steps represents an email
                              description: Type of step. This has to be 'email' always - it's the only supported type for now
                              example: email
                            delay:
                              type: number
                              description: The delay value before sending the NEXT email. The unit is determined by the delay_unit field (defaults to days).
                              example: 2
                            delay_unit:
                              type: string
                              enum:
                              - minutes
                              - hours
                              - days
                              default: days
                              description: The unit of time for the delay value (minutes, hours, or days). Defaults to days for backward compatibility.
                              example: days
                            pre_delay:
                              type: number
                              description: The delay value before sending the FIRST email in a subsequence. **Only applicable to subsequences** - this field is ignored for regular campaigns. The unit is determined by the pre_delay_unit field (defaults to days).
                              example: 2
                            pre_delay_unit:
                              type: string
                              enum:
                              - minutes
                              - hours
                              - days
                              default: days
                              description: The unit of time for the pre_delay value (minutes, hours, or days). **Only applicable to subsequences** - this field is ignored for regular campaigns. Defaults to days for backward compatibility.
                              example: days
                            variants:
                              type: array
                              items:
                                type: object
                                properties:
                                  subject:
                                    type: string
                                    example: Hello {{firstName}}
                                  body:
                                    type: string
                                    description: Email body HTML. Use `<br/>` tags for delivered email line breaks.
                                    example: Hey {{firstName}},<br/><br/>I hope you are doing well.
                                  v_disabled:
                                    type: boolean
                                    description: Whether this variant is disabled. By default, all the variants are enabled. Please set this to true if you want to disable this variant
                                    example: true
                                required:
                                - subject
                                - body
                          required:
                          - type
                          - delay
                          - variants
                    required:
                    - steps
                email_gap:
                  type:
                  - number
                  - 'null'
                  description: The gap between emails in minutes
                  example: 10
                random_wait_max:
                  type:
                  - number
                  - 'null'
                  description: The maximum random wait time in minutes
                  example: 10
                text_only:
                  type:
                  - boolean
                  - 'null'
                  description: Whether the campaign is text only
                  example: false
                first_email_text_only:
                  type:
                  - boolean
                  - 'null'
                  description: Whether the campaign is send the first email as a text only
                  example: false
                email_list:
                  type: array
                  description: List of accounts to use for sending emails
                  items:
                    type: string
                    example: john@doe.com
                daily_limit:
                  type:
                  - number
                  - 'null'
                  description: The daily limit for sending emails
                  example: 100
                stop_on_reply:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to stop the campaign on reply
                  example: false
                email_tag_list:
                  type: array
                  description: List of tags to use for sending emails
                  items:
                    type: string
                    format: uuid
                    example: 019ffad2-5c4b-761a-9bc4-059ac4b3a8a9
                link_tracking:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to track links in emails
                  example: true
                open_tracking:
                  type: boolean
                  description: Whether to track opens in emails
                  example: true
                stop_on_auto_reply:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to stop the campaign on auto reply
                  example: false
                daily_max_leads:
                  type:
                  - integer
                  - 'null'
                  description: The daily maximum new leads to contact
                  minimum: 0
                  example: 100
                prioritize_new_leads:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to prioritize new leads
                  example: false
                auto_variant_select:
                  type:
                  - object
                  - 'null'
                  description: Auto variant select settings
                  properties:
                    trigger:
                      type: string
                      enum:
                      - reply_rate
                      - click_rate
                      - open_rate
                      examples:
                      - click_rate
                      example: click_rate
                  required:
                  - trigger
                match_lead_esp:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to match leads by ESP
                  example: false
                stop_for_company:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to stop the campaign for the entire company(domain) when a lead replies
                  example: false
                insert_unsubscribe_header:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to insert an unsubscribe header in emails
                  example: false
                allow_risky_contacts:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to allow risky contacts
                  example: false
                disable_bounce_protect:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to disable bounce protection
                  example: false
                limit_emails_per_company_override:
                  type:
                  - object
                  - 'null'
                  description: Overrides the workspace-wide limit emails per company setting for this campaign.
                  properties:
                    mode:
                      type: string
                      enum:
                      - custom
                      - disabled
                      examples:
                      - custom
                      example: custom
                    daily_limit:
                      type: number
                      minimum: 1
                      examples:
                      - 3
                      example: 3
                    scope:
                      type: string
                      enum:
                      - per_campaign
                      - across_workspace
                      examples:
                      - per_campaign
                      example: per_campaign
                  required:
                  - mode
                cc_list:
                  type: array
                  description: List of accounts to CC on emails
                  items:
                    type: string
                    format: email
                    example: john@doe.com
                bcc_list:
                  type: array
                  description: List of accounts to BCC on emails
                  items:
                    type: string
                    format: email
                    example: john@doe.com
                owned_by:
                  type:
                  - string
                  - 'null'
                  description: Owner ID
                  format: uuid
                  example: 019ffad2-5c4b-761a-9bc4-059c036e479a
                ai_sdr_id:
                  type:
                  - string
                  - 'null'
                  description: AI Sales Agent ID that created this campaign
                  format: uuid
                  example: 019ffad2-5c4b-761a-9bc4-059dc9a58653
                provider_routing_rules:
                  type: array
                  description: Auto variant select settings
                  items:
                    type: object
                    properties:
                      action:
                        type: string
                        enum:
                        - send
                        - do_not_send
                        example: send
                      recipient_esp:
                        type: array
                        items:
                          type: string
                          enum:
                          - all
                          - google
                          - outlook
                          - other
                          example: all
                      sender_esp:
                        type: array
                        items:
                          type: string
                          enum:
                          - all
                          - google
                          - outlook
                          - other
                          example: all
                  required:
                  - action
                  - recipient_esp
                  - sender_esp
              required:
              - name
              - campaign_schedule
              additionalProperties: false
        required: true
        description: The Campaign to create
      responses:
        '200':
          description: The Campaign
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Campaign'
        '400':
          description: Invalid request body (e.g. missing required fields, or invalid field values)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 400
                    examples:
                    - 400
                    example: 400
                  error:
                    type: string
                    enum:
                    - Bad Request
                    examples:
                    - Bad Request
                    example: Bad Request
                  message:
                    type: string
                    examples:
                    - body must have required property 'name'
                    example: body must have required property 'name'
                required:
                - statusCode
                - error
                - message
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Payment Required
                    examples:
                    - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                    - Workspace does not have an active paid plan
                    example: Workspace does not have an active paid plan
                required:
                - statusCode
                - error
                - message
        '404':
          description: The requested resource was not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 404
                    examples:
                    - 404
                    example: 404
                  error:
                    type: string
                    enum:
                    - Not Found
                    examples:
                    - Not Found
                    example: Not Found
                  message:
                    type: string
                    examples:
                    - Resource not found
                    example: Resource not found
                required:
                - statusCode
                - error
                - message
        '429':
          description: You have exceeded the rate limit. Please check the rate limit docs for more information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 429
                    examples:
                    - 429
                    example: 429
                  error:
                    type: string
                    enum:
                    - Too Many Requests
                    examples:
                    - Too Many Requests
                    example: Too Many Requests
                  message:
                    type: string
                    examples:
                    - Rate limit exceeded
                    example: Rate limit exceeded
                required:
                - statusCode
                - error
                - message
    get:
      operationId: listCampaign
      summary: List campaign
      tags:
      - Campaign
      description: 'Requires one of the following scopes: `campaigns:read`, `campaigns:all`, `all:read`, `all:all`'
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          example: 10
        example: 10
        in: query
        name: limit
        required: false
        description: The number of items to return
      - schema:
          type: string
          example: 01956fbd-0eb1-72db-a565-82977a586084
        example: 01956fbd-0eb1-72db-a565-82977a586084
        in: query
        name: starting_after
        required: false
        description: The ID of the last item in the previous page - used for pagination. You can use the value of the `next_starting_after` field from the previous response.
      - schema:
          type: string
          example: Summer Sale Campaign
        example: Summer Sale Campaign
        in: query
        name: search
        required: false
        description: Search by campaign name
      - schema:
          type: string
          example: 019ffad2-9b9f-79cc-82ca-2b31778b13de,019ffad2-9b9f-79cc-82ca-2b3271f21ade
        example: 019ffad2-9b9f-79cc-82ca-2b31778b13de,019ffad2-9b9f-79cc-82ca-2b3271f21ade
        in: query
        name: tag_ids
        required: false
        description: Filter campaigns by tag ids. Returns campaigns that have any of the specified tags assigned. You can specify multiple tag ids by separating them with a comma.
      - schema:
          type: string
          format: uuid
          example: 019ffad2-9b9f-79cc-82ca-2b33348f0860
        example: 019ffad2-9b9f-79cc-82ca-2b33348f0860
        in: query
        name: ai_sales_agent_id
        required: false
        description: Filter campaigns by AI Sales Agent ID. Returns campaigns that were created by the specified AI Sales Agent.
      - schema:
          type: number
          enum:
          - -99
          - -1
          - -2
          - 0
          - 1
          - 2
          - 3
          - 4
          x-enumDescriptions:
            '0': Draft
            '1': Active
            '2': Paused
            '3': Completed
            '4': Running Subsequences
            '-99': Account Suspended
            '-1': Accounts Unhealthy
            '-2': Bounce Protect
          example: 1
        examples:
          '1':
            value: 1
          '2':
            value: 2
        in: query
        name: status
        required: false
        description: Filter campaigns by status using the campaign status enum value (e.g., ACTIVE, PAUSED).
      - schema:
          type: number
          enum:
          - -99
          - -1
          - -2
          - 0
          - 1
          - 2
          - 3
          - 4
          x-enumDescriptions:
            '0': Draft
            '1': Active
            '2': Paused
            '3': Completed
            '4': Running Subsequences
            '-99': Account Suspended
            '-1': Accounts Unhealthy
            '-2': Bounce Protect
          example: 1
        example: 1
        in: query
        name: exclude_status
        required: false
        description: Exclude campaigns with this status using the campaign status enum value (e.g., exclude ACTIVE to list only campaigns that are not currently active).
      responses:
        '200':
          description: The list of Campaign
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: The list of Campaign
                    items:
                      $ref: '#/components/schemas/Campaign'
                  next_starting_after:
                    type: string
                    examples:
                    - 019ffad2-9ba0-7ae4-8d2d-0588c0a8454e
                    - '2026-08-13T11:12:14.240Z'
                    description: The filter for getting the next items after this one, this could either be a UUID, a timestamp, on an email depending on the specific API
                    example: 019ffad2-9ba0-7ae4-8d2d-0588c0a8454e
                additionalProperties: false
                required:
                - items
        '401':
          description: This request is unauthorized (either the Authorization header is missing or invalid, or the API key has been revoked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 401
                    examples:
                    - 401
                    example: 401
                  error:
                    type: string
                    enum:
                    - Unauthorized
                    examples:
                    - Unauthorized
                    example: Unauthorized
                  message:
                    type: string
                    examples:
                    - Missing Authorization header
                    example: Missing Authorization header
                required:
                - statusCode
                - error
                - message
        '402':
          description: This request cannot be fulfilled because the workspace does not have an active paid plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: number
                    enum:
                    - 402
                    examples:
                    - 402
                    example: 402
                  error:
                    type: string
                    enum:
                    - Payment Required
                    examples:
                    - Payment Required
                    example: Payment Required
                  message:
                    type: string
                    examples:
                    - Workspace does not have 

# --- truncated at 32 KB (198 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/instantly-ai/refs/heads/main/openapi/instantly-ai-campaign-api-openapi.yml