@454creative/easy-email

A framework-agnostic email service library for Node.js with observability and monitoring capabilities. Supports SMTP, SendGrid, and AWS SES providers with comprehensive error handling, performance monitoring, and template rendering.

🚀 Features

• Framework Agnostic: Works with any Node.js framework (Express, NestJS, Fastify, etc.)
• Multiple Providers: Support for SMTP, SendGrid, and AWS SES
• Observability: Built-in monitoring, logging, and metrics
• Type Safety: Full TypeScript support with comprehensive type definitions
• Error Handling: Robust error handling with detailed error information
• Performance Monitoring: Track email sending performance and identify bottlenecks
• Template Engine: HTML template rendering with variable substitution
• Validation: Email address validation and request validation
• Retry Logic: Automatic retry with exponential backoff
• Rate Limiting: Built-in rate limiting support
• AWS SES Integration: Full AWS SES support with advanced features
• Dependency Injection: No singletons - perfect for multi-tenant applications
• Multi-Tenant Support: Each service instance is completely isolated

📦 Installation

npm install @454creative/easy-email

🔧 Quick Start

Basic Usage

import { EmailService, EmailProviderType } from '@454creative/easy-email';

// Configure with SMTP
const emailService = new EmailService({
  type: EmailProviderType.SMTP,
  config: {
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    auth: {
      user: '[email protected]',
      pass: 'your-password'
    }
  }
});

// Or configure with SendGrid
const sendGridService = new EmailService({
  type: EmailProviderType.SENDGRID,
  config: {
    apiKey: 'your-sendgrid-api-key'
  }
});

// Send email
const result = await emailService.sendEmail({
  to: '[email protected]',
  subject: 'Hello from Easy Email!',
  text: 'This is a test email',
  from: '[email protected]'
});

if (result.success) {
  console.log('Email sent successfully!');
} else {
  console.error('Failed to send email:', result.error);
}

SendGrid Configuration

import { EmailService, EmailProviderType } from '@454creative/easy-email';

const emailService = new EmailService({
  type: EmailProviderType.SENDGRID,
  config: {
    apiKey: 'your-sendgrid-api-key'
  }
});

AWS SES Configuration

import { EmailService, EmailProviderType, EmailConfigBuilder } from '@454creative/easy-email';

// Method 1: Using EmailConfigBuilder (Recommended)
const config = new EmailConfigBuilder(EmailProviderType.SES)
  .withSesConfig({
    region: 'us-west-2',
    // Credentials will be loaded from environment variables:
    // AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
  })
  .withRetryAttempts(3)
  .withTimeout(10000)
  .build();

const emailService = new EmailService(config, { email: '[email protected]' });

Dependency Injection & Multi-Tenant Support

The library supports proper dependency injection with no singletons, making it perfect for multi-tenant applications:

import { EmailService, EmailProviderType, ObservabilityService } from '@454creative/easy-email';

// Create tenant-specific observability services
const tenant1Observability = new ObservabilityService({ 
  enabled: true, 
  tenantId: 'tenant-1',
  scope: 'tenant' 
});

const tenant2Observability = new ObservabilityService({ 
  enabled: true, 
  tenantId: 'tenant-2',
  scope: 'tenant' 
});

// Create isolated email services for each tenant
const tenant1Service = new EmailService(
  {
    type: EmailProviderType.SMTP,
    config: { host: 'smtp.tenant1.com', port: 587, secure: false }
  },
  { email: '[email protected]' },
  tenant1Observability // Inject tenant-specific observability
);

const tenant2Service = new EmailService(
  {
    type: EmailProviderType.SENDGRID,
    config: { apiKey: 'tenant2-api-key' }
  },
  { email: '[email protected]' },
  tenant2Observability // Inject tenant-specific observability
);

// Each tenant's metrics and events are completely isolated
await tenant1Service.sendEmail({ to: '[email protected]', subject: 'Hello Tenant 1' });
await tenant2Service.sendEmail({ to: '[email protected]', subject: 'Hello Tenant 2' });

// Get isolated metrics for each tenant
const tenant1Metrics = tenant1Observability.getMetrics();
const tenant2Metrics = tenant2Observability.getMetrics();

Using Factory Methods

For convenience, you can also use factory methods:

import { ProviderFactory } from '@454creative/easy-email';

// Create services with factory methods
const emailService = ProviderFactory.createEmailService(
  { type: EmailProviderType.SMTP, config: smtpConfig },
  { email: '[email protected]' },
  ProviderFactory.createObservabilityService({ enabled: true, scope: 'production' })
);

