MT-22678: Add search filter to contact lists get_list

examples/contacts/contact_lists.py

@@ -23,6 +23,11 @@ def list_contact_lists() -> list[ContactList]:
     return contact_lists_api.get_list()
 
 
+def search_contact_lists(search: str) -> list[ContactList]:
+    # Filter lists by name (case-insensitive prefix match).
+    return contact_lists_api.get_list(search=search)
+
+
 def get_contact_list(contact_list_id: int) -> ContactList:
     return contact_lists_api.get_by_id(contact_list_id)
 
@@ -38,6 +43,9 @@ def delete_contact_list(contact_list_id: int) -> DeletedObject:
     lists = list_contact_lists()
     print(lists)
 
+    matching_lists = search_contact_lists(search="news")
+    print(matching_lists)
+
     contact_list = get_contact_list(contact_list_id=created.id)
     print(contact_list)
 

mailtrap/api/resources/contact_lists.py

@@ -4,16 +4,23 @@
 from mailtrap.models.common import DeletedObject
 from mailtrap.models.contacts import ContactList
 from mailtrap.models.contacts import ContactListParams
+from mailtrap.models.contacts import ContactListsFilterParams
 
 
 class ContactListsApi:
     def __init__(self, client: HttpClient, account_id: str) -> None:
         self._account_id = account_id
         self._client = client
 
-    def get_list(self) -> list[ContactList]:
-        """Get all contact lists existing in your account."""
-        response = self._client.get(self._api_path())
+    def get_list(self, search: Optional[str] = None) -> list[ContactList]:
+        """
+        Get all contact lists existing in your account.
+
+        :param search: Optionally filter lists by name
+            (case-insensitive prefix match).
+        """
+        params = ContactListsFilterParams(search=search)
+        response = self._client.get(self._api_path(), params=params.api_query_params)
         return [ContactList(**field) for field in response]
 
     def get_by_id(self, list_id: int) -> ContactList:

mailtrap/models/contacts.py

@@ -38,6 +38,12 @@ class ContactListParams(RequestParams):
     name: str
 
 
+@dataclass
+class ContactListsFilterParams(RequestParams):
+    # Filter contact lists by name (case-insensitive prefix match).
+    search: Optional[str] = None
+
+
 @dataclass
 class ContactList:
     id: int

tests/unit/api/contacts/test_contact_lists.py

@@ -106,6 +106,24 @@ def test_get_contact_lists_should_return_contact_list_list(
         )
         assert contact_lists[0].id == LIST_ID
 
+    @responses.activate
+    def test_get_contact_lists_with_search_should_filter_by_name(
+        self, contact_lists_api: ContactListsApi, sample_contact_list_dict: dict
+    ) -> None:
+        search = "news"
+        responses.get(
+            BASE_CONTACT_LISTS_URL,
+            json=[sample_contact_list_dict],
+            status=200,
+            match=[responses.matchers.query_param_matcher({"search": search})],
+        )
+
+        contact_lists = contact_lists_api.get_list(search=search)
+
+        assert isinstance(contact_lists, list)
+        assert contact_lists[0].id == LIST_ID
+        assert responses.calls[0].request.params["search"] == search
+
     @pytest.mark.parametrize(
         "status_code,response_json,expected_error_message",
         [