[Mailer][SendGrid] add support for scheduling delivery via send_at API parameter

Mickael GOETZ · Mickael GOETZ · commit 50ac018170e7 · 2025-05-07T16:26:28.000+02:00
diff --git a/src/Symfony/Component/Mailer/Bridge/Sendgrid/CHANGELOG.md b/src/Symfony/Component/Mailer/Bridge/Sendgrid/CHANGELOG.md
@@ -5,6 +5,7 @@ CHANGELOG
 ---
 
  * Add support for webhooks
+ * Add support for scheduling delivery with the `send_at` API parameter via a `Send-At` date-header.
 
 5.4
 ---
diff --git a/src/Symfony/Component/Mailer/Bridge/Sendgrid/README.md b/src/Symfony/Component/Mailer/Bridge/Sendgrid/README.md
@@ -44,6 +44,20 @@ class SendGridConsumer implements ConsumerInterface
 }
 ```
 
+Scheduling
+----------
+
+When using the **API transport** (with a `sendgrid+api` DSN), you can schedule
+email your emails by providing a `\DateTimeInterface` object in a
+`Symfony\Component\Mime\Header\DateHeader` named `Send-At`.
+
+```php
+$email = new \Symfony\Component\Mime\Email();
+$email->getHeaders()->addDateHeader('Send-At', (new \DateTime())->modify('+3 hours'));
+```
+It will be mapped to the `send_at` parameter of the `[POST] /mail/send`
+[API endpoint](https://www.twilio.com/docs/sendgrid/api-reference/mail-send/mail-send#request-body)
+
 Resources
 ---------
 
diff --git a/src/Symfony/Component/Mailer/Bridge/Sendgrid/Tests/Transport/SendgridApiTransportTest.php b/src/Symfony/Component/Mailer/Bridge/Sendgrid/Tests/Transport/SendgridApiTransportTest.php
@@ -286,4 +286,18 @@ public function testInlineWithoutCustomContentId()
 
         $this->assertSame('text.txt', $payload['attachments'][0]['content_id']);
     }
+
+    public function testSendAtHeader()
+    {
+        $email = new Email();
+        $email->getHeaders()->addDateHeader('Send-At', new \DateTime('2025-05-07 16:00:00', new \DateTimeZone('Europe/Paris')));
+        $envelope = new Envelope(new Address('alice@system.com'), [new Address('bob@system.com')]);
+
+        $transport = new SendgridApiTransport('ACCESS_KEY');
+        $method = new \ReflectionMethod(SendgridApiTransport::class, 'getPayload');
+        $payload = $method->invoke($transport, $email, $envelope);
+
+        $this->assertArrayHasKey('send_at', $payload);
+        $this->assertEquals(1746626400, $payload['send_at']);
+    }
 }
diff --git a/src/Symfony/Component/Mailer/Bridge/Sendgrid/Transport/SendgridApiTransport.php b/src/Symfony/Component/Mailer/Bridge/Sendgrid/Transport/SendgridApiTransport.php
@@ -22,6 +22,7 @@
 use Symfony\Component\Mailer\Transport\AbstractApiTransport;
 use Symfony\Component\Mime\Address;
 use Symfony\Component\Mime\Email;
+use Symfony\Component\Mime\Header\DateHeader;
 use Symfony\Contracts\HttpClient\Exception\DecodingExceptionInterface;
 use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -125,7 +126,13 @@ private function getPayload(Email $email, Envelope $envelope): array
                 continue;
             }
 
-            if ($header instanceof TagHeader) {
+            if ($name === 'send-at') {
+                if (!$header instanceof DateHeader) {
+                    throw new TransportException(sprintf('The Send-At header should be a "%s" instance to deduce the correct timestamp.', DateHeader::class));
+                }
+                // the documentation shows parameter names in camelCase but the expected JSON keys should be in snake_case
+                $payload['send_at'] = $header->getDateTime()->getTimestamp();
+            } elseif ($header instanceof TagHeader) {
                 if (10 === \count($categories)) {
                     throw new TransportException(sprintf('Too many "%s" instances present in the email headers. Sendgrid does not accept more than 10 categories on an email.', TagHeader::class));
                 }
