Package Exports
- @prathammahajan/multi-email-sender
- @prathammahajan/multi-email-sender/src/index.js
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@prathammahajan/multi-email-sender) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
🚀 Multi Email Sender
🎯 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-senderimport { 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:
- ✅ Verify email and password are correct
- ✅ For Gmail: Use app passwords instead of regular passwords
- ✅ Enable 2-factor authentication
- ✅ Check if account is locked or suspended
- ✅ 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:
- ✅ Reduce
maxEmailsPerMinutesetting - ✅ Increase
delayBetweenEmails - ✅ Use multiple email accounts for rotation
- ✅ Check your provider's specific limits
- ✅ 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:
- ✅ Increase
timeoutsetting - ✅ Check internet connection stability
- ✅ Verify SMTP server settings
- ✅ Try different ports (587 vs 465)
- ✅ 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:
- 🐛 Report bugs - Found an issue? Let us know!
- 💡 Suggest features - Have ideas? We'd love to hear them!
- 🔧 Submit PRs - Fix bugs or add features
- 📖 Improve docs - Help others learn
- ⭐ 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 |