npm package: @nixxie-international/email-service
Description: A robust, modern, and comprehensive email service for Node.js with TypeScript support, advanced validation, tracking, analytics, A/B testing, and suppression lists
Author: Sher Ghan
Latest version: 2.0.2

# @nixxie-international/email-service

A **robust, modern, and comprehensive email service** for Node.js applications built with TypeScript. Features advanced email templating, tracking, analytics, A/B testing, and suppression lists.

[![npm version](https://badge.fury.io/js/@nixxie-international/email-service.svg)](https://www.npmjs.com/package/@nixxie-international/email-service)
[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/ellerbrock/typescript-badges/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 📧 **Email sending** with Pug template engine
- 🔍 **Advanced email validation** with comprehensive error handling
- 📊 **Email tracking and analytics** with detailed metrics
- 🔄 **Retry mechanism** with exponential backoff and jitter
- 📦 **Bulk email sending** with intelligent batching
- ⏰ **Email scheduling** for future delivery
- 🎯 **Template helpers** for common formatting needs
- 🚫 **Suppression lists** (permanent and temporary)
- 🧪 **A/B testing** with statistical distribution
- 💥 **Bounce handling** and delivery notifications
- 📈 **Email analytics** and comprehensive reporting
- 🛡️ **Type-safe** with full TypeScript support
- 🏗️ **Modern architecture** with dependency injection
- ⚡ **High performance** with connection pooling and rate limiting

## 🚀 Installation

```bash
npm install @nixxie-international/email-service
```

## 📋 Requirements

- Node.js >= 16.0.0
- TypeScript >= 4.5.0 (for TypeScript projects)

## 🎯 Quick Start

```typescript
import { createEmailService } from '@nixxie-international/email-service';

const emailService = createEmailService({
  smtp: {
    host: 'smtp.gmail.com',
    port: 587,
    user: 'your-email@gmail.com',
    password: 'your-app-password'
  },
  defaults: {
    companyName: 'Your Company',
    emailFrom: 'noreply@yourcompany.com'
  },
  templateDir: './email-templates'
});

// Initialize the service
await emailService.initialize();

// Send an email
const result = await emailService.sendEmail({
  to: 'user@example.com',
  subject: 'Welcome to our platform!',
  templateName: 'welcome',
  data: {
    userName: 'John Doe',
    loginUrl: 'https://yourapp.com/login'
  },
  tracking: true
});

console.log(`Email sent: ${result.messageId}`);
```

## ⚙️ Configuration

### Basic Configuration

```typescript
interface EmailServiceConfig {
  smtp: {
    host: string;
    port: number;
    secure?: boolean;           // Use TLS (default: false)
    user: string;
    password: string;
    maxConnections?: number;    // Max concurrent connections (default: 5)
    rateDelta?: number;         // Rate limiting time window (default: 20000ms)
    rateLimit?: number;         // Max emails per time window (default: 5)
  };
  defaults: {
    companyName: string;
    emailFrom: string;
    domain?: string;            // For message ID generation
  };
  templateDir?: string;         // Path to Pug templates (default: './email-templates')
  apiUrl?: string;             // For tracking URLs
  logger?: Logger;             // Custom logger (default: console)
  retryConfig?: Partial<RetryConfig>;
}
```

### Advanced Configuration

```typescript
const emailService = createAdvancedEmailService({
  smtp: {
    host: 'smtp.sendgrid.net',
    port: 587,
    user: 'apikey',
    password: 'your-sendgrid-api-key',
    maxConnections: 10,
    rateLimit: 50,
    rateDelta: 60000  // 1 minute
  },
  defaults: {
    companyName: 'Acme Corp',
    emailFrom: 'noreply@acme.com',
    domain: 'acme.com'
  },
  templateDir: './src/email-templates',
  retryConfig: {
    maxRetries: 5,
    baseDelay: 2000,
    maxDelay: 60000,
    factor: 2
  }
});
```

## 📧 Sending Emails

### Single Email

```typescript
await emailService.sendEmail({
  to: 'user@example.com',
  subject: 'Welcome!',
  templateName: 'welcome',
  data: { name: 'John', code: '12345' },
  cc: ['manager@example.com'],
  bcc: ['audit@example.com'],
  priority: 'high',
  tracking: true,
  metadata: { userId: '123', campaignId: 'welcome-series' }
});
```

### Bulk Email Sending

```typescript
await emailService.sendBulkEmails({
  recipients: [
    { to: 'user1@example.com', data: { name: 'User 1' } },
    { to: 'user2@example.com', data: { name: 'User 2' } },
    // ... more recipients
  ],
  subject: 'Monthly Newsletter',
  templateName: 'newsletter',
  batchSize: 100,               // Send in batches of 100
  delayBetweenBatches: 5000,    // 5 second delay between batches
  tracking: true
});
```

### Scheduled Emails

```typescript
const scheduleId = await emailService.scheduleEmail({
  to: 'user@example.com',
  subject: 'Reminder: Meeting tomorrow',
  templateName: 'reminder',
  data: { meetingTime: '2024-01-15 10:00 AM' },
  sendAt: new Date('2024-01-14T18:00:00Z'),
  tracking: true
});

console.log(`Email scheduled with ID: ${scheduleId}`);
```

## 🎨 Template System

### Template Helpers

Built-in helpers available in all Pug templates:

```pug
// welcome.pug
html
  body
    h1 Welcome #{userName}!
    p Your account was created on #{formatDate(createdAt, 'MMMM DD, YYYY')}
    p Current balance: #{formatCurrency(balance, 'USD')}
    p= truncate(description, 150)
    div!= linkify(userBio)

    ul
      each item in items
        li= item.name
```

Available template helpers:

- **formatDate(date, format)** - Format dates using Intl.DateTimeFormat
- **formatDateTime(date, format)** - Format date and time
- **formatCurrency(amount, currency)** - Format currency values
- **truncate(text, length)** - Truncate text with ellipsis
- **linkify(text)** - Convert URLs to clickable links
- **escapeHtml(html)** - Escape HTML characters for security
- **generateList(items, property)** - Generate HTML lists

### Custom Template Directory

```typescript
const emailService = createEmailService({
  // ... other config
  templateDir: path.join(__dirname, 'custom-templates')
});
```

## 🚫 Suppression Lists (Advanced)

Prevent emails from being sent to specific addresses:

```typescript
const advancedService = createAdvancedEmailService(config);

// Add permanent suppression
advancedService.addToSuppressionList('blocked@example.com', true);

// Add temporary suppression (24 hours)
advancedService.addToSuppressionList('temp-block@example.com', false);

// Check if email is suppressed
const isSuppressed = advancedService.isEmailSuppressed('user@example.com');

// Remove from suppression list
advancedService.removeFromSuppressionList('user@example.com');
```

## 🧪 A/B Testing

Test different email subjects or content:

```typescript
const results = await advancedService.sendABTestEmail({
  recipients: ['user1@example.com', 'user2@example.com', 'user3@example.com'],
  subjectA: 'Special Offer Inside!',
  subjectB: '50% Off Everything Today',
  templateName: 'promotion',
  data: { discount: 50 },
  splitRatio: 0.5,  // 50/50 split
  testName: 'subject-line-test-q1-2024'
});

console.log(`Test ID: ${results.testId}`);
console.log(`Group A sent to ${results.groupA.length} recipients`);
console.log(`Group B sent to ${results.groupB.length} recipients`);
```

## 📊 Analytics & Tracking

### Get Email Analytics

```typescript
const analytics = emailService.getEmailAnalytics({
  templateName: 'welcome',
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31')
});

console.log(analytics);
/*
{
  sent: 1000,
  delivered: 980,
  opened: 450,
  clicked: 120,
  bounced: 20,
  failed: 0,
  openRate: 45.9,    // percentage
  clickRate: 12.2,   // percentage
  bounceRate: 2.0    // percentage
}
*/
```

### Track Email Status Updates

```typescript
// Update email status when webhooks are received
emailService.updateTrackingStatus(trackingId, 'opened');
emailService.updateTrackingStatus(trackingId, 'clicked');
emailService.updateTrackingStatus(trackingId, 'bounced');

// Get tracking data for specific email
const trackingData = emailService.getTrackingData(trackingId);
```

### Handle Bounce Notifications

```typescript
emailService.processBounceNotification({
  messageId: 'original-message-id',
  email: 'bounced@example.com',
  reason: 'Mailbox full',
  bounceType: 'soft'  // 'soft', 'hard', or 'complaint'
});
```

## 🛡️ Error Handling

The service provides comprehensive error types for better error handling:

```typescript
import {
  EmailValidationError,
  EmailTemplateError,
  EmailTransportError,
  EmailSuppressionError
} from '@nixxie-international/email-service';

try {
  await emailService.sendEmail(invalidOptions);
} catch (error) {
  if (error instanceof EmailValidationError) {
    console.log('Validation failed:', error.message);
    console.log('Error details:', error.details);
  } else if (error instanceof EmailTemplateError) {
    console.log('Template error:', error.message);
  } else if (error instanceof EmailTransportError) {
    console.log('SMTP transport error:', error.message);
  } else if (error instanceof EmailSuppressionError) {
    console.log('Email suppressed:', error.message);
  }
}
```

## 🔍 Email Validation

Robust email validation with comprehensive checks:

```typescript
import { EmailValidator } from '@nixxie-international/email-service';

// Validate single email
const isValid = EmailValidator.validateEmail('user@example.com');

// Validate multiple emails
const { valid, invalid } = EmailValidator.validateEmails([
  'good@example.com',
  'bad-email',
  'another@domain.com'
]);

// Throw error for invalid emails
EmailValidator.requireValidEmail('user@example.com'); // throws if invalid

// Normalize email
const normalized = EmailValidator.normalizeEmail(' USER@EXAMPLE.COM ');
// Returns: 'user@example.com'

// Check for disposable email services
const isDisposable = EmailValidator.isDisposableEmail('user@10minutemail.com');

// Extract domain
const domain = EmailValidator.extractDomain('user@example.com'); // 'example.com'
```

## 🧪 Testing

Run the test suite:

```bash
npm test                    # Run all tests
npm run test:watch         # Run tests in watch mode
npm run test:coverage      # Run tests with coverage report
```

Test specific functionality:

```bash
npm test -- --testNamePattern="validation"
npm test -- src/__tests__/email-service.test.ts
```

## 🏗️ Development

```bash
# Clone the repository
git clone https://github.com/sherghan7/email-service.git
cd email-service

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build the project
npm run build

# Run linting
npm run lint
npm run lint:fix
```

## 📚 API Reference

### EmailService Methods

| Method | Description |
|--------|-------------|
| `initialize()` | Initialize SMTP connection |
| `sendEmail(options)` | Send single email |
| `sendBulkEmails(options)` | Send bulk emails |
| `scheduleEmail(options)` | Schedule email for future delivery |
| `renderTemplate(name, data)` | Render Pug template |
| `validateEmailAddress(email)` | Validate email address |
| `getEmailAnalytics(filters)` | Get email analytics |
| `updateTrackingStatus(id, status)` | Update tracking status |
| `processBounceNotification(data)` | Handle bounce notifications |

### AdvancedEmailService Additional Methods

| Method | Description |
|--------|-------------|
| `addToSuppressionList(email, permanent)` | Add email to suppression list |
| `removeFromSuppressionList(email)` | Remove email from suppression list |
| `isEmailSuppressed(email)` | Check if email is suppressed |
| `sendABTestEmail(options)` | Send A/B test emails |

## 🔧 Configuration Examples

### Gmail SMTP
```typescript
{
  smtp: {
    host: 'smtp.gmail.com',
    port: 587,
    user: 'your-email@gmail.com',
    password: 'your-app-password'  // Use app password, not regular password
  }
}
```

### SendGrid SMTP
```typescript
{
  smtp: {
    host: 'smtp.sendgrid.net',
    port: 587,
    user: 'apikey',
    password: 'your-sendgrid-api-key'
  }
}
```

### AWS SES SMTP
```typescript
{
  smtp: {
    host: 'email-smtp.us-east-1.amazonaws.com',
    port: 587,
    user: 'your-access-key-id',
    password: 'your-secret-access-key'
  }
}
```

## 🔒 Security Considerations

- Never commit SMTP credentials to version control
- Use environment variables for sensitive configuration
- Validate all email addresses before sending
- Implement rate limiting to prevent abuse
- Use suppression lists to respect user preferences
- Sanitize template data to prevent XSS attacks

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 👨‍💻 Author

**Sher Ghan**
- GitHub: [@sherghan7](https://github.com/sherghan7)
- Email: sher@nixxieinternational.com

## 🆘 Support

If you have any questions or need help:

1. Check the [GitHub Issues](https://github.com/sherghan7/email-service/issues)
2. Create a new issue if your problem isn't already listed
3. For urgent support, contact: sher@nixxieinternational.com

## 🎯 Roadmap

- [ ] Webhook endpoints for email events
- [ ] Email templates marketplace
- [ ] Visual template editor
- [ ] Advanced analytics dashboard
- [ ] Integration with popular email marketing platforms
- [ ] Support for other template engines (Handlebars, Mustache)
- [ ] Queue-based email processing
- [ ] Multi-tenant support

---

Made with ❤️ by [Sher Ghan at Nixxie International](https://nixxieinternational.com)