Hunter Email Accounts API

openapi: 3.2.0
info:
  title: Hunter Email Accounts API
  version: 2.0.0
  description: 'Find and verify professional email addresses and manage Hunter resources.

    Hunter''s own MCP servers forward the calling AI client''s User-Agent in a reserved `X-MCP-USER-AGENT` request header. It is read only for usage attribution and to record which AI clients an account has connected from, and never changes a response. Per-request attribution resolves it to a fixed list of known clients; the first call from each new client also stores the User-Agent as sent, so a client Hunter does not yet recognise can be identified. There is nothing for an integration to send here.

    Hunter''s MCP servers also identify themselves with `X-SOURCE: hunter-mcp` or `X-SOURCE: hunter-chatgpt`. These reserved markers attribute server-side actions to the MCP channel, separately from ordinary API and product usage. They do not replace API authentication. Ordinary API clients do not need to send these markers.'
  contact:
    name: Hunter Support
    url: https://help.hunter.io
servers:
- url: https://api.hunter.io/v2
  description: Production
security:
- apiKeyQuery: []
- apiKeyHeader: []
- bearerAuth: []
tags:
- name: Email Accounts
paths:
  /email-accounts:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listEmailAccounts
      summary: List email accounts
      tags:
      - Email Accounts
      responses:
        '200':
          description: List email accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-accounts/capacities:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: getEmailAccountCapacities
      summary: Get email account sending capacities
      tags:
      - Email Accounts
      responses:
        '200':
          description: Get email account sending capacities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-accounts/{id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getEmailAccount
      summary: Get an email account
      description: The account's `signature` is returned HTML-sanitized (HUN-22571).
      tags:
      - Email Accounts
      responses:
        '200':
          description: Get an email account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_account_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    patch:
      operationId: updateEmailAccount
      summary: Update an email account
      tags:
      - Email Accounts
      responses:
        '200':
          description: Update an email account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_account_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    put:
      operationId: replaceEmailAccount
      summary: Replace an email account
      tags:
      - Email Accounts
      responses:
        '200':
          description: Replace an email account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/email_account_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-accounts/{id}/health-report:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getEmailAccountHealthReport
      summary: Get an email account health report
      tags:
      - Email Accounts
      responses:
        '200':
          description: Get an email account health report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-accounts/{id}/usage:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getEmailAccountUsage
      summary: Get an email account usage report
      tags:
      - Email Accounts
      responses:
        '200':
          description: Get an email account usage report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-accounts/{id}/warmup-report:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getEmailAccountWarmupReport
      summary: Get an email account warmup report
      tags:
      - Email Accounts
      responses:
        '200':
          description: Get an email account warmup report.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /email-accounts/{id}/sequences:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listEmailAccountSequences
      summary: List sequences using an email account
      tags:
      - Email Accounts
      responses:
        '200':
          description: List sequences using an email account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: The request could not be completed. A 429 with the error id `restricted_account` means the account is blocked, suspended or delinquent; further requests with the same API key are then rejected before reaching the API for up to 10 minutes, while the account and usage endpoints stay available.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_response'
  schemas:
    email_account_response:
      type: object
      additionalProperties: false
      required:
      - data
      properties:
        data:
          type: object
          additionalProperties: false
          required:
          - id
          - email
          - first_name
          - last_name
          - sending_status
          - daily_limit
          - provider
          - sender_name
          - default_account
          - signature
          - profile_picture_url
          - custom_tracking_domain
          - sending_schedule
          - warmup
          properties:
            id:
              type: integer
            email:
              type:
              - string
              - 'null'
              description: The address messages are sent from.
            first_name:
              $ref: '#/components/schemas/nullable_string'
            last_name:
              $ref: '#/components/schemas/nullable_string'
            sending_status:
              type: string
              enum:
              - active
              - paused
              - warming
              description: '`warming` while inbox protection or a progressive-sending ramp-up runs, even if the account is disconnected. Otherwise `active` when connected, and `paused` when disconnected or backing off after transient sending errors.'
            daily_limit:
              type: integer
              description: Maximum number of messages sent from this account per day.
            provider:
              type: string
              enum:
              - gmail
              - outlook
              - smtp_imap
            sender_name:
              type:
              - string
              - 'null'
              description: Display name used in the From header. May be `null` for Outlook accounts, whose sender name lives in the Microsoft profile.
            default_account:
              type:
              - boolean
              - 'null'
              description: Whether this is its owner's default sending account. Per user, so on a team several accounts can each be the default for their own owner.
            signature:
              type:
              - string
              - 'null'
              description: The account's signature as sanitized HTML, or `null` when none is set.
            profile_picture_url:
              type:
              - string
              - 'null'
              description: The account owner's avatar.
            custom_tracking_domain:
              type:
              - string
              - 'null'
              description: Hostname the team's tracking links, open-tracking pixels, and unsubscribe links use, for example `track.example.com`. `null` when the team has no custom tracking domain, the domain is not verified or its SSL is not ready yet, or the team's plan does not include custom tracking domains. Hunter's shared tracking domain is used in all those cases.
            sending_schedule:
              type: object
              additionalProperties: false
              required:
              - days
              - start_time
              - end_time
              - time_zone
              description: The default send windows a new sequence created by the requesting user would use. A sequence can override these.
              properties:
                days:
                  type:
                  - array
                  - 'null'
                  items:
                    type: integer
                    minimum: 0
                    maximum: 6
                  description: Sending days, 0 = Monday to 6 = Sunday.
                start_time:
                  type:
                  - string
                  - 'null'
                  pattern: ^\d{2}:\d{2}$
                  description: Start of the sending window, `HH:MM` in `time_zone`.
                end_time:
                  type:
                  - string
                  - 'null'
                  pattern: ^\d{2}:\d{2}$
                  description: End of the sending window, `HH:MM` in `time_zone`.
                time_zone:
                  type: string
                  description: IANA or Rails time zone name, for example `Europe/Paris`.
            warmup:
              type: object
              additionalProperties: false
              required:
              - enabled
              - status
              - end_date
              description: Inbox protection summary.
              properties:
                enabled:
                  type: boolean
                  description: Whether inbox protection is currently protecting the account.
                status:
                  type:
                  - string
                  - 'null'
                  enum:
                  - pending_oauth
                  - in_progress
                  - finished
                  - paused
                  - active
                  - null
                  description: '`null` when inbox protection was never set up for the account.'
                end_date:
                  type:
                  - string
                  - 'null'
                  format: date
    generic_resource_response:
      type: object
      additionalProperties: true
      description: Generic envelope for V2 resource operations whose detailed schema is not yet in the contract.
    error_response:
      oneOf:
      - $ref: '#/components/schemas/standard_error_response'
      - $ref: '#/components/schemas/legacy_error_response'
    nullable_string:
      type:
      - string
      - 'null'
    standard_error_response:
      type: object
      additionalProperties: false
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - code
            - details
            properties:
              id:
                type: string
              code:
                type: integer
              details:
                type: string
    legacy_error_response:
      type: object
      additionalProperties: false
      required:
      - error
      properties:
        error: {}
  parameters:
    ApiKey:
      name: api_key
      in: query
      description: Hunter API key. Prefer the X-API-KEY header outside browser links.
      schema:
        type: string
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
    bearerAuth:
      type: http
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Hunter
  source: https://hunter.io/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)