Hunter

Hunter Campaigns API

Manage email sequences and recipients.

Documentation GitHub OpenAPI

Business capability

Operations 7

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /campaigns List my email campaigns · List campaigns #

Ask an LLM

“How do I see all the email sequences in my Hunter account?”

“Can I list only the campaigns that have already been started?”

Tell an agent

List my email campaigns.

Show my campaigns filtered by started = {started}.

GET /campaigns/{id}/recipients List the recipients of a campaign · List campaign recipients #

Ask an LLM

“Who is enrolled as a recipient in a particular campaign?”

“Can I page through a campaign's recipient list?”

Tell an agent

Show the recipients of campaign {id}.

List {limit} recipients of campaign {id} starting at offset {offset}.

POST /campaigns/{id}/recipients Add recipients to a campaign · Add campaign recipients #

Ask an LLM

“How do I enroll new people into an email sequence?”

“Can I add my saved leads to a campaign using their lead IDs?”

Tell an agent

Add {emails} as recipients to campaign {id}.

Enroll leads {lead_ids} in campaign {id}.

DELETE /campaigns/{id}/recipients Cancel scheduled emails for campaign recipients · Remove campaign recipients #

Ask an LLM

“How do I stop a campaign from sending any more emails to certain people?”

“Can I cancel the scheduled messages for a recipient without stopping the whole sequence?”

Tell an agent destructive · confirm first

Cancel all scheduled emails to {emails} in campaign {id}.

Pull {emails} out of campaign {id} so they get no further emails.

POST /campaigns/{id}/start Start an email campaign · Start a campaign #

Ask an LLM

“How do I kick off sending for an email sequence?”

“Can I launch a campaign through the API once its recipients are loaded?”

Tell an agent

Start campaign {id}.

Launch the email sequence for campaign {id} now.

POST /campaigns/{id}/follow-ups Add a campaign follow-up step #

GET /campaigns/{id}/follow-ups/{follow_up_id} Get a campaign follow-up step #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/hunter:hunter-campaigns-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Hunter Campaigns 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: Campaigns
paths:
  /campaigns:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    get:
      operationId: listCampaigns
      summary: List campaigns
      description: Each campaign carries `editable`. It is true when the API key's user owns the campaign or is a team admin or owner, and only then can that user add recipients to it.
      tags:
      - Campaigns
      responses:
        '200':
          description: List campaigns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /campaigns/{id}/recipients:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: listCampaignRecipients
      summary: List campaign recipients
      description: When a recipient has asked Hunter to delete their address, with a claim or a California DROP request, their `email` is null (HUN-23599).
      tags:
      - Campaigns
      responses:
        '200':
          description: List campaign recipients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    post:
      operationId: addCampaignRecipients
      summary: Add campaign recipients
      tags:
      - Campaigns
      responses:
        '201':
          description: Add campaign recipients. `data.skipped_recipients` lists the addresses that this request did not add, from both `emails` and `lead_ids`, each with its `reason`. It is `null` when no address was skipped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
    delete:
      operationId: removeCampaignRecipients
      summary: Remove campaign recipients
      tags:
      - Campaigns
      responses:
        '201':
          description: 'Remove campaign recipients. On a draft campaign, the recipients are removed and listed in `data.recipients_removed`. On a started campaign, the recipients stay in the campaign and no more emails are sent to them: they are listed in `data.recipients_canceled`, with the count of canceled pending emails in `data.messages_canceled`. A recipient not contacted yet gets the canceled status, also when their emails are not created yet. A recipient already contacted keeps their status (sent, opened or clicked) and gets no new follow-up. `data.skipped_recipients` lists the addresses that this request did not change, each with its `reason`: `not_in_sequence`, or `no_pending_messages` when sending to the recipient already stopped (for example, they replied, or they were canceled before). It is `null` when no address was skipped.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /campaigns/{id}/start:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: startCampaign
      summary: Start a campaign
      tags:
      - Campaigns
      responses:
        '200':
          description: Start a campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /campaigns/{id}/follow-ups:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    post:
      operationId: createCampaignFollowUp
      summary: Add a campaign follow-up step
      tags:
      - Campaigns
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/follow_up_create_request'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/follow_up_create_request'
      responses:
        '201':
          description: Add a campaign follow-up step.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/generic_resource_response'
        '401':
          $ref: '#/components/responses/Error'
        default:
          $ref: '#/components/responses/Error'
  /campaigns/{id}/follow-ups/{follow_up_id}:
    parameters:
    - $ref: '#/components/parameters/ApiKey'
    - name: id
      in: path
      required: true
      schema:
        type: string
    - name: follow_up_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getCampaignFollowUp
      summary: Get a campaign follow-up step
      tags:
      - Campaigns
      responses:
        '200':
          description: Get a campaign follow-up step.
          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:
    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'
    follow_up_create_request:
      type: object
      additionalProperties: true
      properties:
        api_key:
          type: string
        step:
          type: integer
          minimum: 0
          description: 'Step to create. Optional for a new step (the next step is used). Required with `variant`, where it names the existing step that gets a Variant B.

            '
        variant:
          type: string
          enum:
          - B
          description: 'Set to `B` to add Variant B to an existing `step`, which turns A/B testing on for the sequence. Omitted fields are copied from the step''s Variant A. A Variant B whose subject and body both match Variant A is refused.

            '
        wait_days:
          type: integer
          minimum: 0
        subject:
          type: string
        body:
          type: string
          description: 'Plain text or HTML. Line breaks and blank lines in plain text, and `<p>` paragraphs in HTML, are kept. The body is stored as the editor''s HTML (`<div>` and `<br>`), also when `message_format` is `text`.

            '
        message_format:
          type: string
        message_template_id:
          description: ID of a message template whose subject, body, and format fill omitted fields.
    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)

Hunter Campaigns API

Operations 7

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

MCP server

Tools for apis

Call it yourself

Get an API key

OpenAPI Specification