🚀 Multi Email Sender

The Ultimate Node.js Email Automation Solution

🎯 What Makes This Special?

Transform your email operations with our enterprise-grade solution that combines intelligent automation, smart analytics, and bulletproof reliability. Whether you're sending 10 emails or 10,000, we've got you covered!

🌟 Why Developers Love Us

• 🧠 Smart Retry Logic - Never lose an email again with intelligent exponential backoff
• ⚡ Adaptive Rate Limiting - Automatically adjusts to your email provider's limits
• 📊 Real-time Analytics - Track success rates, performance metrics, and delivery insights
• 🎨 Template Engine - Create personalized emails with dynamic content
• 🛡️ Enterprise Security - Built with production-grade error handling and validation
• 📈 Scalable Architecture - Handles everything from startups to enterprise workloads

🚀 Quick Start (30 seconds)

npm install @prathammahajan/multi-email-sender

import { EmailSender } from '@prathammahajan/multi-email-sender';

// 🎯 Initialize with your email provider
const sender = new EmailSender({
  email: {
    service: 'gmail',
    auth: {
      user: '[email protected]',
      pass: 'your-app-password' // Use app password for Gmail
    }
  }
});

// 📧 Send to multiple recipients instantly
const results = await sender.sendToMultiple(
  ['[email protected]', '[email protected]'],
  {
    subject: '🎉 Welcome to Our Platform!',
    html: '<h1>Hello there!</h1><p>Thanks for joining us!</p>'
  }
);

console.log(`✅ Sent ${results.filter(r => r.success).length} emails successfully!`);

That's it! Your emails are sent with automatic retry logic, rate limiting, and comprehensive logging. 🎉

🎨 Interactive Features Showcase

🧠 Smart Retry Logic

// Automatically retries failed emails with exponential backoff
const sender = new EmailSender({
  options: {
    maxRetries: 5,        // Try up to 5 times
    retryDelay: 1000,     // Start with 1 second delay
    enableLogging: true   // Track every attempt
  }
});

⚡ Adaptive Rate Limiting

// Automatically adjusts to your provider's limits
const sender = new EmailSender({
  rateLimit: {
    enabled: true,
    maxEmailsPerMinute: 10,  // Gmail-friendly
    maxEmailsPerHour: 100    // Respectful limits
  }
});

🎨 Dynamic Templates

// Create personalized emails with ease
const recipients = [
  { email: '[email protected]', name: 'John', company: 'Tech Corp' },
  { email: '[email protected]', name: 'Jane', company: 'Design Studio' }
];

const emailContent = {
  subject: 'Hello {{name}} from {{company}}!',
  html: `
    <h1>Welcome {{name}}!</h1>
    <p>We're excited to have you from <strong>{{company}}</strong> join our community.</p>
    <p>Best regards,<br>The Team</p>
  `,
  template: {
    name: 'welcome',
    variables: { name: '{{name}}', company: '{{company}}' }
  }
};

await sender.sendToMultiple(recipients, emailContent);

📊 Real-time Analytics

// Get comprehensive insights
const stats = sender.getStatistics();
console.log(`
📈 Email Analytics:
✅ Success Rate: ${((stats.totalSent / (stats.totalSent + stats.totalFailed)) * 100).toFixed(1)}%
📧 Total Sent: ${stats.totalSent}
⏱️  Avg Duration: ${Math.round(stats.averageDuration)}ms
🔄 Total Attempts: ${stats.totalAttempts}
`);

🛠️ Configuration Made Simple

📧 Email Provider Setup

const gmailSender = new EmailSender({
  email: {
    service: 'gmail',
    auth: {
      user: '[email protected]',
      pass: 'your-app-password' // Generate in Google Account settings
    }
  },
  options: {
    dailyLimit: 100,           // Gmail's recommended limit
    delayBetweenEmails: 2000,  // 2 seconds between emails
    maxRetries: 3
  },
  rateLimit: {
    maxEmailsPerMinute: 10,
    maxEmailsPerHour: 100
  }
});

💡 Pro Tip: Enable 2-factor authentication and use app passwords for better security!

const outlookSender = new EmailSender({
  email: {
    service: 'hotmail',
    auth: {
      user: '[email protected]',
      pass: 'your-password'
    }
  },
  options: {
    dailyLimit: 300,           // Outlook allows more
    delayBetweenEmails: 1000,  // Faster sending
    maxRetries: 3
  },
  rateLimit: {
    maxEmailsPerMinute: 20,
    maxEmailsPerHour: 200
  }
});

const customSender = new EmailSender({
  email: {
    service: 'custom',
    auth: {
      user: '[email protected]',
      pass: 'your-smtp-password'
    },
    host: 'smtp.yourdomain.com',
    port: 587,
    secure: false
  },
  options: {
    dailyLimit: 500,           // Check with your provider
    delayBetweenEmails: 500,   // Custom providers often allow faster sending
    maxRetries: 5
  },
  rateLimit: {
    maxEmailsPerMinute: 30,
    maxEmailsPerHour: 500
  }
});

