list_accounts

Instructions

Implementation Reference

• src/instantly_mcp/tools/accounts.py:22-68 (handler)

  The main execution handler for the list_accounts tool. Fetches accounts via API with support for pagination, search, filters, and adds LLM-friendly pagination hints.

  async def list_accounts(params: Optional[ListAccountsInput] = None) -> str:
      """
      List email accounts 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.
      
      Status codes: 1=Active, 2=Paused, -1/-2/-3=Errors
      Provider codes: 1=IMAP, 2=Google, 3=Microsoft, 4=AWS
      
      Returns accounts with warmup status and campaign eligibility.
      """
      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 = ListAccountsInput(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.status is not None:
          query_params["status"] = params.status
      if params.provider_code is not None:
          query_params["provider_code"] = params.provider_code
      if params.tag_ids:
          query_params["tag_ids"] = params.tag_ids
      
      result = await client.get("/accounts", 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_accounts with starting_after='{next_cursor}' to get next page."
      
      return json.dumps(result, indent=2)

• src/instantly_mcp/models/accounts.py:34-64 (schema)

  Pydantic model defining the input schema for list_accounts parameters including pagination, search, status, and provider filters.

  class ListAccountsInput(BaseModel):
      """Input for listing email accounts."""
      
      # 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 email domain"
      )
      status: Optional[Literal[1, 2, -1, -2, -3]] = Field(
          default=None,
          description="1=Active, 2=Paused, -1/-2/-3=Errors"
      )
      provider_code: Optional[Literal[1, 2, 3, 4]] = Field(
          default=None,
          description="1=IMAP, 2=Google, 3=Microsoft, 4=AWS"
      )
      tag_ids: Optional[str] = Field(
          default=None,
          description="Comma-separated tag IDs"
      )

• src/instantly_mcp/tools/accounts.py:223-230 (registration)

  Registration of list_accounts within the ACCOUNT_TOOLS list, which is dynamically loaded and registered by the MCP server.

  ACCOUNT_TOOLS = [
      list_accounts,
      get_account,
      create_account,
      update_account,
      manage_account_state,
      delete_account,
  ]

• src/instantly_mcp/server.py:69-70 (registration)

  MCP annotation registration for list_accounts indicating it is read-only.

  "list_accounts": {"readOnlyHint": True},
  "get_account": {"readOnlyHint": True},