feat: impl batch validation mode

Author: drish

examples/batch_email_send.py

@@ -49,3 +49,45 @@
     print("Failed to send batch emails")
     print(f"Error: {err}")
     exit(1)
+
+try:
+    # Send batch emails with permissive validation mode
+    print("sending with permissive validation mode")
+
+    # Example with some invalid emails to demonstrate error handling
+    mixed_params: List[resend.Emails.SendParams] = [
+        {
+            "from": "onboarding@resend.dev",
+            "to": ["delivered@resend.dev"],
+            "subject": "Valid email",
+            "html": "<strong>This should work!</strong>",
+        },
+        {
+            "from": "onboarding@resend.dev",
+            "to": [],  # Invalid - empty to field
+            "subject": "Invalid email",
+            "html": "<strong>This should fail!</strong>",
+        },
+    ]
+
+    options_permissive: resend.Batch.SendOptions = {
+        "batch_validation": "permissive",
+    }
+
+    result: resend.Batch.SendResponse = resend.Batch.send(
+        mixed_params, options=options_permissive
+    )
+
+    print(f"Successfully sent {len(result['data'])} emails:")
+    for email in result["data"]:
+        print(f"  Email id: {email['id']}")
+
+    if "errors" in result and result["errors"]:
+        print(f"Validation errors for {len(result['errors'])} emails:")
+        for error in result["errors"]:
+            print(f"  Index {error['index']}: {error['message']}")
+
+except resend.exceptions.ResendError as err:
+    print("Failed to send batch emails")
+    print(f"Error: {err}")
+    exit(1)

resend/__init__.py

@@ -11,7 +11,7 @@
 from .domains._domain import Domain
 from .domains._domains import Domains
 from .emails._attachment import Attachment, RemoteAttachment
-from .emails._batch import Batch
+from .emails._batch import Batch, BatchValidationError
 from .emails._email import Email
 from .emails._emails import Emails
 from .emails._tag import Tag
@@ -51,6 +51,7 @@
     "RemoteAttachment",
     "Tag",
     "Broadcast",
+    "BatchValidationError",
     # Default HTTP Client
     "RequestsClient",
 ]

resend/emails/_batch.py

@@ -1,6 +1,6 @@
 from typing import Any, Dict, List, Optional, cast
 
-from typing_extensions import NotRequired, TypedDict
+from typing_extensions import Literal, NotRequired, TypedDict
 
 from resend import request
 
@@ -14,6 +14,25 @@ class SendEmailResponse(TypedDict):
     """
 
 
+class BatchValidationError(TypedDict):
+    """
+    BatchValidationError represents a validation error for a specific email in the batch.
+
+    Attributes:
+        index (int): The index of the email in the batch that caused the error
+        message (str): The validation error message
+    """
+
+    index: int
+    """
+    The index of the email in the batch that caused the error.
+    """
+    message: str
+    """
+    The validation error message.
+    """
+
+
 class Batch:
 
     class SendOptions(TypedDict):
@@ -24,6 +43,8 @@ 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.
+            batch_validation (NotRequired[Literal["strict", "permissive"]]): Batch validation mode.
+            Defaults to "strict" when not provided.
         """
 
         idempotency_key: NotRequired[str]
@@ -33,11 +54,21 @@ class SendOptions(TypedDict):
         If provided, will be sent as the `Idempotency-Key` header.
         """
 
+        batch_validation: NotRequired[Literal["strict", "permissive"]]
+        """
+        Batch validation mode.
+        Defaults to "strict" when not provided.
+        """
+
     class SendResponse(TypedDict):
         data: List[SendEmailResponse]
         """
         A list of email objects
         """
+        errors: NotRequired[List[BatchValidationError]]
+        """
+        A list of validation errors (only present in permissive mode)
+        """
 
     @classmethod
     def send(
@@ -49,10 +80,10 @@ def send(
 
         Args:
             params (List[Emails.SendParams]): The list of emails to send
-            options (Optional[SendOptions]): Batch options, ie: idempotency_key
+            options (Optional[SendOptions]): Batch options, including batch_validation mode
 
         Returns:
-            SendResponse: A list of email objects
+            SendResponse: A list of email objects, and optionally validation errors in permissive mode
         """
         path = "/emails/batch"
 

