feat: Batch validation mode (#123)

Author: drish

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    resend (0.23.0)
+    resend (0.24.0)
       httparty (>= 0.21.0)
 
 GEM

examples/batch_email.rb

@@ -29,4 +29,41 @@
 # Send a batch of emails with Idempotency key
 emails = Resend::Batch.send(params, options: { idempotency_key: "af67ff1cdf3cdf1" })
 puts "Emails sent with Idempotency key:"
-puts(emails)
+puts(emails)
+
+# Example with batch_validation: permissive
+# This will send valid emails and return errors for invalid ones
+params_with_invalid = [
+  {
+    "from": "[email protected]",
+    "to": ["[email protected]"],
+    "subject": "Valid email",
+    "html": "<strong>This email is valid!</strong>",
+  },
+  {
+    "from": "[email protected]",
+    "to": ["invalid-email"],  # Invalid email format
+    "subject": "Invalid email",
+    "html": "<strong>This email has an invalid recipient!</strong>",
+  },
+]
+
+# Send batch with permissive validation mode
+# This will send the valid email and return error details for the invalid one
+emails = Resend::Batch.send(params_with_invalid, options: { batch_validation: "permissive" })
+puts "\nEmails sent with permissive validation mode:"
+puts "Successful emails:"
+puts emails[:data] if emails[:data]
+puts "Errors:"
+puts emails[:errors] if emails[:errors]
+
+# Send batch with strict validation mode (default behavior)
+# This will fail the entire batch if any email is invalid
+begin
+  emails = Resend::Batch.send(params_with_invalid, options: { batch_validation: "strict" })
+  puts "\nEmails sent with strict validation mode:"
+  puts(emails)
+rescue => e
+  puts "\nStrict validation mode failed as expected:"
+  puts "Error: #{e.message}"
+end

lib/resend/batch.rb

@@ -4,6 +4,27 @@ module Resend
   # Module responsible for wrapping Batch email sending API
   module Batch
     class << self
+      # Send a batch of emails
+      #
+      # @param params [Array<Hash>] Array of email parameters (max 100 emails)
+      # @param options [Hash] Additional options for the request
+      # @option options [String] :idempotency_key Optional idempotency key
+      # @option options [String] :batch_validation Batch validation mode: "strict" (default) or "permissive"
+      #   - "strict": Entire batch fails if any email is invalid
+      #   - "permissive": Sends valid emails and returns errors for invalid ones
+      #
+      # @return [Hash] Response with :data array and optional :errors array (in permissive mode)
+      #
+      # @example Send batch with strict validation (default)
+      #   Resend::Batch.send([
+      #     { from: "[email protected]", to: ["[email protected]"], subject: "Hello", html: "<p>Hi</p>" }
+      #   ])
+      #
+      # @example Send batch with permissive validation
+      #   response = Resend::Batch.send(emails, options: { batch_validation: "permissive" })
+      #   # response[:data] contains successful email IDs
+      #   # response[:errors] contains validation errors with index and message
+      #
       # https://resend.com/docs/api-reference/emails/send-batch-emails
       def send(params = [], options: {})
         path = "emails/batch"

lib/resend/request.rb

@@ -25,6 +25,7 @@ def initialize(path = "", body = {}, verb = "POST", options: {})
       }
 
       set_idempotency_key
+      set_batch_validation
     end
 
     # Performs the HTTP call
@@ -66,6 +67,14 @@ def set_idempotency_key
       end
     end
 
+    def set_batch_validation
+      # Set x-batch-validation header for batch emails
+      # Supported values: 'strict' (default) or 'permissive'
+      if @path == "emails/batch" && @options[:batch_validation]
+        @headers["x-batch-validation"] = @options[:batch_validation]
+      end
+    end
+
     def check_json!(resp)
       if resp.body.is_a?(Hash)
         JSON.parse(resp.body.to_json)

spec/batch_spec.rb

@@ -138,5 +138,132 @@
         }
       )
     end
