🚀 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: 'your-email@gmail.com',
      pass: 'your-app-password' // Use app password for Gmail
    }
  }
});

// 📧 Send to multiple recipients instantly
const results = await sender.sendToMultiple(
  ['user1@example.com', 'user2@example.com'],
  {
    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: 'john@example.com', name: 'John', company: 'Tech Corp' },
  { email: 'jane@example.com', 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

🔵 Gmail Configuration (Click to expand)

const gmailSender = new EmailSender({
  email: {
    service: 'gmail',
    auth: {
      user: 'your-email@gmail.com',
      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!

🟠 Outlook Configuration (Click to expand)

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

🟢 Custom SMTP Configuration (Click to expand)

const customSender = new EmailSender({
  email: {
    service: 'custom',
    auth: {
      user: 'your-email@yourdomain.com',
      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: 'admin@company.com', type: 'system', message: 'Server backup completed' },
  { email: 'user@example.com', 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_USER=your-email@gmail.com
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

🔐 Security Best Practices

• ✅ 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

⚡ Performance Optimization

• 🚀 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

📊 Monitoring & Analytics

• 📈 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

🔐 Authentication Errors

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);

⏱️ Rate Limiting Issues

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);

🌐 Network & Connection Issues

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

EmailSender Options

{
  email: {
    service: 'gmail',           // 'gmail', 'outlook', 'yahoo', 'custom'
    auth: {
      user: 'email@domain.com',
      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! ⚡