feat: Add support for Idempotecy key header (#138)

Author: drish

examples/simple_email.py

@@ -19,11 +19,19 @@
     ],
 }
 
-email: resend.Email = resend.Emails.send(params)
-print(f"Sent email")
-print("Email ID: ", email["id"])
 
-email_resp: resend.Email = resend.Emails.get(email_id=email["id"])
+# Without Idempotency Key
+email_non_idempotent: resend.Email = resend.Emails.send(params)
+print(f"Sent email without idempotency key: {email_non_idempotent['id']}")
+
+# With Idempotency Key
+options: resend.Emails.SendOptions = {
+    "idempotency_key": "44",
+}
+email_idempotent: resend.Email = resend.Emails.send(params, options)
+print(f"Sent email with idempotency key: {email_idempotent['id']}")
+
+email_resp: resend.Email = resend.Emails.get(email_id=email_non_idempotent["id"])
 print(f"Retrieved email: {email_resp['id']}")
 print("Email ID: ", email_resp["id"])
 print("Email from: ", email_resp["from"])

resend/emails/_emails.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List, Union, cast
+from typing import Any, Dict, List, Optional, Union, cast
 
 from typing_extensions import NotRequired, TypedDict
 
@@ -8,6 +8,15 @@
 from resend.emails._tag import Tag
 
 
+class _SendOptions(TypedDict):
+    idempotency_key: NotRequired[str]
+    """
+    Unique key that ensures the same operation is not processed multiple times.
+    Allows for safe retries without duplicating operations.
+    If provided, will be sent as the `Idempotency-Key` header.
+    """
+
+
 class _UpdateParams(TypedDict):
     id: str
     """
@@ -148,14 +157,25 @@ class SendParams(_SendParamsDefault):
             tags (NotRequired[List[Tag]]): List of tags to be added to the email.
         """
 
+    class SendOptions(_SendOptions):
+        """
+        SendOptions is the class that wraps the options for the send method.
+
+        Attributes:
+            idempotency_key (NotRequired[str]): Unique key that ensures the same operation is not processed multiple times.
+            Allows for safe retries without duplicating operations.
+            If provided, will be sent as the `Idempotency-Key` header.
+        """
+
     @classmethod
-    def send(cls, params: SendParams) -> Email:
+    def send(cls, params: SendParams, options: Optional[SendOptions] = None) -> Email:
         """
         Send an email through the Resend Email API.
         see more: https://resend.com/docs/api-reference/emails/send-email
 
         Args:
             params (SendParams): The email parameters
+            options (SendOptions): The email options
 
         Returns:
             Email: The email object that was sent
@@ -165,6 +185,7 @@ def send(cls, params: SendParams) -> Email:
             path=path,
             params=cast(Dict[Any, Any], params),
             verb="post",
+            options=cast(Dict[Any, Any], options),
         ).perform_with_content()
         return resp
 

resend/request.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, Generic, List, Union, cast
+from typing import Any, Dict, Generic, List, Optional, Union, cast
 
 import requests
 from typing_extensions import Literal, TypeVar
@@ -19,10 +19,12 @@ def __init__(
         path: str,
         params: Union[Dict[Any, Any], List[Dict[Any, Any]]],
         verb: RequestVerb,
+        options: Optional[Dict[str, Any]] = None,
     ):
         self.path = path
         self.params = params
         self.verb = verb
+        self.options = options
 
     def perform(self) -> Union[T, None]:
         """Is the main function that makes the HTTP request
@@ -83,12 +85,18 @@ def __get_headers(self) -> Dict[Any, Any]:
         Returns:
             Dict: configured HTTP Headers
         """
-        return {
+        headers = {
             "Accept": "application/json",
             "Authorization": f"Bearer {resend.api_key}",
             "User-Agent": f"resend-python:{get_version()}",
         }
 
+        # Add the Idempotency-Key header if the verb is POST
+        # and the options dict contains the key
+        if self.verb == "post" and (self.options and "idempotency_key" in self.options):
+            headers["Idempotency-Key"] = self.options["idempotency_key"]
+        return headers
+
     def make_request(self, url: str) -> requests.Response:
         """make_request is a helper function that makes the actual
         HTTP request to the Resend API.

tests/request_test.py

@@ -0,0 +1,69 @@
+import unittest
+from typing import Any, Dict
+from unittest.mock import MagicMock, Mock, patch
+
+from resend import request
+from resend.version import get_version
+
+
+class TestResendRequest(unittest.TestCase):
+    @patch("resend.request.requests.request")
+    @patch("resend.api_key", new="test_key")
+    def test_request_idempotency_key_is_set(self, mock_requests: MagicMock) -> None:
+        mock_response = Mock()
+        mock_response.text = "{}"
+        mock_response.status_code = 200
+        mock_response.headers = {"content-type": "application/json"}
+        mock_response.json.return_value = {}
+
+        mock_requests.return_value = mock_response
+
+        req = request.Request[Dict[str, Any]](
+            path="/test",
+            params={},
+            verb="post",
+            options={"idempotency_key": "abc-123"},
+        )
+
+        req.perform()
+
+        self.assertTrue(mock_requests.called, "Expected requests.request to be called")
+
+        _, kwargs = mock_requests.call_args
+        headers = kwargs["headers"]
+
+        self.assertEqual(headers["Accept"], "application/json")
+        self.assertEqual(headers["Authorization"], "Bearer test_key")
+        self.assertEqual(headers["User-Agent"], f"resend-python:{get_version()}")
+        self.assertEqual(headers["Idempotency-Key"], "abc-123")
+
+    @patch("resend.request.requests.request")
+    @patch("resend.api_key", new="test_key")
+    def test_request_idempotency_key_is_not_set(self, mock_requests: MagicMock) -> None:
+        mock_response = Mock()
+        mock_response.text = "{}"
+        mock_response.status_code = 200
+        mock_response.headers = {"content-type": "application/json"}
+        mock_response.json.return_value = {}
+
+        mock_requests.return_value = mock_response
+
+        req = request.Request[Dict[str, Any]](
+            path="/test",
+            params={},
+            verb="post",
+        )
+
+        req.perform()
+
+        self.assertTrue(mock_requests.called, "Expected requests.request to be called")
+
+        _, kwargs = mock_requests.call_args
+        headers = kwargs["headers"]
+
+        self.assertEqual(headers["Accept"], "application/json")
+        self.assertEqual(headers["Authorization"], "Bearer test_key")
+        self.assertEqual(headers["User-Agent"], f"resend-python:{get_version()}")
+        self.assertNotIn(
+            "Idempotency-Key", headers, "Idempotency-Key should not be set"
+        )