feat: get subscriber by email endpoint

backend/src/Api/Console/Controller/SubscriberController.php

@@ -261,6 +261,19 @@ private function skipLists(Subscriber $subscriber, array $lists, array $reasonsT
         );
     }
 
+    #[Route('/subscribers/email/{email}', methods: 'GET')]
+    #[ScopeRequired(Scope::SUBSCRIBERS_READ)]
+    public function getSubscriberByEmail(string $email, Newsletter $newsletter): JsonResponse
+    {
+        $subscriber = $this->subscriberService->getSubscriberByEmail($newsletter, $email);
+
+        if ($subscriber === null) {
+            return $this->json(['message' => 'Subscriber not found'], 404);
+        }
+
+        return $this->json(new SubscriberObject($subscriber));
+    }
+
     #[Route('/subscribers/{id}', methods: 'DELETE')]
     #[ScopeRequired(Scope::SUBSCRIBERS_WRITE)]
     public function deleteSubscriber(Subscriber $subscriber): JsonResponse

backend/src/Api/Console/Object/SubscriberObject.php

@@ -17,6 +17,10 @@ class SubscriberObject
      * @var array<int>
      */
     public array $list_ids;
+    /**
+     * @var array<string>
+     */
+    public array $lists;
     public ?string $subscribe_ip;
     public ?int $subscribed_at;
 
@@ -31,7 +35,9 @@ public function __construct(Subscriber $subscriber)
         $this->email = $subscriber->getEmail();
         $this->source = $subscriber->getSource();
         $this->status = $subscriber->getStatus();
-        $this->list_ids = array_values($subscriber->getLists()->map(fn($list) => $list->getId())->toArray());
+        $subscriberLists = $subscriber->getLists();
+        $this->list_ids = array_values($subscriberLists->map(fn($list) => $list->getId())->toArray());
+        $this->lists = array_values($subscriberLists->map(fn($list) => $list->getName())->toArray());
         $this->subscribe_ip = $subscriber->getSubscribeIp();
         $this->subscribed_at = $subscriber->getSubscribedAt()?->getTimestamp();
         $this->metadata = $subscriber->getMetadata();

backend/tests/Api/Console/Subscriber/GetSubscriberByEmailTest.php

@@ -0,0 +1,85 @@
+<?php
+
+namespace App\Tests\Api\Console\Subscriber;
+
+use App\Api\Console\Controller\SubscriberController;
+use App\Api\Console\Object\SubscriberObject;
+use App\Entity\Subscriber;
+use App\Repository\SubscriberRepository;
+use App\Service\Subscriber\SubscriberService;
+use App\Tests\Case\WebTestCase;
+use App\Tests\Factory\NewsletterFactory;
+use App\Tests\Factory\NewsletterListFactory;
+use App\Tests\Factory\SubscriberFactory;
+use PHPUnit\Framework\Attributes\CoversClass;
+
+#[CoversClass(SubscriberController::class)]
+#[CoversClass(SubscriberService::class)]
+#[CoversClass(SubscriberRepository::class)]
+#[CoversClass(Subscriber::class)]
+#[CoversClass(SubscriberObject::class)]
+class GetSubscriberByEmailTest extends WebTestCase
+{
+
+    public function test_get_subscriber_by_email_found(): void
+    {
+        $newsletter = NewsletterFactory::createOne();
+        $list1 = NewsletterListFactory::createOne(['newsletter' => $newsletter, 'name' => 'list-one']);
+        $list2 = NewsletterListFactory::createOne(['newsletter' => $newsletter, 'name' => 'list-two']);
+
+        $subscriber = SubscriberFactory::createOne([
+            'newsletter' => $newsletter,
+            'email' => 'test@example.com',
+            'lists' => [$list1, $list2],
+        ]);
+
+        $response = $this->consoleApi(
+            $newsletter,
+            'GET',
+            '/subscribers/email/test@example.com',
+        );
+
+        $this->assertSame(200, $response->getStatusCode());
+        $json = $this->getJson();
+        $this->assertSame($subscriber->getId(), $json['id']);
+        $this->assertSame('test@example.com', $json['email']);
+        $this->assertIsArray($json['list_ids']);
+        $this->assertIsArray($json['lists']);
+        $this->assertContains($list1->getId(), $json['list_ids']);
+        $this->assertContains($list2->getId(), $json['list_ids']);
+        $this->assertContains('list-one', $json['lists']);
+        $this->assertContains('list-two', $json['lists']);
+    }
+
+    public function test_get_subscriber_by_email_not_found(): void
+    {
+        $newsletter = NewsletterFactory::createOne();
+
+        $response = $this->consoleApi(
+            $newsletter,
+            'GET',
+            '/subscribers/email/nonexistent@example.com',
+        );
+
+        $this->assertSame(404, $response->getStatusCode());
+    }
+
+    public function test_get_subscriber_by_email_other_newsletter(): void
+    {
+        $newsletter = NewsletterFactory::createOne();
+        $otherNewsletter = NewsletterFactory::createOne();
+
+        SubscriberFactory::createOne([
+            'newsletter' => $newsletter,
+            'email' => 'test@example.com',
+        ]);
+
+        $response = $this->consoleApi(
+            $otherNewsletter,
+            'GET',
+            '/subscribers/email/test@example.com',
+        );
+
+        $this->assertSame(404, $response->getStatusCode());
+    }
+}

frontend/src/routes/(marketing)/docs/[...slug]/content/ConsoleApi.svelte

@@ -284,6 +284,10 @@
 
 <ul>
 	<li><a href="#get-subscribers"><code>GET /subscribers</code></a> - Get subscribers</li>
+	<li>
+		<a href="#get-subscriber-by-email"><code>GET /subscribers/email/{'{email}'}</code></a> - Get a subscriber
+		by email
+	</li>
 	<li>
 		<a href="#create-update-subscriber"><code>POST /subscribers</code></a> - Create or update a subscriber
 	</li>
@@ -324,6 +328,18 @@
     `}
 />
 
+<h4 id="get-subscriber-by-email">Get a subscriber by email</h4>
+
+<code>GET /subscribers/email/{'{email}'}</code>
+
+<CodeBlock
+	language="ts"
+	code={`
+        type Request = {}
+        type Response = Subscriber // 404 if not found
+    `}
+/>
+
 <h4 id="create-update-subscriber">Create or update a subscriber</h4>
 
 <code>POST /subscribers</code>
@@ -1133,6 +1149,7 @@ appearance of your newsletters.
             source: 'console' | 'form' | 'import';
             status: 'subscribed' | 'pending';
             list_ids: number[];
+            lists: string[]; // list names
             subscribe_ip: string | null;
             is_opted_in: boolean;
             subscribed_at: number | null; // unix timestamp