Implement /batch method for sending/testing/bulk emails

examples/java/io/mailtrap/examples/bulk/Batch.java

@@ -0,0 +1,43 @@
+package io.mailtrap.examples.bulk;
+
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.emails.Address;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
+import io.mailtrap.model.request.emails.BatchEmailBase;
+import io.mailtrap.model.request.emails.MailtrapMail;
+
+import java.util.List;
+import java.util.Map;
+
+public class Batch {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final String SENDER_EMAIL = "sender@domain.com";
+    private static final String RECIPIENT_EMAIL = "recipient@domain.com";
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+            .token(TOKEN)
+            .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+
+        final var mail = MailtrapMail.builder()
+            .from(new Address(SENDER_EMAIL))
+            .to(List.of(new Address(RECIPIENT_EMAIL)))
+            .subject("Hello from Mailtrap!")
+            .text("Welcome to Mailtrap Bulk Sending!")
+            .build();
+
+        final var batchMail = MailtrapBatchMail.builder()
+            // Optionally you can add this `base` object - if you have some common data across emails
+            // Each property can be overridden in `requests` for individual emails
+            .base(BatchEmailBase.builder().subject("Base Subject for all emails").build())
+            .requests(List.of(mail))
+            .build();
+
+        System.out.println(client.bulkSendingApi().emails().batchSend(batchMail));
+    }
+
+}

examples/java/io/mailtrap/examples/sending/Batch.java

@@ -0,0 +1,43 @@
+package io.mailtrap.examples.sending;
+
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.emails.Address;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
+import io.mailtrap.model.request.emails.BatchEmailBase;
+import io.mailtrap.model.request.emails.MailtrapMail;
+
+import java.util.List;
+import java.util.Map;
+
+public class Batch {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final String SENDER_EMAIL = "sender@domain.com";
+    private static final String RECIPIENT_EMAIL = "recipient@domain.com";
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+            .token(TOKEN)
+            .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+
+        final var mail = MailtrapMail.builder()
+            .from(new Address(SENDER_EMAIL))
+            .to(List.of(new Address(RECIPIENT_EMAIL)))
+            .subject("Hello from Mailtrap Sending!")
+            .text("Welcome to Mailtrap Sending!")
+            .build();
+
+        final var batchMail = MailtrapBatchMail.builder()
+            // Optionally you can add this `base` object - if you have some common data across emails
+            // Each property can be overridden in `requests` for individual emails
+            .base(BatchEmailBase.builder().subject("Base Subject for all emails").build())
+            .requests(List.of(mail))
+            .build();
+
+        System.out.println(client.sendingApi().emails().batchSend(batchMail));
+    }
+
+}

examples/java/io/mailtrap/examples/testing/Batch.java

@@ -0,0 +1,48 @@
+package io.mailtrap.examples.testing;
+
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.emails.Address;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
+import io.mailtrap.model.request.emails.BatchEmailBase;
+import io.mailtrap.model.request.emails.MailtrapMail;
+
+import java.util.List;
+import java.util.Map;
+
+public class Batch {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final String SENDER_EMAIL = "sender@domain.com";
+    private static final String RECIPIENT_EMAIL = "recipient@domain.com";
+    private static final long INBOX_ID = 1337L;
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+            .token(TOKEN)
+            .inboxId(INBOX_ID)
+            .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+
+        final var mail = MailtrapMail.builder()
+            .from(new Address("John Doe", SENDER_EMAIL))
+            .to(List.of(new Address("Jane Doe", RECIPIENT_EMAIL)))
+            .templateUuid("813t39es-t74i-4308-b037-0n6bg8b1fe88")
+            .templateVariables(Map.of(
+                "user_name", "Jack Sparrow",
+                "testing_template", "true"
+            ))
+            .build();
+
+        final var batchMail = MailtrapBatchMail.builder()
+            // Optionally you can add this `base` object - if you have some common data across emails
+            // Each property can be overridden in `requests` for individual emails
+            .base(BatchEmailBase.builder().templateUuid("base-template-uuid").build())
+            .requests(List.of(mail))
+            .build();
+
+        System.out.println(client.testingApi().emails().batchSend(batchMail, config.getInboxId()));
+    }
+
+}

