Batch Sending Api

examples/batch.rb

@@ -0,0 +1,105 @@
+require 'mailtrap'
+require 'base64'
+
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+
+# Set your API credentials as environment variables
+# export MAILTRAP_API_KEY='your-api-key'
+#
+# client = Mailtrap::Client.new
+# Bulk sending (@see https://help.mailtrap.io/article/113-sending-streams)
+# client = Mailtrap::Client.new(bulk: true)
+# Sandbox sending (@see https://help.mailtrap.io/article/109-getting-started-with-mailtrap-email-testing)
+# client = Mailtrap::Client.new(sandbox: true, inbox_id: 12)
+
+# Batch sending with Mailtrap::Mail::Base
+mail = Mailtrap::Mail.batch_base_from_content(
+  from: { email: '[email protected]', name: 'Mailtrap Test' },
+  subject: 'You are awesome!',
+  text: 'Congrats for sending test email with Mailtrap!',
+  category: 'Integration Test',
+  # attachments: [
+  #   {
+  #     content: Base64.encode64('Attachment content'), # base64 encoded content or IO string
+  #     filename: 'attachment.txt'
+  #   }
+  # ],
+  headers: {
+    'X-MT-Header': 'Custom header'
+  },
+  custom_variables: {
+    year: 2022
+  }
+)
+
+client.send_batch(
+  mail, [
+    Mailtrap::Mail.from_content(
+      to: [
+        { email: '[email protected]', name: 'recipient1' }
+      ]
+    ),
+    Mailtrap::Mail::Base.new(
+      to: [
+        { email: '[email protected]', name: 'recipient2' }
+      ]
+    )
+  ]
+)
+
+# Batch sending with Mailtrap::Mail::Base
+mail = Mailtrap::Mail.batch_base_from_template(
+  from: { email: '[email protected]', name: 'Mailtrap Test' },
+  reply_to: { email: '[email protected]', name: 'Mailtrap Reply-To' },
+  template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c',
+  template_variables: {
+    'user_name' => 'John Doe'
+  }
+)
+
+client.send_batch(
+  mail, [
+    Mailtrap::Mail::Base.new(
+      to: [
+        { email: '[email protected]', name: 'recipient1' }
+      ]
+    ),
+    Mailtrap::Mail::Base.new(
+      to: [
+        { email: '[email protected]', name: 'recipient2' }
+      ],
+      template_variables: {
+        'user_name' => 'John Doe 1',
+        'user_name2' => 'John Doe 2'
+      }
+    )
+  ]
+)
+
+# You can also pass the request parameters directly
+client.send_batch(
+  {
+    from: { email: '[email protected]', name: 'Mailtrap Test' },
+    reply_to: { email: '[email protected]', name: 'Mailtrap Reply-To' },
+    template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c',
+    template_variables: {
+      'user_name' => 'John Doe'
+    },
+  },
+  [
+    {
+      to: [
+        { email: '[email protected]', name: 'recipient1' }
+      ]
+    },
+    {
+      to: [
+        { email: '[email protected]', name: 'recipient2' }
+      ],
+      template_variables: {
+        'user_name' => 'John Doe 1',
+        'user_name2' => 'John Doe 2'
+      }
+    }
+  ]
+)

lib/mailtrap/client.rb

@@ -37,11 +37,9 @@ def initialize( # rubocop:disable Metrics/ParameterLists
       sandbox: false,
       inbox_id: nil
     )
-      raise ArgumentError, 'api_key is required' if api_key.nil?
-      raise ArgumentError, 'api_port is required' if api_port.nil?
+      validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
 
       api_host ||= select_api_host(bulk:, sandbox:)
-      raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
 
       @api_key = api_key
       @api_host = api_host
