Allow to, cc or bcc for batch transactional emails

Author: IgorDobryn

src/tools/sendEmail/__tests__/batchSendTransactionalEmail.test.ts

@@ -130,6 +130,52 @@ describe("batchSendTransactionalEmail", () => {
     expect(result.content[0].text).toContain("'subject' is required");
   });
 
+  it("sends successfully when `to` is omitted but `cc`/`bcc` is provided", async () => {
+    mockClient.batchSend.mockResolvedValue({
+      success: true,
+      responses: [{ success: true, message_ids: ["m-1"] }],
+    });
+
+    await batchSendTransactionalEmail({
+      base: { from: "sender@example.com", subject: "Hi", text: "Hello" },
+      requests: [
+        {
+          cc: ["carol@example.com"],
+          bcc: ["dan@example.com"],
+        },
+      ],
+    });
+
+    expect(mockClient.batchSend).toHaveBeenCalledWith({
+      base: {
+        from: { email: "sender@example.com" },
+        subject: "Hi",
+        text: "Hello",
+      },
+      requests: [
+        {
+          to: [],
+          cc: [{ email: "carol@example.com" }],
+          bcc: [{ email: "dan@example.com" }],
+        },
+      ],
+    });
+  });
+
+  it("errors when none of `to`/`cc`/`bcc` has a recipient", async () => {
+    const result = await batchSendTransactionalEmail({
+      base: { from: "sender@example.com", subject: "Hi", text: "x" },
+      requests: [{}],
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("requests[0]:");
+    expect(result.content[0].text).toContain(
+      "provide at least one recipient via 'to', 'cc', or 'bcc'"
+    );
+    expect(mockClient.batchSend).not.toHaveBeenCalled();
+  });
+
   it("surfaces API errors", async () => {
     mockClient.batchSend.mockRejectedValue(new Error("rate limited"));
 

src/tools/sendEmail/batchSendTransactionalEmail.ts

@@ -109,12 +109,25 @@ async function batchSendTransactionalEmail({
       sdkBase.custom_variables = base.custom_variables;
     if (base?.headers !== undefined) sdkBase.headers = base.headers;
 
-    const sdkRequests = requests.map((req) => {
+    const sdkRequests = requests.map((req, i) => {
+      const toAddresses =
+        req.to !== undefined ? normalizeToRecipients(req.to) : [];
+      const ccAddresses =
+        req.cc && req.cc.length > 0 ? normalizeAddressList(req.cc) : [];
+      const bccAddresses =
+        req.bcc && req.bcc.length > 0 ? normalizeAddressList(req.bcc) : [];
+
+      if (toAddresses.length + ccAddresses.length + bccAddresses.length === 0) {
+        throw new Error(
+          `requests[${i}]: provide at least one recipient via 'to', 'cc', or 'bcc'`
+        );
+      }
+
       const r: Record<string, unknown> = {
-        to: normalizeToRecipients(req.to),
+        to: toAddresses,
       };
-      if (req.cc && req.cc.length > 0) r.cc = normalizeAddressList(req.cc);
-      if (req.bcc && req.bcc.length > 0) r.bcc = normalizeAddressList(req.bcc);
+      if (ccAddresses.length > 0) r.cc = ccAddresses;
+      if (bccAddresses.length > 0) r.bcc = bccAddresses;
       if (req.reply_to) r.reply_to = [toMailtrapAddress(req.reply_to)];
       if (req.subject !== undefined) r.subject = req.subject;
       if (req.text !== undefined) r.text = req.text;

src/tools/sendEmail/schemas/batchSendTransactionalEmail.ts

@@ -78,14 +78,14 @@ const batchSendTransactionalEmailSchema = {
       type: "array",
       minItems: 1,
       description:
-        "Per-recipient messages. Each entry must include `to`; other fields override `base`.",
+        "Per-recipient messages. Each request must include at least one recipient via `to`, `cc`, or `bcc`; other fields override `base`.",
       items: {
         type: "object",
         properties: {
           to: {
             ...addressArrayOrSingle,
             description:
-              "Recipient(s): one address (string or `{ email, name? }`) or a non-empty array.",
+              "Recipient(s): one address (string or `{ email, name? }`) or a non-empty array. Optional if `cc` or `bcc` is provided; at least one of `to`/`cc`/`bcc` must contain a recipient.",
           },
           cc: {
             type: "array",
@@ -103,7 +103,6 @@ const batchSendTransactionalEmailSchema = {
           },
           ...inlineOrTemplateProps,
         },
-        required: ["to"],
         additionalProperties: false,
       },
     },

src/types/mailtrap.ts

@@ -58,11 +58,12 @@ export interface BatchSendEmailBase {
 }
 
 /**
- * Per-recipient override in a batch send. `to` is required; any other field
- * overrides the corresponding `base` value for this single message.
+ * Per-recipient override in a batch send. At least one of `to`/`cc`/`bcc`
+ * must contain a recipient (validated at runtime); any other field overrides
+ * the corresponding `base` value for this single message.
  */
 export interface BatchSendEmailRequest {
-  to: MailtrapAddressParam | MailtrapAddressParam[];
+  to?: MailtrapAddressParam | MailtrapAddressParam[];
   cc?: MailtrapAddressParam[];
   bcc?: MailtrapAddressParam[];
   reply_to?: MailtrapAddressParam;