feature symfony#61455 [Mailer][Sendgrid] Add suppression groups support (KiloSierraCharlie)

This PR was squashed before being merged into the 7.4 branch.

Discussion
----------

[Mailer][Sendgrid] Add suppression groups support

| Q             | A
| ------------- | ---
| Branch?       | 7.4
| Bug fix?      | no
| New feature?  | yes
| Deprecations? | no
| Issues        | Fix/Implement symfony#53830
| License       | MIT

This PR implements a new header which supports the SendGrid suppression group/ASM options - allowing recipients of emails to unsubscribe.

Commits
-------

1c69aa2 [Mailer][Sendgrid] Add suppression groups support

Author: fabpot

src/Symfony/Component/Mailer/Bridge/Sendgrid/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+7.4
+---
+
+ * Add support for suppression groups via `SuppressionGroupHeader`
+
 7.2
 ---
 

src/Symfony/Component/Mailer/Bridge/Sendgrid/Header/SuppressionGroupHeader.php

@@ -0,0 +1,45 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Mailer\Bridge\Sendgrid\Header;
+
+use Symfony\Component\Mime\Header\UnstructuredHeader;
+
+/**
+ * @author Kieran Cross
+ */
+final class SuppressionGroupHeader extends UnstructuredHeader
+{
+    /**
+     * @param int[] $groupsToDisplay
+     */
+    public function __construct(
+        private int $groupId,
+        private array $groupsToDisplay = [],
+    ) {
+        $this->groupsToDisplay = array_values(array_map('intval', $groupsToDisplay));
+
+        parent::__construct('X-Sendgrid-SuppressionGroup', json_encode([
+            'group_id' => $groupId,
+            'groups_to_display' => $this->groupsToDisplay,
+        ], \JSON_THROW_ON_ERROR));
+    }
+
+    public function getGroupId(): int
+    {
+        return $this->groupId;
+    }
+
+    public function getGroupsToDisplay(): array
+    {
+        return $this->groupsToDisplay;
+    }
+}

src/Symfony/Component/Mailer/Bridge/Sendgrid/README.md