@@ -53,6 +51,71 @@ def initialize( # rubocop:disable Metrics/ParameterLists
       @http_clients = {}
     end
 
+    # Sends a batch of emails.
+    # @example
+    #  mail = Mailtrap::Mail::Base.new(
+    #    from: { email: '[email protected]', name: 'Mailtrap Test' },
+    #    reply_to: { email: '[email protected]', name: 'Mailtrap Reply-To' },
+    #    template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c',
+    #    template_variables: {
+    #      'user_name' => 'John Doe'
+    #    }
+    #  )
+    #
+    #  client.send_batch(mail, [
+    #                      Mailtrap::Mail::Base.new(
+    #                        to: [
+    #                          { email: '[email protected]', name: 'recipient1' }
+    #                        ]
+    #                      ),
+    #                      Mailtrap::Mail::Base.new(
+    #                        to: [
+    #                          { email: '[email protected]', name: 'recipient2' }
+    #                        ],
+    #                        template_variables: {
+    #                          'user_name' => 'John Doe 1',
+    #                          'user_name2' => 'John Doe 2'
+    #                        }
+    #                      )
+    #                    ])
+    #
+    # @example
+    #  client.send_batch({
+    #    from: { email: '[email protected]', name: 'Mailtrap Test' },
+    #    reply_to: { email: '[email protected]', name: 'Mailtrap Reply-To' },
+    #    template_uuid: '339c8ab0-e73c-4269-984e-0d2446aacf2c',
+    #    template_variables: {
+    #      'user_name' => 'John Doe'
+    #    },
+    #  },
+    #  [
+    #    {
+    #      to: [
+    #        { email: '[email protected]', name: 'recipient1' }
+    #      ]
+    #    },
+    #    {
+    #      to: [
+    #        { email: '[email protected]', name: 'recipient2' }
+    #      ],
+    #      template_variables: {
+    #        'user_name' => 'John Doe 1',
+    #        'user_name2' => 'John Doe 2'
+    #      }
+    #    }
+    #  ])
+    # @param base [#to_json] The base email configuration for the batch.
+    # @param requests [Array<#to_json>] Array of individual email requests.
+    # @return [Hash] The JSON response from the API.
+    # @!macro api_errors
+    # @raise [Mailtrap::MailSizeError] If the message is too large.
+    def send_batch(base, requests)
+      perform_request(:post, api_host, batch_request_path, {
+                        base:,
+                        requests:
+                      })
+    end
+
     # Sends an email
     # @example
     #   mail = Mailtrap::Mail.from_template(
@@ -124,8 +187,6 @@ def http_client_for(host)
     end
 
     def select_api_host(bulk:, sandbox:)
-      raise ArgumentError, 'bulk mode is not applicable for sandbox API' if bulk && sandbox
-
       if sandbox
         SANDBOX_API_HOST
       elsif bulk
@@ -139,6 +200,10 @@ def send_path
       "/api/send#{"/#{inbox_id}" if sandbox}"
     end
 
+    def batch_request_path
+      "/api/batch#{"/#{inbox_id}" if sandbox}"
+    end
+
     def perform_request(method, host, path, body = nil)
       http_client = http_client_for(host)
       request = setup_request(method, path, body)
@@ -203,5 +268,12 @@ def response_errors(body)
     def json_response(body)
       JSON.parse(body, symbolize_names: true)
     end
+
+    def validate_args!(api_key, api_port, bulk, sandbox, inbox_id)
+      raise ArgumentError, 'api_key is required' if api_key.nil?
+      raise ArgumentError, 'api_port is required' if api_port.nil?
+      raise ArgumentError, 'bulk stream is not applicable for sandbox API' if bulk && sandbox
+      raise ArgumentError, 'inbox_id is required for sandbox API' if sandbox && inbox_id.nil?
+    end
   end
 end

lib/mailtrap/mail.rb

@@ -117,6 +117,69 @@ def from_content( # rubocop:disable Metrics/ParameterLists
         )
       end
 
+      # Builds a mail object that will be sent using a pre-defined email
+      # template. The template content (subject, text, html, category) is
+      # defined in the Mailtrap dashboard and referenced by the template_uuid.
+      # Template variables can be passed to customize the template content.
+      # @example
+      #   mail = Mailtrap::Mail.batch_base_from_template(
+      #     from: { email: '[email protected]', name: 'Mailtrap Test' },
+      #     template_uuid: '2f45b0aa-bbed-432f-95e4-e145e1965ba2',
+      #     template_variables: {
+      #       'user_name' => 'John Doe'
+      #     }
+      #   )
+      def batch_base_from_template( # rubocop:disable Metrics/ParameterLists
+        from: nil,
+        reply_to: nil,
+        attachments: [],
+        headers: {},
+        custom_variables: {},
+        template_uuid: nil,
+        template_variables: {}
+      )
+        Mailtrap::Mail::Base.new(
+          from:,
+          reply_to:,
+          attachments:,
+          headers:,
+          custom_variables:,
+          template_uuid:,
+          template_variables:
+        )
+      end
+
+      # Builds a mail object with content including subject, text, html, and category.
+      # @example
+      #   mail = Mailtrap::Mail.batch_base_from_content(
+      #     from: { email: '[email protected]', name: 'Mailtrap Test' },
+      #     subject: 'You are awesome!',
+      #     text: 'Congrats for sending test email with Mailtrap!'
+      #   )
+      def batch_base_from_content( # rubocop:disable Metrics/ParameterLists
+        from: nil,
+        reply_to: nil,
+        attachments: [],
+        headers: {},
+        custom_variables: {},
+        subject: nil,
+        text: nil,
+        html: nil,
+        category: nil
+      )
+        Mailtrap::Mail::Base.new(
+          from:,
+          reply_to:,
+          attachments:,
+          headers:,
+          custom_variables:,
+          subject:,
+          text:,
+          html:,
+          category:
+        )
+      end
+
       # Builds a mail object from Mail::Message
       # @param message [Mail::Message]
       # @return [Mailtrap::Mail::Base]