🎯 Real-World Use Cases

🛒 E-commerce Order Confirmations

// Send personalized order confirmations
const orderEmails = orders.map(order => ({
  email: order.customerEmail,
  name: order.customerName,
  orderId: order.id,
  total: order.total,
  items: order.items
}));

const emailContent = {
  subject: '🎉 Order Confirmation #{{orderId}}',
  html: `
    <h1>Thank you {{name}}!</h1>
    <p>Your order #{{orderId}} has been confirmed.</p>
    <p><strong>Total: ${{total}}</strong></p>
    <p>We'll send you tracking information soon!</p>
  `,
  template: {
    name: 'order-confirmation',
    variables: { name: '{{name}}', orderId: '{{orderId}}', total: '{{total}}' }
  }
};

await sender.sendToMultiple(orderEmails, emailContent);

📧 Newsletter Campaigns

// Send newsletters with attachments
const newsletterContent = {
  subject: '📰 Weekly Newsletter - {{date}}',
  html: newsletterHTML,
  attachments: [
    { filename: 'newsletter.pdf', path: './newsletters/weekly.pdf' }
  ],
  template: {
    name: 'newsletter',
    variables: { date: new Date().toLocaleDateString() }
  }
};

// Process in batches for large lists
const batchSize = 50;
for (let i = 0; i < subscribers.length; i += batchSize) {
  const batch = subscribers.slice(i, i + batchSize);
  await sender.sendToMultiple(batch, newsletterContent);
  
  // Add delay between batches
  await new Promise(resolve => setTimeout(resolve, 5000));
}

🔔 Transactional Notifications

// Send system notifications
const notifications = [
  { email: '[email protected]', type: 'system', message: 'Server backup completed' },
  { email: '[email protected]', type: 'account', message: 'Password changed successfully' }
];

for (const notification of notifications) {
  const emailContent = {
    subject: `🔔 ${notification.type.charAt(0).toUpperCase() + notification.type.slice(1)} Notification`,
    text: notification.message,
    priority: 'high'
  };
  
  await sender.sendSingle(notification.email, emailContent);
}

📊 Advanced Features

🧠 Intelligent Error Handling

// Automatic error categorization and handling
const results = await sender.sendToMultiple(recipients, emailContent);

results.forEach(result => {
  if (!result.success) {
    switch (result.error) {
      case 'authentication':
        console.log('🔐 Auth issue - check credentials');
        break;
      case 'rate_limit':
        console.log('⏱️ Rate limited - will retry automatically');
        break;
      case 'network':
        console.log('🌐 Network issue - retrying with backoff');
        break;
      default:
        console.log('❌ Other error:', result.error);
    }
  }
});

📈 Performance Monitoring

// Get detailed performance insights
const stats = sender.getStatistics();
const logs = sender.getLogs();

console.log(`
📊 Performance Report:
┌─────────────────────────────────────┐
│ 📧 Emails Sent: ${stats.totalSent.toString().padEnd(20)} │
│ ❌ Failed: ${stats.totalFailed.toString().padEnd(23)} │
│ ⏱️  Avg Time: ${Math.round(stats.averageDuration).toString().padEnd(18)}ms │
│ 🔄 Total Attempts: ${stats.totalAttempts.toString().padEnd(15)} │
└─────────────────────────────────────┘

📈 Success Rate: ${((stats.totalSent / (stats.totalSent + stats.totalFailed)) * 100).toFixed(1)}%
🎯 Error Breakdown:`, stats.errorBreakdown);

🔄 Batch Processing with Progress

// Process large lists with progress tracking
const processLargeList = async (recipients, emailContent) => {
  const batchSize = 100;
  const totalBatches = Math.ceil(recipients.length / batchSize);
  
  for (let i = 0; i < recipients.length; i += batchSize) {
    const batchNumber = Math.floor(i / batchSize) + 1;
    const batch = recipients.slice(i, i + batchSize);
    
    console.log(`📦 Processing batch ${batchNumber}/${totalBatches} (${batch.length} recipients)...`);
    
    const results = await sender.sendToMultiple(batch, emailContent);
    const successful = results.filter(r => r.success).length;
    
    console.log(`✅ Batch ${batchNumber} completed: ${successful}/${batch.length} successful`);
    
    // Show progress bar
    const progress = Math.round((batchNumber / totalBatches) * 100);
    console.log(`📊 Progress: [${'█'.repeat(progress/5)}${'░'.repeat(20-progress/5)}] ${progress}%`);
    
    // Rate limiting delay
    if (batchNumber < totalBatches) {
      await new Promise(resolve => setTimeout(resolve, 2000));
    }
  }
};

🌍 Environment Variables (Production Ready)

# .env file
EMAIL_SERVICE=gmail
[email protected]
EMAIL_PASS=your-app-password
EMAIL_DAILY_LIMIT=100
EMAIL_DELAY=2000
EMAIL_MAX_RETRIES=3
EMAIL_RATE_LIMIT_ENABLED=true
EMAIL_MAX_PER_MINUTE=10
EMAIL_MAX_PER_HOUR=100