📚 API Reference

Available Exports

import {
  // Main services
  EmailService,
  ObservabilityService,
  SesService,
  
  // Enums and constants
  EmailProviderType,
  EMAIL_CONSTANTS,
  OBSERVABILITY_CONSTANTS,
  
  // Performance utilities
  PerformanceMonitor,
  trackPerformance,
  
  // Version information
  VERSION,
  LIBRARY_INFO,
  
  // Error classes
  EmailServiceError,
  ConfigurationError,
  ProviderError,
  ValidationError,
  
  // Utility functions
  validateEmail,
  isValidEmail,
  checkEmailTypos
} from '@454creative/easy-email';

EmailService

The main service class for sending emails.

Constructor

new EmailService(
  providerConfig: EmailProviderConfig | SmtpConfig,
  defaultFrom?: { email: string; name?: string },
  observabilityConfig?: ObservabilityConfig
)

Methods

• sendEmail(request: EmailRequest): Promise<EmailResponse> - Send an email
• verifyConnection(): Promise<boolean> - Verify provider connection
• sendPlainText(to, subject, text, options?): Promise<EmailResponse> - Send plain text email
• sendHtml(to, subject, html, options?): Promise<EmailResponse> - Send HTML email

Interfaces

EmailRequest

interface EmailRequest {
  to: string | string[];
  subject: string;
  text?: string;
  html?: string;
  from?: string;
  cc?: string | string[];
  bcc?: string | string[];
  replyTo?: string;
  attachments?: EmailRequestAttachment[];
  headers?: Record<string, string>;
}

EmailProviderType

enum EmailProviderType {
  SMTP = 'smtp',
  SENDGRID = 'sendgrid',
  SES = 'ses'
}

EmailResponse

interface EmailResponse {
  success: boolean;
  messageId?: string;
  error?: {
    message: string;
    code?: string;
    provider?: string;
    details?: any;
  };
}

🔍 Observability

The library includes built-in observability features:

import { ObservabilityService } from '@454creative/easy-email';

const observability = ObservabilityService.getInstance({
  enabled: true,
  logLevel: 'info',
  trackMetrics: true
});

// Get metrics
const metrics = observability.getMetrics();
console.log('Email metrics:', metrics);

🎯 Performance Monitoring

Track performance with the built-in performance monitor:

import { PerformanceMonitor } from '@454creative/easy-email';

const monitor = PerformanceMonitor.getInstance({
  enabled: true,
  thresholdMs: 1000,
  logSlowOperations: true
});

// Get performance summary
const summary = monitor.getSummary();
console.log('Performance summary:', summary);

🛠️ Error Handling

The library provides comprehensive error handling:

import { 
  EmailServiceError, 
  ValidationError, 
  ProviderError 
} from '@454creative/easy-email';

try {
  const result = await emailService.sendEmail(request);
  // Handle success
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof ProviderError) {
    console.error('Provider error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

📝 Examples

See the examples/ directory for comprehensive examples:

• Simple Best Practice
• SendGrid Example
• AWS SES Example
• Observability Example
• Event-Driven Example
• SendGrid Debugging

For detailed documentation and guides, see the Documentation Directory.

📚 Documentation

AWS SES Integration

• AWS SES Setup Guide - Complete setup instructions
• AWS SES Examples - Comprehensive usage examples
• AWS SES Troubleshooting - Common issues and solutions

General Documentation

• Getting Started - Quick start guide
• API Reference - Complete API documentation
• Best Practices - Development guidelines
• Troubleshooting - Common issues and solutions

🧪 Testing

# Run all tests
npm test

# Run unit tests
npm run test:unit

# Run integration tests
npm run test:integration

# Run with coverage
npm run test:coverage

📊 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 ISC License - see the LICENSE file for details.

🤝 Support

• Issues: GitHub Issues
• Documentation: Documentation Directory
• API Reference: Generated API Docs
• Examples: Examples Directory

🔄 Changelog

See CHANGELOG.md for a complete list of changes, version history, and migration guides.

📈 Roadmap

• [x] AWS SES integration ✅
• [ ] Additional email providers (Mailgun)
• [ ] Advanced template engine with layouts
• [ ] Email scheduling and queuing
• [ ] Webhook support for delivery tracking
• [ ] Advanced rate limiting strategies
• [ ] Email analytics and reporting

Made with ❤️ by 454 Creative