@@ -44,6 +44,22 @@ class SendGridConsumer implements ConsumerInterface
 }
 ```
 
+Suppression Groups
+------------------
+
+Create an e-mail and add the `SuppressionGroupHeader`:
+
+```php
+use Symfony\Component\Mailer\Bridge\Sendgrid\Header\SuppressionGroupHeader;
+// [...]
+$email = new Email();
+$email->getHeaders()->add(new SuppressionGroupHeader(GROUP_ID, GROUPS_TO_DISPLAY));
+```
+
+where:
+ - `GROUP_ID` is your Sendgrid suppression group ID
+ - `GROUPS_TO_DISPLAY_ID` is an array of the Sendgrid suppression group IDs presented to the user
+
 Resources
 ---------
 

src/Symfony/Component/Mailer/Bridge/Sendgrid/Tests/Transport/SendgridApiTransportTest.php

@@ -13,6 +13,7 @@
 
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mailer\Bridge\Sendgrid\Header\SuppressionGroupHeader;
 use Symfony\Component\Mailer\Bridge\Sendgrid\Transport\SendgridApiTransport;
 use Symfony\Component\Mailer\Envelope;
 use Symfony\Component\Mailer\Header\MetadataHeader;
@@ -289,4 +290,23 @@ public function testInlineWithoutCustomContentId()
 
         $this->assertSame('text.txt', $payload['attachments'][0]['content_id']);
     }
+
+    public function testWithSuppressionGroup()
+    {
+        $email = new Email();
+        $email->getHeaders()->add(new SuppressionGroupHeader(1, [1, 2, 3, 4, 5]));
+        $envelope = new Envelope(new Address('[email protected]'), [new Address('[email protected]')]);
+
+        $transport = new SendgridApiTransport('ACCESS_KEY');
+        $method = new \ReflectionMethod(SendgridApiTransport::class, 'getPayload');
+        $payload = $method->invoke($transport, $email, $envelope);
+
+        $this->assertArrayHasKey('asm', $payload);
+        $this->assertArrayHasKey('group_id', $payload['asm']);
+        $this->assertArrayHasKey('groups_to_display', $payload['asm']);
+
+        $this->assertCount(5, $payload['asm']['groups_to_display']);
+
+        $this->assertSame([1, 2, 3, 4, 5], $payload['asm']['groups_to_display']);
+    }
 }

src/Symfony/Component/Mailer/Bridge/Sendgrid/Tests/Transport/SendgridSmtpTransportTest.php

@@ -13,7 +13,10 @@
 
 use PHPUnit\Framework\Attributes\DataProvider;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\Mailer\Bridge\Sendgrid\Header\SuppressionGroupHeader;
 use Symfony\Component\Mailer\Bridge\Sendgrid\Transport\SendgridSmtpTransport;
+use Symfony\Component\Mime\Address;
+use Symfony\Component\Mime\Email;
 
 class SendgridSmtpTransportTest extends TestCase
 {
@@ -36,4 +39,29 @@ public static function getTransportData()
             ],
         ];
     }
+
+    public function testSuppressionGroupHeader()
+    {
+        $email = (new Email())->subject('Hello!')
+            ->to(new Address('[email protected]', 'Kevin'))
+            ->from(new Address('[email protected]', 'Fabien'))
+            ->text('Hello There!');
+        $email->getHeaders()->add(new SuppressionGroupHeader(1, [1, 2, 3, 4, 5]));
+
+        $transport = new SendgridSmtpTransport('ACCESS_KEY');
+        $method = new \ReflectionMethod(SendgridSmtpTransport::class, 'addSendgridHeaders');
+        $method->invoke($transport, $email);
+
+        $this->assertFalse($email->getHeaders()->has('X-Sendgrid-SuppressionGroup'));
+        $this->assertTrue($email->getHeaders()->has('X-SMTPAPI'));
+
+        $json = $email->getHeaders()->get('X-SMTPAPI')->getBodyAsString();
+        $payload = json_decode($json, true);
+
+        $this->assertArrayHasKey('asm', $payload);
+        $this->assertArrayHasKey('group_id', $payload['asm']);
+        $this->assertArrayHasKey('groups_to_display', $payload['asm']);
+        $this->assertCount(5, $payload['asm']['groups_to_display']);
+        $this->assertSame([1, 2, 3, 4, 5], $payload['asm']['groups_to_display']);
+    }
 }

src/Symfony/Component/Mailer/Bridge/Sendgrid/Transport/SendgridApiTransport.php

@@ -13,6 +13,7 @@
 
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
+use Symfony\Component\Mailer\Bridge\Sendgrid\Header\SuppressionGroupHeader;
 use Symfony\Component\Mailer\Envelope;
 use Symfony\Component\Mailer\Exception\HttpTransportException;
 use Symfony\Component\Mailer\Exception\TransportException;
@@ -132,6 +133,13 @@ private function getPayload(Email $email, Envelope $envelope): array
                 $categories[] = mb_substr($header->getValue(), 0, 255);
             } elseif ($header instanceof MetadataHeader) {
                 $customArguments[$header->getKey()] = $header->getValue();
+            } elseif ($header instanceof SuppressionGroupHeader) {
+                $payload['asm'] = [
+                    'group_id' => $header->getGroupId(),
+                ];
+                if ($groupsToDisplay = $header->getGroupsToDisplay()) {
+                    $payload['asm']['groups_to_display'] = $groupsToDisplay;
+                }
             } else {
                 $payload['headers'][$header->getName()] = $header->getBodyAsString();
             }

src/Symfony/Component/Mailer/Bridge/Sendgrid/Transport/SendgridSmtpTransport.php

@@ -13,7 +13,12 @@
 
 use Psr\EventDispatcher\EventDispatcherInterface;
 use Psr\Log\LoggerInterface;
+use Symfony\Component\Mailer\Bridge\Sendgrid\Header\SuppressionGroupHeader;
+use Symfony\Component\Mailer\Envelope;
+use Symfony\Component\Mailer\SentMessage;
 use Symfony\Component\Mailer\Transport\Smtp\EsmtpTransport;
+use Symfony\Component\Mime\Message;
+use Symfony\Component\Mime\RawMessage;
 
 /**
  * @author Kevin Verschaeve
@@ -27,4 +32,47 @@ public function __construct(#[\SensitiveParameter] string $key, ?EventDispatcher
         $this->setUsername('apikey');
         $this->setPassword($key);
     }
+
+    public function send(RawMessage $message, ?Envelope $envelope = null): ?SentMessage
+    {
+        if ($message instanceof Message) {
+            $this->addSendgridHeaders($message);
+        }
+
+        return parent::send($message, $envelope);
+    }
+
+    private function addSendgridHeaders(Message $message): void
+    {
+        $headers = $message->getHeaders();
+
+        if ($headers->has('X-SMTPAPI')) {
+            return;
+        }
+
+        $suppressionHeader = null;
+
+        foreach ($headers->all() as $header) {
+            if ($header instanceof SuppressionGroupHeader) {
+                $suppressionHeader = $header;
+                break;
+            }
+        }
+
+        if ($suppressionHeader) {
+            $payload = [
+                'asm' => [
+                    'group_id' => $suppressionHeader->getGroupId(),
+                ],
+            ];
+
+            $groupsToDisplay = $suppressionHeader->getGroupsToDisplay();
+            if ($groupsToDisplay) {
+                $payload['asm']['groups_to_display'] = $groupsToDisplay;
+            }
+
+            $headers->addTextHeader('X-SMTPAPI', json_encode($payload, \JSON_UNESCAPED_SLASHES));
+            $headers->remove('X-Sendgrid-SuppressionGroup');
+        }
+    }
 }