resend/request.py

@@ -56,6 +56,9 @@ def __get_headers(self) -> HeadersType:
         if self.verb == "post" and self.options and "idempotency_key" in self.options:
             headers["Idempotency-Key"] = str(self.options["idempotency_key"])
 
+        if self.verb == "post" and self.options and "batch_validation" in self.options:
+            headers["x-batch-validation"] = str(self.options["batch_validation"])
+
         return headers
 
     def make_request(self, url: str) -> Union[Dict[str, Any], List[Any]]:

tests/batch_emails_test.py

@@ -63,7 +63,7 @@ def test_batch_email_send_with_options(self) -> None:
             },
         ]
 
-        options: resend.Emails.SendOptions = {
+        options: resend.Batch.SendOptions = {
             "idempotency_key": "af477dc78aa9fa91fff3b8c0d4a2e1a5",
         }
 
@@ -90,3 +90,80 @@ def test_should_send_batch_email_raise_exception_when_no_content(self) -> None:
         ]
         with self.assertRaises(NoContentError):
             _ = resend.Batch.send(params)
+
+    def test_batch_email_send_with_strict_validation_mode(self) -> None:
+        self.set_mock_json(
+            {
+                "data": [
+                    {"id": "ae2014de-c168-4c61-8267-70d2662a1ce1"},
+                    {"id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb"},
+                ]
+            }
+        )
+
+        params: List[resend.Emails.SendParams] = [
+            {
+                "from": "from@resend.dev",
+                "to": ["to@resend.dev"],
+                "subject": "hey",
+                "html": "<strong>hello, world!</strong>",
+            },
+            {
+                "from": "from@resend.dev",
+                "to": ["to@resend.dev"],
+                "subject": "hello",
+                "html": "<strong>hello, world!</strong>",
+            },
+        ]
+
+        options: resend.Batch.SendOptions = {
+            "batch_validation": "strict",
+        }
+
+        emails: resend.Batch.SendResponse = resend.Batch.send(params, options=options)
+        assert len(emails["data"]) == 2
+        assert emails["data"][0]["id"] == "ae2014de-c168-4c61-8267-70d2662a1ce1"
+        assert emails["data"][1]["id"] == "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb"
+        assert "errors" not in emails
+
+    def test_batch_email_send_with_permissive_validation_mode(self) -> None:
+        self.set_mock_json(
+            {
+                "data": [
+                    {"id": "ae2014de-c168-4c61-8267-70d2662a1ce1"},
+                ],
+                "errors": [
+                    {
+                        "index": 1,
+                        "message": "The `to` field is missing.",
+                    }
+                ],
+            }
+        )
+
+        params: List[resend.Emails.SendParams] = [
+            {
+                "from": "from@resend.dev",
+                "to": ["to@resend.dev"],
+                "subject": "hey",
+                "html": "<strong>hello, world!</strong>",
+            },
+            {
+                "from": "from@resend.dev",
+                "to": [],
+                "subject": "hello",
+                "html": "<strong>hello, world!</strong>",
+            },
+        ]
+
+        options: resend.Batch.SendOptions = {
+            "batch_validation": "permissive",
+        }
+
+        emails: resend.Batch.SendResponse = resend.Batch.send(params, options=options)
+        assert len(emails["data"]) == 1
+        assert emails["data"][0]["id"] == "ae2014de-c168-4c61-8267-70d2662a1ce1"
+        assert "errors" in emails
+        assert len(emails["errors"]) == 1
+        assert emails["errors"][0]["index"] == 1
+        assert emails["errors"][0]["message"] == "The `to` field is missing."