From 26b781780c4bbc4a07241a9c1df329c68c99459a Mon Sep 17 00:00:00 2001
From: Maciej Walusiak <maciej.walusiak@railsware.com>
Date: Thu, 9 Jul 2026 12:19:03 +0200
Subject: [PATCH 1/2] MT-22678: Add name search filter to getAllContactLists

---
 README.md                         |  2 +-
 examples/contact-lists/all.php    | 15 +++++++++++++++
 src/Api/General/Contact.php       | 10 ++++++++--
 tests/Api/General/ContactTest.php | 20 ++++++++++++++++++++
 4 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index fc5eef2..ae0e21c 100644
--- a/README.md
+++ b/README.md
@@ -255,7 +255,7 @@ Email Sandbox (Testing):
 
 Contact management:
 - Contacts CRUD & listing – [`contacts/all.php`](examples/contacts/all.php)
-- Contact lists CRUD – [`contact-lists/all.php`](examples/contact-lists/all.php)
+- Contact lists CRUD & name search – [`contact-lists/all.php`](examples/contact-lists/all.php)
 - Custom fields CRUD – [`contact-fields/all.php`](examples/contact-fields/all.php)
 - Import/Export – (no example yet) ← add in future
 - Events – (no example yet) ← add in future
diff --git a/examples/contact-lists/all.php b/examples/contact-lists/all.php
index edc7bc1..9058654 100644
--- a/examples/contact-lists/all.php
+++ b/examples/contact-lists/all.php
@@ -30,6 +30,21 @@
 }
 
 
+/**
+ * Get all Contact Lists filtered by name (case-insensitive prefix match).
+ *
+ * GET https://mailtrap.io/api/accounts/{account_id}/contacts/lists?search=news
+ */
+try {
+    $response = $contacts->getAllContactLists('news'); // Replace 'news' with your desired name prefix
+
+    // print the response body (array)
+    var_dump(ResponseHelper::toArray($response));
+} catch (Exception $e) {
+    echo 'Caught exception: ',  $e->getMessage(), PHP_EOL;
+}
+
+
 /**
  * Get a specific Contact List by ID.
  *
diff --git a/src/Api/General/Contact.php b/src/Api/General/Contact.php
index 4a5b0ca..30c9e9e 100644
--- a/src/Api/General/Contact.php
+++ b/src/Api/General/Contact.php
@@ -27,12 +27,18 @@ public function __construct(ConfigInterface $config, private int $accountId)
     /**
      * Get all Contact Lists.
      *
+     * @param string|null $search Filter contact lists by name (case-insensitive prefix match), or null to get all.
      * @return ResponseInterface
      */
-    public function getAllContactLists(): ResponseInterface
+    public function getAllContactLists(?string $search = null): ResponseInterface
     {
+        $parameters = [];
+        if ($search !== null) {
+            $parameters['search'] = $search;
+        }
+
         return $this->handleResponse(
-            $this->httpGet($this->getBasePath() . '/lists')
+            $this->httpGet($this->getBasePath() . '/lists', $parameters)
         );
     }
 
diff --git a/tests/Api/General/ContactTest.php b/tests/Api/General/ContactTest.php
index 70f00fe..5c3e38b 100644
--- a/tests/Api/General/ContactTest.php
+++ b/tests/Api/General/ContactTest.php
@@ -59,6 +59,26 @@ public function testGetAllContactLists(): void
         $this->assertArrayHasKey('id', $responseData[0]);
     }
 
+    public function testGetAllContactListsWithSearch(): void
+    {
+        $search = 'news';
+
+        $this->contact->expects($this->once())
+            ->method('httpGet')
+            ->with(
+                AbstractApi::DEFAULT_HOST . '/api/accounts/' . self::FAKE_ACCOUNT_ID . '/contacts/lists',
+                ['search' => $search]
+            )
+            ->willReturn(new Response(200, ['Content-Type' => 'application/json'], json_encode($this->getExpectedContactLists())));
+
+        $response = $this->contact->getAllContactLists($search);
+        $responseData = ResponseHelper::toArray($response);
+
+        $this->assertInstanceOf(Response::class, $response);
+        $this->assertCount(2, $responseData);
+        $this->assertArrayHasKey('id', $responseData[0]);
+    }
+
     public function testGetContactList(): void
     {
         $contactListId = 1;

From 57ee9cb1d43deb924c0b3a0102d93adcd5c23fdf Mon Sep 17 00:00:00 2001
From: Maciej Walusiak <maciej.walusiak@railsware.com>
Date: Fri, 10 Jul 2026 10:24:04 +0200
Subject: [PATCH 2/2] MT-22678: Drop search filter call-out from README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index ae0e21c..fc5eef2 100644
--- a/README.md
+++ b/README.md
@@ -255,7 +255,7 @@ Email Sandbox (Testing):
 
 Contact management:
 - Contacts CRUD & listing – [`contacts/all.php`](examples/contacts/all.php)
-- Contact lists CRUD & name search – [`contact-lists/all.php`](examples/contact-lists/all.php)
+- Contact lists CRUD – [`contact-lists/all.php`](examples/contact-lists/all.php)
 - Custom fields CRUD – [`contact-fields/all.php`](examples/contact-fields/all.php)
 - Import/Export – (no example yet) ← add in future
 - Events – (no example yet) ← add in future