// Use environment variables
import { createConfigFromEnv } from '@prathammahajan/multi-email-sender';

const config = createConfigFromEnv();
const sender = new EmailSender(config);

🏆 Best Practices & Tips

💡 Pro Tips for Success

• ✅ Use App Passwords for Gmail/Yahoo (never regular passwords)
• ✅ Enable 2FA on your email accounts
• ✅ Store credentials in environment variables
• ✅ Use dedicated email accounts for sending
• ✅ Monitor your sending reputation regularly

• 🚀 Batch processing for large lists (50-100 emails per batch)
• 🚀 Use appropriate delays based on your provider
• 🚀 Monitor rate limits and adjust accordingly
• 🚀 Enable logging for debugging and optimization
• 🚀 Use templates for consistent formatting

• 📈 Track success rates and identify patterns
• 📈 Monitor error types to improve reliability
• 📈 Set up alerts for high failure rates
• 📈 Regular log analysis for optimization
• 📈 A/B test different sending strategies

🔧 Troubleshooting Guide

❓ Common Issues & Solutions

Problem: Authentication failed or Invalid credentials

Solutions:

1. ✅ Verify email and password are correct
2. ✅ For Gmail: Use app passwords instead of regular passwords
3. ✅ Enable 2-factor authentication
4. ✅ Check if account is locked or suspended
5. ✅ Verify SMTP settings for custom providers

// Test your configuration
const isValid = sender.validateConfiguration();
console.log('Configuration valid:', isValid);

Problem: Emails being delayed or blocked

Solutions:

1. ✅ Reduce maxEmailsPerMinute setting
2. ✅ Increase delayBetweenEmails
3. ✅ Use multiple email accounts for rotation
4. ✅ Check your provider's specific limits
5. ✅ Monitor rate limit statistics

// Check current rate limit status
const status = sender.rateLimiter.getStatus();
console.log('Rate limit status:', status);

Problem: Timeouts or connection failures

Solutions:

1. ✅ Increase timeout setting
2. ✅ Check internet connection stability
3. ✅ Verify SMTP server settings
4. ✅ Try different ports (587 vs 465)
5. ✅ Check firewall settings

// Increase timeout for slow networks
const sender = new EmailSender({
  email: { /* config */ },
  options: {
    timeout: 60000, // 60 seconds
    maxRetries: 5
  }
});

📚 API Reference

🎯 Core Classes

| Class | Description | Key Methods | |-------|-------------|-------------| | EmailSender | Main email sending class | sendToMultiple(), sendSingle(), getStatistics() | | Logger | Comprehensive logging system | info(), error(), getLogs(), getStatistics() | | RetryLogic | Intelligent retry mechanism | executeWithRetry(), getRetryStatistics() | | RateLimiter | Smart rate limiting | waitIfNeeded(), getStatus(), updateConfig() |

🔧 Configuration Options

{
  email: {
    service: 'gmail',           // 'gmail', 'outlook', 'yahoo', 'custom'
    auth: {
      user: '[email protected]',
      pass: 'password'
    },
    host: 'smtp.domain.com',    // For custom SMTP
    port: 587,                  // For custom SMTP
    secure: false               // For custom SMTP
  },
  options: {
    dailyLimit: 100,            // Max emails per day
    delayBetweenEmails: 2000,   // Delay in milliseconds
    maxRetries: 3,              // Max retry attempts
    retryDelay: 1000,           // Base retry delay
    timeout: 30000,             // Send timeout
    enableLogging: true,        // Enable detailed logging
    logFile: 'email-logs.json'  // Log file path
  },
  rateLimit: {
    enabled: true,              // Enable rate limiting
    maxEmailsPerMinute: 10,     // Max emails per minute
    maxEmailsPerHour: 100       // Max emails per hour
  }
}

🤝 Contributing & Support

🚀 Get Involved

We love contributions! Here's how you can help:

1. 🐛 Report bugs - Found an issue? Let us know!
2. 💡 Suggest features - Have ideas? We'd love to hear them!
3. 🔧 Submit PRs - Fix bugs or add features
4. 📖 Improve docs - Help others learn
5. ⭐ Star the repo - Show your support!

📞 Support Channels

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: GitHub Wiki
• ☕ Buy me a coffee: Support the project

📄 License & Legal

This project is licensed under the MIT License - see the LICENSE file for details.

Made with ❤️ by Pratham Mahajan

🎯 Perfect For

| 🛒 E-commerce | 📧 Marketing | 🔔 Notifications | 📊 Analytics | |-------------------|------------------|---------------------|------------------| | Order confirmations | Newsletter campaigns | System alerts | Performance tracking | | Shipping updates | Promotional emails | User notifications | Delivery insights | | Customer support | Welcome sequences | Password resets | Error monitoring |

🚀 Ready to Transform Your Email Operations?

Start sending emails like a pro in 30 seconds! ⚡