list_campaigns
Retrieve and manage email outreach campaigns with paginated results, including status, lead counts, and performance metrics. Use search by name and cursor-based navigation to access campaign data efficiently.
Instructions
List campaigns with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after= to get next page. Continue until pagination.next_starting_after is null.
Note: search filters by campaign NAME only, not by status. To filter by status, use campaign_status in get_daily_campaign_analytics.
Returns campaign list with status, lead counts, and performance metrics.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
Implementation Reference
- The primary handler function implementing the list_campaigns tool logic. Fetches campaigns from the Instantly.ai API /campaigns endpoint, handles input parameters for pagination (starting_after, limit), search, and tags. Adds helpful pagination hints to the response.async def list_campaigns(params: Optional[ListCampaignsInput] = None) -> str: """ List campaigns with cursor-based pagination (100 per page). PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null. Note: search filters by campaign NAME only, not by status. To filter by status, use campaign_status in get_daily_campaign_analytics. Returns campaign list with status, lead counts, and performance metrics. """ client = get_client() # Handle case where params is None (for OpenAI/non-Claude clients) # Set default limit=100 to return more results by default if params is None: params = ListCampaignsInput(limit=100) query_params = {} if params.limit: query_params["limit"] = params.limit else: # Default to 100 results if no limit specified query_params["limit"] = 100 if params.starting_after: query_params["starting_after"] = params.starting_after if params.search: query_params["search"] = params.search if params.tag_ids: query_params["tag_ids"] = params.tag_ids result = await client.get("/campaigns", params=query_params) # Add pagination guidance for LLMs if isinstance(result, dict): pagination = result.get("pagination", {}) next_cursor = pagination.get("next_starting_after") if next_cursor: result["_pagination_hint"] = f"MORE RESULTS AVAILABLE. Call list_campaigns with starting_after='{next_cursor}' to get next page." return json.dumps(result, indent=2)
- Pydantic BaseModel defining the input schema (parameters) for the list_campaigns tool, including optional fields for limit, pagination cursor (starting_after), search term, and tag filtering.class ListCampaignsInput(BaseModel): """Input for listing campaigns with pagination.""" # Use extra="ignore" to be tolerant of unexpected fields from LLMs model_config = ConfigDict(str_strip_whitespace=True, extra="ignore") limit: Optional[int] = Field( default=100, ge=1, le=100, description="Results per page (1-100, default: 100)" ) starting_after: Optional[str] = Field( default=None, description="Pagination cursor - use value from pagination.next_starting_after to get next page" ) search: Optional[str] = Field( default=None, description="Search by campaign NAME only (not status)" ) tag_ids: Optional[str] = Field( default=None, description="Comma-separated tag IDs" )
- src/instantly_mcp/server.py:78-78 (registration)MCP tool registration annotation in the TOOL_ANNOTATIONS dictionary, marking list_campaigns as read-only (does not modify data). The tool is dynamically registered via the register_tools() function loop."list_campaigns": {"readOnlyHint": True},