Instantly Account API

openapi: 3.2.0
info:
  title: Explorer Account 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: Account
  description: An email account that can be used to send campaigns
  x-group: Account
paths:
  /api/v2/accounts:
    post:
      operationId: createAccount
      summary: Create account
      tags:
      - Account
      description: 'Requires one of the following scopes: `accounts:create`, `accounts:all`, `all:create`, `all:all`'
      requestBody:
        content:
          application/json:
            schema:
              title: CreateAccount
              description: The Account to create
              type: object
              properties:
                email:
                  type: string
                  description: Email address of the account
                  format: email
                  example: user@example.com
                first_name:
                  type: string
                  description: First name associated with the account
                  example: John
                last_name:
                  type: string
                  description: Last name associated with the account
                  example: Doe
                warmup:
                  type: object
                  description: Warmup configuration for the account
                  properties:
                    limit:
                      type: number
                      description: Email sending limit for the account
                      example: 100
                    advanced:
                      type: object
                      description: Advanced settings for the account
                      properties:
                        warm_ctd:
                          type: boolean
                          description: Whether the account is in warm CTD mode
                          example: false
                        open_rate:
                          type: number
                          description: Email open rate for the account
                          example: 0.95
                        important_rate:
                          type: number
                          description: Important email rate for the account
                          example: 0.8
                        read_emulation:
                          type: boolean
                          description: Whether read emulation is enabled
                          example: true
                        spam_save_rate:
                          type: number
                          description: Spam save rate for the account
                          example: 0.02
                        weekday_only:
                          type: boolean
                          description: Whether to send emails only on weekdays
                          example: true
                    warmup_custom_ftag:
                      type: string
                      description: Custom tag for the account
                      example: warmup
                    increment:
                      type: string
                      enum:
                      - disabled
                      - '0'
                      - '1'
                      - '2'
                      - '3'
                      - '4'
                      x-enumDescriptions:
                        '0': '0'
                        '1': '1'
                        '2': '2'
                        '3': '3'
                        '4': '4'
                        disabled: Disabled
                      description: Daily increment added to the sending limit, starting from 0, until the full daily limit is reached (slow ramp). Gradually increases sending volume to improve deliverability. Set to `disabled` to send at the full daily limit from day one.
                      example: disabled
                    reply_rate:
                      type: number
                      description: Reply rate for the account
                      example: 0.1
                daily_limit:
                  type:
                  - number
                  - 'null'
                  description: Daily email sending limit
                  example: 100
                tracking_domain_name:
                  type:
                  - string
                  - 'null'
                  description: Tracking domain
                  example: example.com
                tracking_domain_status:
                  type:
                  - string
                  - 'null'
                  description: Tracking domain status
                  example: active
                enable_slow_ramp:
                  type:
                  - boolean
                  - 'null'
                  description: Whether to enable slow ramp up for sending limits
                  example: false
                inbox_placement_test_limit:
                  type:
                  - number
                  - 'null'
                  description: The limit for inbox placement tests
                  minimum: 0
                  example: 10
                provider_code:
                  type: number
                  description: Provider code for the account. Please make sure to specify the right provider code, otherwise your account will not work.
                  enum:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 8
                  - 11
                  x-enumDescriptions:
                    '1': Custom IMAP/SMTP
                    '2': Google
                    '3': Microsoft
                    '4': AWS
                    '8': AirMail
                    '11': Airmail Instant
                  example: 2
                sending_gap:
                  type: number
                  description: The gap between emails sent from this account in minutes (minimum wait time when used with multiple campaigns)
                  minimum: 0
                  maximum: 1440
                  example: 10
                signature:
                  type:
                  - string
                  - 'null'
                  description: Email signature for the account
                  example: Best regards, John Doe
                reply_to:
                  type: string
                  example: reply@example.com
                imap_username:
                  type: string
                  example: username
                imap_password:
                  type: string
                  example: password
                imap_host:
                  type: string
                  example: imap.gmail.com
                imap_port:
                  type: number
                  example: 993
                smtp_username:
                  type: string
                  example: username
                smtp_password:
                  type: string
                  example: password
                smtp_host:
                  type: string
                  example: smtp.gmail.com
                smtp_port:
                  type: number
                  example: 587
                warmup_custom_ftag:
                  type: string
                  example: warmup
                skip_cname_check:
                  type: boolean
                  example: false
              required:
              - email
              - first_name
              - last_name
              - provider_code
              - imap_username
              - imap_password
              - imap_host
              - imap_port
              - smtp_username
              - smtp_password
              - smtp_host
              - smtp_port
              additionalProperties: false
        required: true
        description: The Account to create
      responses:
        '200':
          description: The Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '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: listAccount
      summary: List account
      tags:
      - Account
      description: 'Requires one of the following scopes: `accounts:read`, `accounts: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: 2026-01-01T00:00:00.000Z&jon@doe.com
        example: 2026-01-01T00:00:00.000Z&jon@doe.com
        in: query
        name: starting_after
        required: false
        description: Pagination cursor from `next_starting_after`, in `timestamp_created&email` format. Legacy ISO date-time cursor is still supported.
      - schema:
          type: string
          example: gmail.com
        example: gmail.com
        in: query
        name: search
        required: false
      - schema:
          type: number
          enum:
          - 1
          - 2
          - 3
          - -1
          - -2
          - -3
          x-enumDescriptions:
            '1': Active
            '2': Paused
            '3': Temporarily paused for maintenance; will be automatically resumed shortly
            '-1': Connection Error
            '-2': Soft Bounce Error
            '-3': Sending Error
          example: 1
        example: 1
        in: query
        name: status
        required: false
      - schema:
          type: number
          enum:
          - 1
          - 2
          - 3
          - 4
          - 8
          - 11
          x-enumDescriptions:
            '1': Custom IMAP/SMTP
            '2': Google
            '3': Microsoft
            '4': AWS
            '8': AirMail
            '11': Airmail Instant
          example: 2
        example: 2
        in: query
        name: provider_code
        required: false
      - schema:
          type: string
          example: 019ffad2-9b14-7491-94e1-412827f38846, 019ffad2-9b14-7491-94e1-41295cf52579
        example: 019ffad2-9b14-7491-94e1-412827f38846, 019ffad2-9b14-7491-94e1-41295cf52579
        in: query
        name: tag_ids
        required: false
        description: Filter accounts by tag ids. Returns accounts that have any of the specified tags assigned. You can specify multiple tag ids by separating them with a comma.
      - schema:
          type: string
          example: 019ffad2-9b14-7491-94e1-412a55965922, 019ffad2-9b14-7491-94e1-412b9974b398
        example: 019ffad2-9b14-7491-94e1-412a55965922, 019ffad2-9b14-7491-94e1-412b9974b398
        in: query
        name: tag_ids_all
        required: false
        description: Filter accounts by tag ids with AND logic. Returns only accounts that have all of the specified tags assigned. You can specify multiple tag ids by separating them with a comma.
      - schema:
          type: boolean
          example: true
        example: true
        in: query
        name: include_tags
        required: false
        description: Include tags in the response. If true, the response will include the tags assigned to each account.
      - schema:
          type: string
          enum:
          - ACC_FILTER_PAUSED
          - ACC_FILTER_ERROR
          - ACC_FILTER_NO_CTD
          - ACC_FILTER_PW_ACCOUNTS
          - ACC_FILTER_DFY
          - ACC_FILTER_DFY_SETUP_PENDING
          - ACC_FILTER_W_ACTIVE
          - ACC_FILTER_W_PAUSED
          - ACC_FILTER_W_ERROR
          x-enumDescriptions:
            ACC_FILTER_PAUSED: Paused
            ACC_FILTER_ERROR: Has errors
            ACC_FILTER_NO_CTD: No custom tracking domain
            ACC_FILTER_PW_ACCOUNTS: Pre-warmed accounts
            ACC_FILTER_DFY: DFY accounts
            ACC_FILTER_DFY_SETUP_PENDING: DFY Setup Pending
            ACC_FILTER_W_ACTIVE: Warmup active
            ACC_FILTER_W_PAUSED: Warmup paused
            ACC_FILTER_W_ERROR: Warmup has errors
          example: ACC_FILTER_PAUSED
        examples:
          ACC_FILTER_PAUSED:
            value: ACC_FILTER_PAUSED
          ACC_FILTER_ERROR:
            value: ACC_FILTER_ERROR
          ACC_FILTER_NO_CTD:
            value: ACC_FILTER_NO_CTD
          ACC_FILTER_PW_ACCOUNTS:
            value: ACC_FILTER_PW_ACCOUNTS
          ACC_FILTER_DFY:
            value: ACC_FILTER_DFY
          ACC_FILTER_DFY_SETUP_PENDING:
            value: ACC_FILTER_DFY_SETUP_PENDING
          ACC_FILTER_W_ACTIVE:
            value: ACC_FILTER_W_ACTIVE
          ACC_FILTER_W_PAUSED:
            value: ACC_FILTER_W_PAUSED
          ACC_FILTER_W_ERROR:
            value: ACC_FILTER_W_ERROR
        in: query
        name: filter
        required: false
        description: The filter to apply to the accounts.
      - schema:
          type: string
          enum:
          - timestamp_created
          - email
          - stat_warmup_score
          - status
          example: stat_warmup_score
        example: stat_warmup_score
        in: query
        name: sort_by
        required: false
        description: Column to sort results by.
      - schema:
          type: string
          enum:
          - asc
          - desc
          example: desc
        example: desc
        in: query
        name: sort_order
        required: false
        description: Sort direction. Defaults to `desc` when `sort_by` is provided.
      - schema:
          type: integer
          minimum: 0
          example: 0
        example: 0
        in: query
        name: skip
        required: false
        description: Number of items to skip for offset-based pagination. Used with `sort_by` when cursor pagination is not available.
      responses:
        '200':
          description: The list of Account
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: The list of Account
                    items:
                      allOf:
                      - $ref: '#/components/schemas/Account'
                      - type: object
                        properties:
                          tags:
                            type:
                            - array
                            - 'null'
                            description: Tags associated with the account, set to `include_tags` to populate
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: Unique identifier for the custom tag
                                  examples:
                                  - 019ffad2-9b14-7491-94e1-412c61f2fe27
                                  example: 019ffad2-9b14-7491-94e1-412c61f2fe27
                                label:
                                  type: string
                                  description: Display label for the custom tag
                                  examples:
                                  - Important tag
                                  example: Important tag
                                description:
                                  type:
                                  - string
                                  - 'null'
                                  description: Detailed description of the custom tag purpose
                                  examples:
                                  - null
                                  example: null
                  next_starting_after:
                    type: string
                    examples:
                    - 019ffad2-9b15-755e-8b3d-9a147b6321a1
                    - '2026-08-13T11:12:14.101Z'
                    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-9b15-755e-8b3d-9a147b6321a1
                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 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
  /api/v2/accounts/{email}:
    get:
      operationId: getAccount
      summary: Get account
      tags:
      - Account
      description: 'Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`'
      parameters:
      - schema:
          type: string
          example: jon@doe.com
        example: jon@doe.com
        in: path
        name: email
        required: true
        description: The email of the account to get
      responses:
        '200':
          description: The requested Account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '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
    patch:
      operationId: patchAccount
      summary: Patch account
      tags:
      - Account
      description: 'Requires one of the following scopes: `accounts:update`, `accounts:all`, `all:update`, `all:all`'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                  description: First name associated with the account
                  example: John
                last_name:
                  type: string
                  description: Last name associated with the account
                  example: Doe
                warmup:
                  type: object
                  description: Warmup configuration for the account
                  properties:
                    limit:
                      type: number
                      description: Email sending limit for the account
                      example: 100
                    advanced:
                      type: object
                      description: Advanced settings for the account
                      properties:
                        warm_ctd:
                          type: boolean
                          description: Whether the account is in warm CTD mode
                          example: false
                        open_rate:
                          type: number
                          description: Email open rate for the account
                          example: 0.95
                        important_rate:
                          type: number
                          description: Important email rate for the account
                          example: 0.8
                        read_emulation:
                          type: boolean
                          description: Whether read emulation is enabled
                          example: true
                        spam_save_rate:
                          type: number
                          description: Spam save rate for the account
                          example: 0.02
                        weekday_only:
                          type: boolean
                          description: Whether to send emails only on weekdays
                          example: true
                    warmup_custom_ftag:
                      type: string
                      description: Custom tag for the account
                      example: warmup
                    increment:
                      type: string
                      enum:
                      - disabled
                      - '0'
                      - '1'
                   

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