feat: add idempotency support to EmailEndpoint

Introduced support for idempotency keys in the EmailEndpoint to prevent duplicate email processing by the API. Updated tests to verify behavior with and without idempotency keys. Enhanced the README with examples and a detailed explanation of idempotency usage.

Author: bjarn

README.md

@@ -20,18 +20,18 @@ You can install the package via composer:
 composer require lettermint/lettermint-php
 ```
 
-
 ## Usage
 
 Initialize the Lettermint client with your API token:
+
 ```php
 $lettermint = new Lettermint\Lettermint('your-api-token');
 ```
 
-
 ### Sending Emails
 
 The SDK provides a fluent interface for composing and sending emails:
+
 ```php
 $response = $lettermint->email
                        ->from('sender@example.com')
@@ -57,9 +57,28 @@ $lettermint->email
     ->headers(['X-Custom-Header' => 'Value'])
     ->attach('document.pdf', base64_encode($fileContent))
     ->route('my-route-id')
+    ->idempotencyKey('unique-request-id-123')
     ->send();
 ```
 
+### Idempotency
+
+To ensure that duplicate requests are not processed, you can use an idempotency key:
+
+```php
+$response = $lettermint->email
+                       ->from('sender@example.com')
+                       ->to('recipient@example.com')
+                       ->subject('Hello from Lettermint!')
+                       ->text('Hello! This is a test email.')
+                       ->idempotencyKey('unique-request-id-123')
+                       ->send();
+```
+
+The idempotency key should be a unique string that you generate for each unique email you want to send. If you make the
+same request with the same idempotency key, the API will return the same response without sending a duplicate email.
+
+For more information, refer to the [documentation](https://docs.lettermint.co/platform/emails/idempotency).
 
 ## Testing
 

src/Client/HttpClient.php

@@ -8,7 +8,9 @@
 class HttpClient
 {
     private string $apiToken;
+
     private string $baseUrl;
+
     private Client $client;
 
     public function __construct(string $apiToken, string $baseUrl)
@@ -17,7 +19,7 @@ public function __construct(string $apiToken, string $baseUrl)
         $this->baseUrl = rtrim($baseUrl, '/');
         $this->client = new Client([
             'base_uri' => $this->baseUrl,
-            'timeout'  => 15,
+            'timeout' => 15,
             'headers' => [
                 'Content-Type' => 'application/json',
                 'x-lettermint-token' => $this->apiToken,
@@ -28,26 +30,31 @@ public function __construct(string $apiToken, string $baseUrl)
     /**
      * Fluent-style usage with dedicated endpoints (builder pattern)
      *
-     * @param string $path
-     * @param array $data
+     * @param  array  $headers  Additional headers for this request
      * @return array Resulting API response
+     *
      * @throws \Exception On HTTP or decode failure
      */
-    public function post(string $path, array $data): array
+    public function post(string $path, array $data, array $headers = []): array
     {
         try {
-            $response = $this->client->post($path, [
-                'json' => $data
-            ]);
+            $requestOptions = ['json' => $data];
+
+            if (! empty($headers)) {
+                $requestOptions['headers'] = $headers;
+            }
+
+            $response = $this->client->post($path, $requestOptions);
             $body = $response->getBody()->getContents();
             $result = json_decode($body, true);
 
             if (json_last_error() !== JSON_ERROR_NONE) {
                 throw new \Exception('Could not decode API response');
             }
+
             return $result;
         } catch (GuzzleException $e) {
-            throw new \Exception('API request failed: ' . $e->getMessage(), 0, $e);
+            throw new \Exception('API request failed: '.$e->getMessage(), 0, $e);
         }
     }
 }

src/Endpoints/EmailEndpoint.php

@@ -9,17 +9,22 @@ class EmailEndpoint extends Endpoint
      */
     private array $payload = [];
 
+    /**
+     * @var string|null The idempotency key for the request.
+     */
+    private ?string $idempotencyKey = null;
+
     /**
      * Set the custom headeres.
      *
      * @example ["Key" => "Value"]
      *
-     * @param array<string, string> $headers The custom headers.
-     * @return self
+     * @param  array<string, string>  $headers  The custom headers.
      */
     public function headers(array $headers): self
     {
         $this->payload['headers'] = $headers;
+
         return $this;
     }
 
@@ -31,135 +36,154 @@ public function headers(array $headers): self
      * @example John Doe <john@acme.com>
      * @example john@acme.com
      *
-     * @param string $email The sender's email address.
-     * @return self
+     * @param  string  $email  The sender's email address.
      */
     public function from(string $email): self
     {
         $this->payload['from'] = $email;
+
         return $this;
     }
 
     /**
      * Set one or more recipient email addresses.
      *
-     * @param string ...$emails One or more recipient email addresses.
-     * @return self
+     * @param  string  ...$emails  One or more recipient email addresses.
      */
     public function to(string ...$emails): self
     {
         $this->payload['to'] = $emails;
+
         return $this;
     }
 
     /**
      * Set the subject of the email.
      *
-     * @param string $subject The subject line.
-     * @return self
+     * @param  string  $subject  The subject line.
      */
     public function subject(string $subject): self
     {
         $this->payload['subject'] = $subject;
+
         return $this;
     }
 
     /**
      * Set the HTML body of the email.
      *
-     * @param string|null $html The HTML content for the email body.
-     * @return self
+     * @param  string|null  $html  The HTML content for the email body.
      */
     public function html(?string $html): self
     {
         $this->payload['html'] = $html;
+
         return $this;
     }
 
     /**
      * Set the plain text body of the email.
      *
-     * @param string|null $text The plain text content for the email body.
-     * @return self
+     * @param  string|null  $text  The plain text content for the email body.
      */
     public function text(?string $text): self
     {
         $this->payload['text'] = $text;
+
         return $this;
     }
 
     /**
      * Set one or more CC email addresses.
      *
-     * @param string ...$emails Email addresses to be CC'd.
-     * @return self
+     * @param  string  ...$emails  Email addresses to be CC'd.
      */
     public function cc(string ...$emails): self
     {
         $this->payload['cc'] = $emails;
+
         return $this;
     }
 
     /**
      * Set one or more BCC email addresses.
      *
-     * @param string ...$emails Email addresses to be BCC'd.
-     * @return self
+     * @param  string  ...$emails  Email addresses to be BCC'd.
      */
     public function bcc(string ...$emails): self
     {
         $this->payload['bcc'] = $emails;
+
         return $this;
     }
 
     /**
      * Set one or more Reply-To email addresses.
      *
-     * @param string ...$emails Reply-To email addresses.
-     * @return self
+     * @param  string  ...$emails  Reply-To email addresses.
      */
     public function replyTo(string ...$emails): self
     {
         $this->payload['reply_to'] = $emails;
+
         return $this;
     }
 
     /**
      * Attach a file to the email.
      *
-     * @param string $filename The attachment filename.
-     * @param string $base64Content The base64-encoded file content.
-     * @return self
+     * @param  string  $filename  The attachment filename.
+     * @param  string  $base64Content  The base64-encoded file content.
      */
     public function attach(string $filename, string $base64Content): self
     {
         $this->payload['attachments'][] = [
             'filename' => $filename,
             'content' => $base64Content,
         ];
+
         return $this;
     }
 
     /**
      * Set the route id for the email.
      *
-     * @param string $route The route id to use for sending.
-     * @return self
+     * @param  string  $route  The route id to use for sending.
      */
     public function route(string $route): self
     {
         $this->payload['route'] = $route;
+
+        return $this;
+    }
+
+    /**
+     * Set the idempotency key for the request.
+     *
+     * @param  string  $key  The idempotency key to ensure request uniqueness.
+     */
+    public function idempotencyKey(string $key): self
+    {
+        $this->idempotencyKey = $key;
+
         return $this;
     }
 
     /**
      * Send the composed email using the current payload.
      *
      * @return array The API response as an associative array.
+     *
      * @throws \Exception On HTTP or API failure.
      */
     public function send(): array
     {
-        return $this->httpClient->post('/v1/send', $this->payload);
+        $headers = [];
+
+        if ($this->idempotencyKey !== null) {
+            $headers['Idempotency-Key'] = $this->idempotencyKey;
+        }
+
+        return $this->httpClient->post('/v1/send', $this->payload, $headers);
     }
 }