+
+    it "does not send the x-batch-validation header when :batch_validation is not provided" do
+      resp = {
+        "data": [
+          { "id": "ae2014de-c168-4c61-8267-70d2662a1ce1" },
+          { "id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb" }
+        ]
+      }
+
+      allow(resp).to receive(:body).and_return(resp)
+      allow(HTTParty).to receive(:send).and_return(resp)
+
+      Resend::Batch.send([{ from: "me" }])
+
+      expect(HTTParty).to have_received(:send).with(
+        :post,
+        "#{Resend::Request::BASE_URL}emails/batch",
+        {
+          headers: {
+            "Content-Type" => "application/json",
+            "Accept" => "application/json",
+            "Authorization" => "Bearer re_123",
+            "User-Agent" => "resend-ruby:#{Resend::VERSION}",
+          },
+          body: [{ from: "me" }].to_json
+        }
+      )
+    end
+
+    it "sends the x-batch-validation header when :batch_validation is set to permissive" do
+      resp = {
+        "data": [
+          { "id": "ae2014de-c168-4c61-8267-70d2662a1ce1" }
+        ],
+        "errors": [
+          { "index": 1, "message": "Invalid email address" }
+        ]
+      }
+
+      allow(resp).to receive(:body).and_return(resp)
+      allow(HTTParty).to receive(:send).and_return(resp)
+
+      Resend::Batch.send([{ from: "me" }], options: { batch_validation: "permissive" })
+
+      expect(HTTParty).to have_received(:send).with(
+        :post,
+        "#{Resend::Request::BASE_URL}emails/batch",
+        {
+          headers: {
+            "Content-Type" => "application/json",
+            "Accept" => "application/json",
+            "Authorization" => "Bearer re_123",
+            "User-Agent" => "resend-ruby:#{Resend::VERSION}",
+            "x-batch-validation" => "permissive"
+          },
+          body: [{ from: "me" }].to_json
+        }
+      )
+    end
+
+    it "sends the x-batch-validation header when :batch_validation is set to strict" do
+      resp = {
+        "data": [
+          { "id": "ae2014de-c168-4c61-8267-70d2662a1ce1" },
+          { "id": "faccb7a5-8a28-4e9a-ac64-8da1cc3bc1cb" }
+        ]
+      }
+
+      allow(resp).to receive(:body).and_return(resp)
+      allow(HTTParty).to receive(:send).and_return(resp)
+
+      Resend::Batch.send([{ from: "me" }], options: { batch_validation: "strict" })
+
+      expect(HTTParty).to have_received(:send).with(
+        :post,
+        "#{Resend::Request::BASE_URL}emails/batch",
+        {
+          headers: {
+            "Content-Type" => "application/json",
+            "Accept" => "application/json",
+            "Authorization" => "Bearer re_123",
+            "User-Agent" => "resend-ruby:#{Resend::VERSION}",
+            "x-batch-validation" => "strict"
+          },
+          body: [{ from: "me" }].to_json
+        }
+      )
+    end
+
+    it "handles response with errors array in permissive mode" do
+      resp = {
+        "data": [
+          { "id": "ae2014de-c168-4c61-8267-70d2662a1ce1" }
+        ],
+        "errors": [
+          {
+            "index": 1,
+            "message": "The 'to' field must be a valid email address"
+          }
+        ]
+      }
+
+      params = [
+        {
+          "from": "[email protected]",
+          "to": ["[email protected]"],
+          "text": "testing",
+          "subject": "Hey",
+        },
+        {
+          "from": "[email protected]",
+          "to": ["invalid-email"],
+          "text": "testing",
+          "subject": "Hello",
+        },
+      ]
+
+      allow_any_instance_of(Resend::Request).to receive(:perform).and_return(resp)
+
+      result = Resend::Batch.send(params, options: { batch_validation: "permissive" })
+
+      expect(result[:data].length).to eq 1
+      expect(result[:errors]).not_to be_nil
+      expect(result[:errors].length).to eq 1
+      expect(result[:errors][0][:index]).to eq 1
+      expect(result[:errors][0][:message]).to include("valid email address")
+    end
   end
 end