send-bulk-emails

Instructions

Implementation Reference

• src/requestHandler.ts:179-215 (handler)

  Executes the send-bulk-emails tool: constructs BulkEmailData from tool parameters and delegates to the sendBulkEmails core function.

  async function handleSendBulkEmails(parameters: any) {
    try {
      // Prepare the bulk email data
      const bulkEmailData: BulkEmailData = {
        recipients: parameters.recipients,
        subject: parameters.subject,
        body: parameters.body,
        from: parameters.from,
        cc: parameters.cc,
        bcc: parameters.bcc,
        templateId: parameters.templateId,
        templateData: parameters.templateData,
        batchSize: parameters.batchSize,
        delayBetweenBatches: parameters.delayBetweenBatches
      };
      
      // Send the bulk emails
      const result = await sendBulkEmails(bulkEmailData, parameters.smtpConfigId);
      
      return {
        success: result.success,
        totalSent: result.totalSent,
        totalFailed: result.totalFailed,
        failures: result.failures,
        message: result.message
      };
    } catch (error) {
      logToFile('Error in handleSendBulkEmails:');
      logToFile(error instanceof Error ? error.message : 'Unknown error');
      return {
        success: false,
        totalSent: 0,
        totalFailed: parameters.recipients?.length || 0,
        message: error instanceof Error ? error.message : 'Unknown error'
      };
    }
  }

• src/emailService.ts:231-318 (helper)

  Core bulk email sending logic: batches recipients, creates individual EmailData per recipient (with template personalization), sends via sendEmail, tracks stats and failures.

  export async function sendBulkEmails(data: BulkEmailData, smtpConfigId?: string): Promise<{
    success: boolean;
    totalSent: number;
    totalFailed: number;
    failures?: { email: string; error: string }[];
    message?: string;
  }> {
    try {
      const { recipients, batchSize = 10, delayBetweenBatches = 1000 } = data;
      
      if (!recipients || recipients.length === 0) {
        return { 
          success: false, 
          totalSent: 0, 
          totalFailed: 0,
          message: 'No recipients provided'
        };
      }
      
      const failures: { email: string; error: string }[] = [];
      let totalSent = 0;
      
      // Process recipients in batches
      for (let i = 0; i < recipients.length; i += batchSize) {
        const batch = recipients.slice(i, i + batchSize);
        
        // Send emails to the batch (one by one to allow for individual template processing)
        const promises = batch.map(async (recipient) => {
          try {
            // Create email data for single recipient using the bulk data
            const emailData: EmailData = {
              to: recipient,
              subject: data.subject,
              body: data.body,
              from: data.from,
              cc: data.cc,
              bcc: data.bcc,
              templateId: data.templateId,
              templateData: {
                ...data.templateData,
                email: recipient.email,
                name: recipient.name || ''
              }
            };
            
            const result = await sendEmail(emailData, smtpConfigId);
            
            if (result.success) {
              totalSent++;
              return { success: true };
            } else {
              failures.push({ email: recipient.email, error: result.message || 'Unknown error' });
              return { success: false, error: result.message };
            }
          } catch (error) {
            failures.push({ 
              email: recipient.email, 
              error: error instanceof Error ? error.message : 'Unknown error' 
            });
            return { success: false, error };
          }
        });
        
        await Promise.all(promises);
        
        // If not the last batch, wait before processing the next batch
        if (i + batchSize < recipients.length) {
          await new Promise(resolve => setTimeout(resolve, delayBetweenBatches));
        }
      }
      
      return {
        success: totalSent > 0,
        totalSent,
        totalFailed: failures.length,
        failures: failures.length > 0 ? failures : undefined,
        message: `Successfully sent ${totalSent} out of ${recipients.length} emails`
      };
    } catch (error) {
      logToFile(`Error sending bulk emails: ${error}`);
      return { 
        success: false, 
        totalSent: 0, 
        totalFailed: data.recipients.length,
        message: error instanceof Error ? error.message : 'Unknown error sending bulk emails'
      };
    }
  } 

• src/tools.ts:95-176 (schema)

  Input schema and metadata definition for the send-bulk-emails tool.

  "send-bulk-emails": {
    name: "send-bulk-emails",
    description: "Send emails in bulk to multiple recipients with rate limiting",
    inputSchema: {
      type: "object",
      properties: {
        recipients: {
          type: "array",
          items: {
            type: "object",
            properties: {
              email: { type: "string" },
              name: { type: "string" }
            },
            required: ["email"]
          },
          description: "Array of recipients"
        },
        subject: {
          type: "string",
          description: "Email subject"
        },
        body: {
          type: "string",
          description: "Email body (HTML supported)"
        },
        from: {
          type: "object",
          properties: {
            email: { type: "string" },
            name: { type: "string" }
          },
          description: "Sender information. If not provided, the default SMTP user will be used."
        },
        cc: {
          type: "array",
          items: {
            type: "object",
            properties: {
              email: { type: "string" },
              name: { type: "string" }
            },
            required: ["email"]
          },
          description: "Array of CC recipients"
        },
        bcc: {
          type: "array",
          items: {
            type: "object",
            properties: {
              email: { type: "string" },
              name: { type: "string" }
            },
            required: ["email"]
          },
          description: "Array of BCC recipients"
        },
        templateId: {
          type: "string",
          description: "ID of the email template to use. If not provided, the email will use the subject and body provided."
        },
        templateData: {
          type: "object",
          description: "Data to be used for template variable substitution"
        },
        batchSize: {
          type: "number",
          description: "Number of emails to send in each batch (default: 10)"
        },
        delayBetweenBatches: {
          type: "number",
          description: "Delay between batches in milliseconds (default: 1000)"
        },
        smtpConfigId: {
          type: "string",
          description: "ID of the SMTP configuration to use. If not provided, the default configuration will be used."
        }
      },
      required: ["recipients", "subject", "body"]
    }
  },

• src/index.ts:59-62 (registration)

  Registers the send-bulk-emails tool (among others) by calling createToolDefinitions() and passing the tools record to setupRequestHandlers.

  const TOOLS = createToolDefinitions();
  
  // Setup request handlers
  await setupRequestHandlers(server, TOOLS);