src/main/java/io/mailtrap/api/apiresource/SendApiResource.java

@@ -3,10 +3,18 @@
 import io.mailtrap.CustomValidator;
 import io.mailtrap.config.MailtrapConfig;
 import io.mailtrap.exception.InvalidRequestBodyException;
+import io.mailtrap.model.mailvalidation.ContentView;
+import io.mailtrap.model.mailvalidation.MailContentView;
+import io.mailtrap.model.mailvalidation.ResolvedMailContentView;
+import io.mailtrap.model.mailvalidation.ResolvedMailView;
+import io.mailtrap.model.request.emails.BatchEmailBase;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
 import io.mailtrap.model.request.emails.MailtrapMail;
 import org.apache.commons.collections4.MapUtils;
 import org.apache.commons.lang3.StringUtils;
 
+import java.util.Objects;
+
 /**
  * Abstract class representing a resource for sending emails via Mailtrap API.
  */
@@ -22,51 +30,87 @@ protected SendApiResource(MailtrapConfig config, CustomValidator customValidator
      * @param mail The email message to be validated.
      * @throws InvalidRequestBodyException If the request body is invalid.
      */
-    protected void validateRequestBodyOrThrowException(MailtrapMail mail) throws InvalidRequestBodyException {
-        // Check if the mail object itself is null
+    protected void validateMailPayload(MailtrapMail mail) {
         if (mail == null) {
             throw new InvalidRequestBodyException("Mail must not be null");
         }
 
-        // Check if all three subject, text, and html are empty
-        boolean isSubjectTextHtmlEmpty = StringUtils.isEmpty(mail.getSubject())
-                && StringUtils.isEmpty(mail.getText())
-                && StringUtils.isEmpty(mail.getHtml());
-
-        // Validate depending on whether the templateUuid is set
-        if (StringUtils.isEmpty(mail.getTemplateUuid())) {
-            // Validation for the scenario where templateUuid is not provided
-            validateWithoutTemplate(mail, isSubjectTextHtmlEmpty);
-        } else {
-            // Validation for the scenario where templateUuid is provided
-            validateWithTemplate(mail);
-        }
-
-        // Additional validation logic (assumed to be provided by the user)
+        // Perform bean validation (NotNull, etc.)
         validateRequestBodyAndThrowException(mail);
+
+        // Validate subject/text/html/templateUuid
+        validateContentRules(MailContentView.of(mail));
     }
 
-    private void validateWithoutTemplate(MailtrapMail mail, boolean isSubjectTextHtmlEmpty) throws InvalidRequestBodyException {
-        // Ensure that at least subject, text, or html is provided if templateUuid is not set
-        if (isSubjectTextHtmlEmpty) {
-            throw new InvalidRequestBodyException("Mail must have subject and either text or html when templateUuid is not provided");
-        }
+    /**
+     * Validates the request body of batch email and throws an exception if it is invalid.
+     *
+     * @param batch batch request to be validated.
+     * @throws InvalidRequestBodyException If the request body is invalid.
+     */
+    protected void validateBatchPayload(MailtrapBatchMail batch) {
+        assertBatchMailNotNull(batch);
+
+        BatchEmailBase base = batch.getBase();
 
-        // Ensure templateVariables are not used if templateUuid is not set
-        if (MapUtils.isNotEmpty(mail.getTemplateVariables())) {
-            throw new InvalidRequestBodyException("Mail templateVariables must only be used with templateUuid");
+        for (int i = 0; i < batch.getRequests().size(); i++) {
+            MailtrapMail mail = batch.getRequests().get(i);
+            ResolvedMailView mailView = new ResolvedMailView(base, mail);
+
+            try {
+                // Perform bean validation (NotNull, etc.)
+                validateRequestBodyAndThrowException(mailView);
+            } catch (InvalidRequestBodyException e) {
+                throw new InvalidRequestBodyException("requests[" + i + "]: " + e.getMessage(), e);
+            }
+
+            validateContentRules(ResolvedMailContentView.of(mailView));
+
+            if (mailView.getFrom() == null) {
+                throw new InvalidRequestBodyException("requests[" + i + "]: from is required (either in mail or base)");
+            }
         }
+    }
 
-        // Ensure the subject is not empty
-        if (StringUtils.isEmpty(mail.getSubject())) {
-            throw new InvalidRequestBodyException("Subject must not be null or empty");
+    private void assertBatchMailNotNull(MailtrapBatchMail batchMail) {
+        if (batchMail == null) {
+            throw new InvalidRequestBodyException("BatchMail must not be null");
+        }
+        if (batchMail.getRequests() == null || batchMail.getRequests().isEmpty()) {
+            throw new InvalidRequestBodyException("BatchMail.requests must not be null or empty");
+        }
+        if (batchMail.getRequests().stream().anyMatch(Objects::isNull)) {
+            throw new InvalidRequestBodyException("BatchMail.requests must not contain null items");
         }
+
     }
 
-    private void validateWithTemplate(MailtrapMail mail) throws InvalidRequestBodyException {
-        // Ensure that subject, text, and html are not used when templateUuid is set
-        if (StringUtils.isNotEmpty(mail.getText()) || StringUtils.isNotEmpty(mail.getHtml()) || StringUtils.isNotEmpty(mail.getSubject())) {
-            throw new InvalidRequestBodyException("When templateUuid is used, subject, text, and html must not be used");
+    private void validateContentRules(ContentView v) {
+        boolean templateUuidBlank = StringUtils.isBlank(v.getTemplateUuid());
+
+        boolean subjectTextHtmlEmpty = StringUtils.isBlank(v.getSubject())
+            && StringUtils.isBlank(v.getText())
+            && StringUtils.isBlank(v.getHtml());
+
+        if (templateUuidBlank) {
+            if (subjectTextHtmlEmpty) {
+                throw new InvalidRequestBodyException("Mail must have subject and either text or html when templateUuid is not provided");
+            }
+            if (MapUtils.isNotEmpty(v.getTemplateVariables())) {
+                throw new InvalidRequestBodyException("Mail templateVariables must only be used with templateUuid");
+            }
+            if (StringUtils.isBlank(v.getSubject())) {
+                throw new InvalidRequestBodyException("Subject must not be null or empty");
+            }
+            if (StringUtils.isBlank(v.getText()) && StringUtils.isBlank(v.getHtml())) {
+                throw new InvalidRequestBodyException("Mail must have subject and either text or html when templateUuid is not provided");
+            }
+        } else {
+            if (StringUtils.isNotEmpty(v.getSubject())
+                || StringUtils.isNotEmpty(v.getText())
+                || StringUtils.isNotEmpty(v.getHtml()))
+                throw new InvalidRequestBodyException("When templateUuid is used, subject, text, and html must not be used");
         }
     }
+
 }

src/main/java/io/mailtrap/api/bulkemails/BulkEmails.java

@@ -2,7 +2,9 @@
 
 import io.mailtrap.exception.InvalidRequestBodyException;
 import io.mailtrap.exception.http.HttpException;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
 import io.mailtrap.model.request.emails.MailtrapMail;
+import io.mailtrap.model.response.emails.BatchSendResponse;
 import io.mailtrap.model.response.emails.SendResponse;
 
 /**
@@ -20,4 +22,6 @@ public interface BulkEmails {
      * @throws InvalidRequestBodyException If the request body is invalid.
      */
     SendResponse send(MailtrapMail mail) throws HttpException, InvalidRequestBodyException;
+
+    BatchSendResponse batchSend(MailtrapBatchMail mail) throws HttpException, InvalidRequestBodyException;
 }

src/main/java/io/mailtrap/api/bulkemails/BulkEmailsImpl.java

@@ -4,8 +4,12 @@
 import io.mailtrap.CustomValidator;
 import io.mailtrap.api.apiresource.SendApiResource;
 import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.exception.InvalidRequestBodyException;
+import io.mailtrap.exception.http.HttpException;
 import io.mailtrap.http.RequestData;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
 import io.mailtrap.model.request.emails.MailtrapMail;
+import io.mailtrap.model.response.emails.BatchSendResponse;
 import io.mailtrap.model.response.emails.SendResponse;
 
 /**
@@ -20,11 +24,20 @@ public BulkEmailsImpl(MailtrapConfig config, CustomValidator customValidator) {
 
     @Override
     public SendResponse send(MailtrapMail mail) {
-        validateRequestBodyOrThrowException(mail);
+        validateMailPayload(mail);
         RequestData requestData = new RequestData();
         if (mail.getHeaders() != null) {
             requestData.setHeaders(mail.getHeaders());
         }
         return httpClient.post(apiHost + "/api/send", mail, requestData, SendResponse.class);
     }
+
+    @Override
+    public BatchSendResponse batchSend(MailtrapBatchMail mail) throws HttpException, InvalidRequestBodyException {
+        validateBatchPayload(mail);
+
+        return
+            httpClient.post(apiHost + "/api/batch", mail, new RequestData(), BatchSendResponse.class);
+
+    }
 }

src/main/java/io/mailtrap/api/sendingemails/SendingEmails.java

@@ -2,7 +2,9 @@
 
 import io.mailtrap.exception.InvalidRequestBodyException;
 import io.mailtrap.exception.http.HttpException;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
 import io.mailtrap.model.request.emails.MailtrapMail;
+import io.mailtrap.model.response.emails.BatchSendResponse;
 import io.mailtrap.model.response.emails.SendResponse;
 
 /**
@@ -20,4 +22,6 @@ public interface SendingEmails {
      * @throws InvalidRequestBodyException If the request body is invalid.
      */
     SendResponse send(MailtrapMail mail) throws HttpException, InvalidRequestBodyException;
+
+    BatchSendResponse batchSend(MailtrapBatchMail mail) throws HttpException, InvalidRequestBodyException;
 }

src/main/java/io/mailtrap/api/sendingemails/SendingEmailsImpl.java

@@ -4,8 +4,12 @@
 import io.mailtrap.CustomValidator;
 import io.mailtrap.api.apiresource.SendApiResource;
 import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.exception.InvalidRequestBodyException;
+import io.mailtrap.exception.http.HttpException;
 import io.mailtrap.http.RequestData;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
 import io.mailtrap.model.request.emails.MailtrapMail;
+import io.mailtrap.model.response.emails.BatchSendResponse;
 import io.mailtrap.model.response.emails.SendResponse;
 
 /**
@@ -20,12 +24,20 @@ public SendingEmailsImpl(MailtrapConfig config, CustomValidator customValidator)
 
     @Override
     public SendResponse send(MailtrapMail mail) {
-        validateRequestBodyOrThrowException(mail);
+        validateMailPayload(mail);
         RequestData requestData = new RequestData();
         if (mail.getHeaders() != null) {
             requestData.setHeaders(mail.getHeaders());
         }
         return httpClient.post(apiHost + "/api/send", mail, requestData, SendResponse.class);
     }
 
+    @Override
+    public BatchSendResponse batchSend(MailtrapBatchMail mail) throws HttpException, InvalidRequestBodyException {
+        validateBatchPayload(mail);
+
+        return
+            httpClient.post(apiHost + "/api/batch", mail, new RequestData(), BatchSendResponse.class);
+    }
+
 }

src/main/java/io/mailtrap/api/testingemails/TestingEmails.java

@@ -2,7 +2,9 @@
 
 import io.mailtrap.exception.InvalidRequestBodyException;
 import io.mailtrap.exception.http.HttpException;
+import io.mailtrap.model.request.emails.MailtrapBatchMail;
 import io.mailtrap.model.request.emails.MailtrapMail;
+import io.mailtrap.model.response.emails.BatchSendResponse;
 import io.mailtrap.model.response.emails.SendResponse;
 
 /**
@@ -21,4 +23,6 @@ public interface TestingEmails {
      * @throws InvalidRequestBodyException If the request body is invalid.
      */
     SendResponse send(MailtrapMail mail, long inboxId) throws HttpException, InvalidRequestBodyException;
+
+    BatchSendResponse batchSend(MailtrapBatchMail mail, long inboxId) throws HttpException, InvalidRequestBodyException;
 }