From cddec0b3a761ec644a50c009b020dbc0288d6493 Mon Sep 17 00:00:00 2001
From: Bjarn Bronsveld <bjarn@bronsveld.me>
Date: Sat, 23 Aug 2025 22:55:06 +0200
Subject: [PATCH] feat: add metadata support to EmailEndpoint

Added a `metadata` method to set custom metadata for emails. Updated tests to ensure correct behavior when metadata is provided. Fixed a typo in the headers method's PHPDoc.
---
 src/Endpoints/EmailEndpoint.php       | 16 +++++++++++++++-
 tests/Endpoints/EmailEndpointTest.php | 20 ++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/src/Endpoints/EmailEndpoint.php b/src/Endpoints/EmailEndpoint.php
index 8ad49ad..7841e90 100644
--- a/src/Endpoints/EmailEndpoint.php
+++ b/src/Endpoints/EmailEndpoint.php
@@ -15,7 +15,7 @@ class EmailEndpoint extends Endpoint
     private ?string $idempotencyKey = null;
 
     /**
-     * Set the custom headeres.
+     * Set the custom headers.
      *
      * @example ["Key" => "Value"]
      *
@@ -169,6 +169,20 @@ public function idempotencyKey(string $key): self
         return $this;
     }
 
+    /**
+     * Set custom metadata.
+     *
+     * @example ["key" => "value"]
+     *
+     * @param  array<string, string>  $metadata  The metadata object.
+     */
+    public function metadata(array $metadata): self
+    {
+        $this->payload['metadata'] = $metadata;
+
+        return $this;
+    }
+
     /**
      * Send the composed email using the current payload.
      *
diff --git a/tests/Endpoints/EmailEndpointTest.php b/tests/Endpoints/EmailEndpointTest.php
index 51490d0..852824f 100644
--- a/tests/Endpoints/EmailEndpointTest.php
+++ b/tests/Endpoints/EmailEndpointTest.php
@@ -233,3 +233,23 @@
         ->subject('Test Subject')
         ->send();
 });
+
+test('it handles metadata', function () {
+    $this->httpClient
+        ->shouldReceive('post')
+        ->once()
+        ->with('/v1/send', [
+            'from' => 'sender@example.com',
+            'to' => ['recipient@example.com'],
+            'subject' => 'Test Subject',
+            'metadata' => ['foo' => 'bar'],
+        ], [])
+        ->andReturn(['message_id' => '123', 'status' => 'pending']);
+
+    $this->endpoint
+        ->from('sender@example.com')
+        ->to('recipient@example.com')
+        ->subject('Test Subject')
+        ->metadata(['foo' => 'bar'])
+        ->send();
+});