@flusys/nestjs-email 4.0.1 → 4.1.0

package/README.md

@@ -1,97 +1,94 @@
-# Email Package Guide
+# @flusys/nestjs-email
 
-> **Package:** `@flusys/nestjs-email`
-> **Version:** 4.0.1
-> **Type:** Email sending with templates, multiple providers, and multi-tenant support
+> Production-grade email management for NestJS — multi-provider (SMTP, SendGrid, Mailgun), database-driven template engine with `{{variable}}` interpolation, company scoping, and multi-tenant support.
+
+[![npm version](https://img.shields.io/npm/v/@flusys/nestjs-email.svg)](https://www.npmjs.com/package/@flusys/nestjs-email)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![NestJS](https://img.shields.io/badge/NestJS-11.x-red.svg)](https://nestjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.x-green.svg)](https://nodejs.org/)
+
+---
 
 ## Table of Contents
 
 - [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
 - [Installation](#installation)
-- [Constants](#constants)
-- [Module Setup](#module-setup)
+- [Quick Start](#quick-start)
+- [Module Registration](#module-registration)
+  - [forRoot (Sync)](#forroot-sync)
+  - [forRootAsync (Factory)](#forrootasync-factory)
+  - [forRootAsync (Class)](#forrootasync-class)
+- [Configuration Reference](#configuration-reference)
+- [Feature Toggles](#feature-toggles)
+- [API Endpoints](#api-endpoints)
 - [Entities](#entities)
-- [Interfaces](#interfaces)
 - [Email Providers](#email-providers)
-- [Email Configuration](#email-configuration)
-- [Email Templates](#email-templates)
-- [Email Sending](#email-sending)
-- [DTOs](#dtos)
-- [Utility Functions](#utility-functions)
-- [API Endpoints](#api-endpoints)
-- [Swagger Documentation](#swagger-documentation)
-- [Multi-Tenant Support](#multi-tenant-support)
-- [Best Practices](#best-practices)
+  - [SMTP (Default)](#smtp-default)
+  - [SendGrid](#sendgrid)
+  - [Mailgun](#mailgun)
+  - [Custom Provider](#custom-provider)
+- [Template Engine](#template-engine)
+- [Exported Services](#exported-services)
+- [Sending Emails Programmatically](#sending-emails-programmatically)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
 ## Overview
 
-`@flusys/nestjs-email` provides:
+`@flusys/nestjs-email` provides a complete email management system. Email provider configurations and templates are stored in the database — no code changes are needed to add new email templates or switch providers. Providers are loaded dynamically, so you only install the SDK for the providers you use.
 
-- **Multiple Providers** - SMTP, SendGrid, Mailgun with dynamic registration
-- **Email Templates** - Variable interpolation with `{{variableName}}` syntax
-- **HTML/Plain Text** - Support via `isHtml` toggle
-- **Multi-Tenant Support** - Company-scoped configurations and templates
-- **Attachments** - File attachment support
+---
 
-### Package Hierarchy
+## Features
 
-```
-@flusys/nestjs-core     ← Foundation
-     ↓
-@flusys/nestjs-shared   ← Shared utilities
-     ↓
-@flusys/nestjs-email    ← Email system (THIS PACKAGE)
-```
+- **Multi-provider** — SMTP (nodemailer), SendGrid, Mailgun with a pluggable custom provider interface
+- **Database-driven templates** — Templates stored in PostgreSQL with `{{variable}}` interpolation
+- **HTML XSS protection** — All variable values are HTML-escaped before interpolation
+- **Provider caching** — SHA-256 config hash prevents duplicate provider instances
+- **Test email** — Verify a provider configuration before using it in production
+- **Company scoping** — Optional `companyId` on configs and templates for multi-company setups
+- **Multi-tenant** — Per-tenant DataSource isolation via the DataSource Provider pattern
+- **Attachments** — Base64-encoded file attachments supported
 
 ---
 
-## Installation
-
-```bash
-npm install @flusys/nestjs-email
+## Compatibility
 
-# Provider-specific packages (install as needed)
-npm install nodemailer                  # For SMTP
-npm install @sendgrid/mail              # For SendGrid
-npm install mailgun.js form-data        # For Mailgun
-```
+| Package | Version |
+|---------|---------|
+| `@flusys/nestjs-core` | `^4.0.0` |
+| `@flusys/nestjs-shared` | `^4.0.0` |
+| `nodemailer` | `^6.0.0` |
+| `@sendgrid/mail` | `^8.0.0` *(optional)* |
+| `mailgun.js` | `^10.0.0` *(optional)* |
+| Node.js | `>= 18.x` |
 
 ---
 
-## Constants
+## Installation
 
-```typescript
-// Injection Token
-export const EMAIL_MODULE_OPTIONS = 'EMAIL_MODULE_OPTIONS';
+```bash
+npm install @flusys/nestjs-email @flusys/nestjs-shared @flusys/nestjs-core
 
-// Default Configuration
-export const DEFAULT_FROM_NAME = 'FLUSYS';
+# Provider-specific SDKs (install only what you use)
+npm install nodemailer                   # SMTP (recommended default)
+npm install @sendgrid/mail               # SendGrid
+npm install mailgun.js form-data         # Mailgun
 ```
 
 ---
 
-## Module Setup
-
-### Module Options Interface
+## Quick Start
 
-```typescript
-interface IEmailModuleConfig extends IDataSourceServiceOptions {
-  defaultProvider?: string;       // Default provider type
-  rateLimitPerMinute?: number;    // Rate limiting
-  enableLogging?: boolean;        // Enable debug logging
-}
-
-interface EmailModuleOptions extends IDynamicModuleConfig {
-  bootstrapAppConfig?: IBootstrapAppConfig;
-  config?: IEmailModuleConfig;
-}
-```
-
-### Basic Setup
+### Minimal Setup (SMTP, Single Database)
 
 ```typescript
+import { Module } from '@nestjs/common';
 import { EmailModule } from '@flusys/nestjs-email';
 
 @Module({
@@ -106,11 +103,11 @@ import { EmailModule } from '@flusys/nestjs-email';
       config: {
         defaultDatabaseConfig: {
           type: 'postgres',
-          host: 'localhost',
-          port: 5432,
-          username: 'user',
-          password: 'password',
-          database: 'myapp',
+          host: process.env.DB_HOST,
+          port: Number(process.env.DB_PORT ?? 5432),
+          username: process.env.DB_USER,
+          password: process.env.DB_PASSWORD,
+          database: process.env.DB_NAME,
         },
       },
     }),
@@ -119,25 +116,36 @@ import { EmailModule } from '@flusys/nestjs-email';
 export class AppModule {}
 ```
 
-### With Company Feature
+After startup, create an email config via the API and then send emails using `EmailSendService`.
+
+---
+
+## Module Registration
+
+### forRoot (Sync)
 
 ```typescript
 EmailModule.forRoot({
   global: true,
   includeController: true,
   bootstrapAppConfig: {
-    databaseMode: 'single',
-    enableCompanyFeature: true,
+    databaseMode: 'single',          // 'single' | 'multi-tenant'
+    enableCompanyFeature: false,     // true = company-scoped templates & configs
   },
   config: {
-    defaultDatabaseConfig: { ... },
+    defaultDatabaseConfig: { /* TypeORM DataSourceOptions */ },
+    defaultProvider: 'smtp',         // Optional: default provider type
+    rateLimitPerMinute: 100,         // Optional: rate limit on send endpoint
+    enableLogging: false,            // Optional: debug logging
   },
-});
+})
 ```
 
-### Async Configuration
+### forRootAsync (Factory)
 
 ```typescript
+import { ConfigService } from '@nestjs/config';
+
 EmailModule.forRootAsync({
   global: true,
   includeController: true,
@@ -146,882 +154,346 @@ EmailModule.forRootAsync({
     enableCompanyFeature: true,
   },
   imports: [ConfigModule],
-  useFactory: async (configService: ConfigService) => ({
-    defaultDatabaseConfig: configService.getDatabaseConfig(),
+  useFactory: (configService: ConfigService) => ({
+    defaultDatabaseConfig: {
+      type: 'postgres',
+      host: configService.get('DB_HOST'),
+      port: configService.get<number>('DB_PORT'),
+      username: configService.get('DB_USER'),
+      password: configService.get('DB_PASSWORD'),
+      database: configService.get('DB_NAME'),
+    },
   }),
   inject: [ConfigService],
-});
+})
 ```
 
----
-
-## Entities
-
-### Entity Groups
+### forRootAsync (Class)
 
 ```typescript
-// Core entities (no company feature)
-export const EmailCoreEntities = [EmailConfig, EmailTemplate];
-
-// Company-specific entities
-export const EmailCompanyEntities = [EmailConfigWithCompany, EmailTemplateWithCompany];
+import { EmailOptionsFactory, IEmailModuleConfig } from '@flusys/nestjs-email';
 
-// Helper function
-export function getEmailEntitiesByConfig(enableCompanyFeature: boolean): any[] {
-  return enableCompanyFeature ? EmailCompanyEntities : EmailCoreEntities;
+@Injectable()
+export class MyEmailConfigFactory implements EmailOptionsFactory {
+  createEmailOptions(): IEmailModuleConfig {
+    return { defaultDatabaseConfig: { /* ... */ } };
+  }
+  createOptions() { return this.createEmailOptions(); }
 }
 
-// Base type aliases for backwards compatibility
-export { EmailConfig as EmailConfigBase } from './email-config.entity';
-export { EmailTemplate as EmailTemplateBase } from './email-template.entity';
+EmailModule.forRootAsync({
+  bootstrapAppConfig: { databaseMode: 'single', enableCompanyFeature: false },
+  useClass: MyEmailConfigFactory,
+})
 ```
 
 ---
 
-## Interfaces
-
-### Provider Configuration Interfaces
-
-```typescript
-interface ISmtpTlsConfig {
-  rejectUnauthorized?: boolean;          // Reject unauthorized certs (default: true)
-  minVersion?: 'TLSv1.2' | 'TLSv1.3';    // Min TLS version (default: 'TLSv1.2')
-}
-
-interface ISmtpConfig {
-  host: string;
-  port: number;
-  secure?: boolean;
-  auth?: { user: string; pass: string };
-  tls?: ISmtpTlsConfig;                  // TLS configuration
-}
-
-interface ISendGridConfig {
-  apiKey: string;
-}
-
-interface IMailgunConfig {
-  apiKey: string;
-  domain: string;
-  region?: 'us' | 'eu';
-}
-```
-
-### Email Template Schema Interfaces
+## Configuration Reference
 
 ```typescript
-interface IEmailTemplateVariable {
-  name: string;
-  type: 'string' | 'number' | 'boolean' | 'date';
-  required?: boolean;
-  defaultValue?: string;
-  description?: string;
-}
-
-interface IEmailSection {
-  id: string;
-  type: 'header' | 'body' | 'footer';
-  name: string;
-  blocks: IEmailBlock[];
-  order: number;
-  style?: IEmailSectionStyle;
-}
-
-interface IEmailSectionStyle {
-  backgroundColor?: string;
-  padding?: string;
-  maxWidth?: string;
-}
-
-interface IEmailBlock {
-  id: string;
-  type: 'text' | 'image' | 'button' | 'divider' | 'html';
-  order: number;
-  content: Record<string, any>;
-  style?: IEmailBlockStyle;
-}
-
-interface IEmailBlockStyle {
-  textAlign?: 'left' | 'center' | 'right';
-  padding?: string;
-  margin?: string;
-  backgroundColor?: string;
-}
+interface IEmailModuleConfig extends IDataSourceServiceOptions {
+  /** Optional: default provider type when no config is specified */
+  defaultProvider?: 'smtp' | 'sendgrid' | 'mailgun';
 
-interface IEmailSettings {
-  maxWidth?: string;
-  backgroundColor?: string;
-  fontFamily?: string;
-  baseTextColor?: string;
-}
+  /** Optional: max emails per minute (default: unlimited) */
+  rateLimitPerMinute?: number;
 
-interface IEmailSchema {
-  id: string;
-  version: string;
-  name: string;
-  subject: string;
-  preheader?: string;
-  sections: IEmailSection[];
-  variables?: IEmailTemplateVariable[];
-  settings?: IEmailSettings;
+  /** Optional: enable debug logging for send operations */
+  enableLogging?: boolean;
 }
 ```
 
 ---
 
-## Email Providers
-
-### Provider Types
+## Feature Toggles
 
-```typescript
-enum EmailProviderTypeEnum {
-  SMTP = 'smtp',
-  SENDGRID = 'sendgrid',
-  MAILGUN = 'mailgun',
-}
-```
+| Feature | Config Key | Default | Effect |
+|---------|-----------|---------|--------|
+| Company scoping | `enableCompanyFeature: true` | `false` | Uses `EmailConfigWithCompany` and `EmailTemplateWithCompany` entities; filters all queries by `companyId` |
+| Multi-tenant | `databaseMode: 'multi-tenant'` | `'single'` | Creates per-tenant DataSource connections |
 
-Providers are auto-registered at module load via `EmailProviderRegistry`.
+---
 
-### SMTP Configuration
+## API Endpoints
 
-```typescript
-{
-  provider: 'smtp',
-  config: {
-    host: 'smtp.gmail.com',
-    port: 587,
-    secure: false,                         // true for port 465
-    auth: { user: 'your@gmail.com', pass: 'app-password' },
-    tls: {
-      rejectUnauthorized: true,            // Certificate validation (default: true)
-      minVersion: 'TLSv1.2',               // Minimum TLS version
-    },
-  }
-}
-```
+All endpoints use **POST**. All require JWT authentication unless noted.
 
-### SendGrid Configuration
+### Email Config — `POST /email/email-config/*`
 
-```typescript
-// Requires: npm install @sendgrid/mail
-{
-  provider: 'sendgrid',
-  config: { apiKey: 'SG.xxxxxxxxxxxx' }
-}
-```
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /email/email-config/insert` | `email-config.create` | Create a provider configuration |
+| `POST /email/email-config/get-all` | `email-config.read` | List all configs |
+| `POST /email/email-config/get/:id` | `email-config.read` | Get config by ID |
+| `POST /email/email-config/update` | `email-config.update` | Update config |
+| `POST /email/email-config/delete` | `email-config.delete` | Delete config |
+| `POST /email/email-config/test` | `email-config.create` | Send a test email to verify config |
+| `POST /email/email-config/set-default` | `email-config.update` | Set as default provider |
 
-### Mailgun Configuration
+### Email Templates — `POST /email/email-template/*`
 
-```typescript
-// Requires: npm install mailgun.js form-data
-{
-  provider: 'mailgun',
-  config: {
-    apiKey: 'key-xxxxxxxx',
-    domain: 'mail.yourdomain.com',
-    region: 'us',  // 'us' or 'eu'
-  }
-}
-```
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /email/email-template/insert` | `email-template.create` | Create a template |
+| `POST /email/email-template/get-all` | `email-template.read` | List all templates |
+| `POST /email/email-template/get/:id` | `email-template.read` | Get template by ID |
+| `POST /email/email-template/update` | `email-template.update` | Update template |
+| `POST /email/email-template/delete` | `email-template.delete` | Delete template |
 
-### Provider Interface
+### Email Send — `POST /email/send/*`
 
-```typescript
-interface IEmailProvider {
-  sendEmail(options: IEmailSendOptions): Promise<IEmailSendResult>;
-  sendBulkEmails(options: IEmailSendOptions[]): Promise<IEmailSendResult[]>;
-  healthCheck(): Promise<boolean>;
-  initialize?(config: any): Promise<void>;
-  close?(): Promise<void>;
-}
+| Endpoint | Permission | Description |
+|----------|-----------|-------------|
+| `POST /email/send/template` | `email-config.create` | Send using a stored template |
+| `POST /email/send/raw` | `email-config.create` | Send raw HTML email |
 
-interface IEmailSendOptions {
-  to: string | string[];
-  cc?: string | string[];
-  bcc?: string | string[];
-  subject: string;
-  html?: string;
-  text?: string;
-  from?: string;
-  fromName?: string;
-  replyTo?: string;
-  attachments?: IEmailAttachment[];
-}
+---
 
-interface IEmailAttachment {
-  filename: string;
-  content: Buffer | string;
-  contentType?: string;
-  encoding?: string;
-}
+## Entities
 
-interface IEmailSendResult {
-  success: boolean;
-  messageId?: string;
-  error?: string;
-}
-```
+### Core Entities (always registered)
 
-### EmailProviderRegistry
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `EmailConfig` | `email_config` | Provider configuration (SMTP credentials, SendGrid API key, etc.) |
+| `EmailTemplate` | `email_template` | Email templates with `{{variable}}` placeholders |
 
-Providers are auto-registered at module load:
+### Company Feature Entities (`enableCompanyFeature: true`)
 
-```typescript
-// Built-in registration (happens automatically)
-EmailProviderRegistry.register(EmailProviderTypeEnum.SMTP, SmtpProvider);
-EmailProviderRegistry.register(EmailProviderTypeEnum.SENDGRID, SendGridProvider);
-EmailProviderRegistry.register(EmailProviderTypeEnum.MAILGUN, MailgunProvider);
-
-// Registry methods
-EmailProviderRegistry.register(name, ProviderClass);  // Register provider
-EmailProviderRegistry.get(name);                       // Get provider class
-EmailProviderRegistry.has(name);                       // Check if registered
-EmailProviderRegistry.getAll();                        // List all providers
-EmailProviderRegistry.clear();                         // Clear registry
-```
+| Entity | Table | Description |
+|--------|-------|-------------|
+| `EmailConfigWithCompany` | `email_config` | Same as EmailConfig + `companyId` and `branchId` columns |
+| `EmailTemplateWithCompany` | `email_template` | Same as EmailTemplate + `companyId` column |
 
-### Custom Provider Example
+#### Register Entities in TypeORM
 
 ```typescript
-class MyCustomProvider implements IEmailProvider {
-  async initialize(config: any): Promise<void> {
-    // Initialize connection
-  }
-
-  async sendEmail(options: IEmailSendOptions): Promise<IEmailSendResult> {
-    // Send email
-    return { success: true, messageId: 'xxx' };
-  }
-
-  async sendBulkEmails(options: IEmailSendOptions[]): Promise<IEmailSendResult[]> {
-    return Promise.all(options.map(opt => this.sendEmail(opt)));
-  }
-
-  async healthCheck(): Promise<boolean> {
-    return true;
-  }
-
-  async close(): Promise<void> {
-    // Cleanup connections
-  }
-}
+import { EmailModule } from '@flusys/nestjs-email';
 
-// Register custom provider
-EmailProviderRegistry.register('custom', MyCustomProvider);
+TypeOrmModule.forRoot({
+  entities: [
+    ...EmailModule.getEntities({ enableCompanyFeature: true }),
+    // other entities
+  ],
+})
 ```
 
 ---
 
-## Email Configuration
-
-### EmailConfig Entity
-
-```typescript
-interface IEmailConfig {
-  id: string;
-  name: string;                // e.g., 'default', 'marketing'
-  provider: EmailProviderTypeEnum;
-  config: Record<string, any>; // Provider-specific config
-  fromEmail: string | null;
-  fromName: string | null;
-  isActive: boolean;
-  isDefault: boolean;          // Auto-selected when emailConfigId not provided
-  companyId?: string | null;   // When company feature enabled
-}
-```
-
-### Default Configuration Resolution
-
-When `emailConfigId` is not provided:
-1. Find config with `isDefault: true` and `isActive: true`
-2. Fall back to oldest active config
+## Email Providers
 
-### Creating Configurations
+### SMTP (Default)
 
-```typescript
-import { EmailProviderConfigService } from '@flusys/nestjs-email';
+Create an `EmailConfig` record with provider `smtp`:
 
-await emailConfigService.insert({
-  name: 'default',
-  provider: 'smtp',
-  fromEmail: 'noreply@example.com',
-  fromName: 'My App',
-  config: {
-    host: 'smtp.gmail.com',
-    port: 587,
-    auth: { user: '...', pass: '...' },
+```json
+POST /email/email-config/insert
+{
+  "name": "Company SMTP",
+  "provider": "smtp",
+  "config": {
+    "host": "smtp.gmail.com",
+    "port": 587,
+    "secure": false,
+    "user": "noreply@example.com",
+    "password": "app-password"
   },
-  isActive: true,
-  isDefault: true,
-}, user);
-```
-
----
-
-## Email Templates
-
-### EmailTemplate Entity
-
-```typescript
-interface IEmailTemplate {
-  id: string;
-  name: string;
-  slug: string;              // URL-friendly identifier
-  description: string | null;
-  subject: string;           // Supports {{variables}}
-  schema: Record<string, unknown>;
-  htmlContent: string;
-  textContent: string | null;
-  schemaVersion: number;     // Auto-incremented on schema change
-  isActive: boolean;
-  isHtml: boolean;           // true=HTML, false=plain text
-  metadata: Record<string, unknown> | null;
-  companyId?: string | null;
+  "fromEmail": "noreply@example.com",
+  "fromName": "My App",
+  "isDefault": true
 }
 ```
 
-### Creating Templates
+### SendGrid
 
-```typescript
-import { EmailTemplateService } from '@flusys/nestjs-email';
-
-await templateService.insert({
-  name: 'Welcome Email',
-  slug: 'welcome-email',
-  subject: 'Welcome to {{appName}}, {{userName}}!',
-  isHtml: true,
-  htmlContent: `
-    <h1>Welcome, {{userName}}!</h1>
-    <p>Thank you for joining {{appName}}.</p>
-    <a href="{{verificationLink}}">Verify Email</a>
-  `,
-  textContent: 'Welcome! Verify: {{verificationLink}}',
-  schema: {},
-  isActive: true,
-}, user);
-```
+Install `@sendgrid/mail` first, then create a config:
 
-### Variable Interpolation
-
-```typescript
-// Template: "Hello {{userName}}, your order #{{orderId}} is {{status}}."
-// Variables: { userName: "John", orderId: "12345", status: "shipped" }
-// Result: "Hello John, your order #12345 is shipped."
+```json
+POST /email/email-config/insert
+{
+  "name": "SendGrid Production",
+  "provider": "sendgrid",
+  "config": { "apiKey": "SG.xxxxxxxxxxxx" },
+  "fromEmail": "noreply@example.com",
+  "fromName": "My App",
+  "isDefault": true
+}
 ```
 
-### isHtml Toggle
-
-- **`isHtml: true`** - Sends `htmlContent` as HTML, `textContent` as fallback
-- **`isHtml: false`** - Sends `textContent` only (no HTML)
-
----
-
-## Email Sending
+### Mailgun
 
-### EmailSendService
-
-```typescript
-import { EmailSendService } from '@flusys/nestjs-email';
+Install `mailgun.js form-data` first, then create a config:
 
-// Send direct email
-const result = await emailSendService.sendEmail({
-  to: 'user@example.com',
-  subject: 'Hello!',
-  html: '<h1>Hello World</h1>',
-  text: 'Hello World',
-  emailConfigId: 'config-uuid', // Optional - uses default
-}, user);
-
-// Send using template
-const result = await emailSendService.sendTemplateEmail({
-  templateSlug: 'welcome-email',
-  to: 'user@example.com',
-  variables: {
-    userName: 'John',
-    appName: 'My App',
+```json
+POST /email/email-config/insert
+{
+  "name": "Mailgun",
+  "provider": "mailgun",
+  "config": {
+    "apiKey": "key-xxxxxxxxxxxx",
+    "domain": "mg.example.com",
+    "region": "us"
   },
-}, user);
-
-// Send with attachments
-const result = await emailSendService.sendEmail({
-  to: 'user@example.com',
-  subject: 'Your Invoice',
-  html: '<p>Invoice attached.</p>',
-  attachments: [{
-    filename: 'invoice.pdf',
-    content: base64Content,
-    contentType: 'application/pdf',
-  }],
-}, user);
+  "fromEmail": "noreply@example.com",
+  "fromName": "My App",
+  "isDefault": true
+}
 ```
 
----
-
-## DTOs
+### Custom Provider
 
-### Email Send DTOs
+Implement `IEmailProvider` and register it with `StorageProviderRegistry`:
 
 ```typescript
-// Base class for common email fields
-class BaseEmailDto {
-  to: string | string[];           // Recipient(s)
-  cc?: string | string[];          // CC recipients
-  bcc?: string | string[];         // BCC recipients
-  from?: string;                   // Sender email
-  fromName?: string;               // Sender name
-  replyTo?: string;                // Reply-to address
-  emailConfigId?: string;          // Email config to use
-  attachments?: EmailAttachmentDto[];
-}
-
-class SendEmailDto extends BaseEmailDto {
-  subject: string;
-  html: string;
-  text?: string;
-}
+import { IEmailProvider, EmailProviderRegistry } from '@flusys/nestjs-email';
 
-class SendTemplateEmailDto extends BaseEmailDto {
-  templateId?: string;             // Template ID (or slug required)
-  templateSlug?: string;           // Template slug (or ID required)
-  variables?: Record<string, any>; // Template variables
-}
-
-class TestEmailDto {
-  emailConfigId: string;
-  recipient: string;
-}
-
-class EmailAttachmentDto {
-  filename: string;
-  content: string;                 // Base64 encoded
-  contentType?: string;
-}
-
-class EmailSendResultDto {
-  success: boolean;
-  messageId?: string;
-  error?: string;
+class MyCustomProvider implements IEmailProvider {
+  async send(options: IEmailSendOptions): Promise<void> {
+    // custom sending logic
+  }
+  async testConnection(): Promise<boolean> {
+    return true;
+  }
 }
-```
-
-### Custom Validators
 
-The DTOs use custom validators for email fields:
-
-```typescript
-// Validates single email or array of emails
-@IsEmailOrEmailArray()
-to: string | string[];
-
-// Requires either templateId or templateSlug
-@RequireTemplateIdOrSlug()
-templateId?: string;
+// Register before module initialization
+EmailProviderRegistry.register('custom', MyCustomProvider);
 ```
 
 ---
 
-## Utility Functions
+## Template Engine
 
-Built-in email template utilities for common use cases:
+Templates use `{{variableName}}` syntax. All values are HTML-escaped automatically.
 
-```typescript
-import { getOtpEmailFormat, getResetPasswordEmailFormat } from '@flusys/nestjs-email/utils';
-
-// Generate OTP email HTML
-const otpHtml = getOtpEmailFormat(123456, 'John Doe');
-
-// Generate password reset email HTML
-const resetHtml = getResetPasswordEmailFormat('https://example.com/reset?token=xyz', 'John Doe');
-```
-
-### getOtpEmailFormat(otp, userName?)
-
-Generates styled HTML for OTP verification emails.
-
-```typescript
-const html = getOtpEmailFormat(123456, 'John');
-// Returns formatted HTML with OTP code prominently displayed
+**Create a template:**
+```json
+POST /email/email-template/insert
+{
+  "name": "Welcome Email",
+  "slug": "welcome",
+  "subject": "Welcome to {{appName}}, {{userName}}!",
+  "html": "<h1>Hello {{userName}}</h1><p>Welcome to <strong>{{appName}}</strong>.</p><p><a href=\"{{loginUrl}}\">Login here</a></p>",
+  "variables": ["appName", "userName", "loginUrl"]
+}
 ```
 
-### getResetPasswordEmailFormat(resetLink, userName?)
-
-Generates styled HTML for password reset emails.
-
-```typescript
-const html = getResetPasswordEmailFormat('https://app.example.com/reset?token=abc123', 'John');
-// Returns formatted HTML with reset button
+**Send using the template:**
+```json
+POST /email/send/template
+{
+  "templateSlug": "welcome",
+  "to": "user@example.com",
+  "variables": {
+    "appName": "My App",
+    "userName": "John Doe",
+    "loginUrl": "https://app.example.com/login"
+  }
+}
 ```
 
 ---
 
-## API Endpoints
-
-All endpoints use POST (RPC pattern) and require JWT authentication.
-
-### Email Configuration
-
-| Endpoint | Description |
-|----------|-------------|
-| `POST /email/email-config/insert` | Create configuration |
-| `POST /email/email-config/get/:id` | Get by ID |
-| `POST /email/email-config/get-all` | Get all (paginated) |
-| `POST /email/email-config/update` | Update |
-| `POST /email/email-config/delete` | Delete |
+## Exported Services
 
-### Email Templates
+These services are exported by `EmailModule` and injectable in your application:
 
-| Endpoint | Description |
-|----------|-------------|
-| `POST /email/email-template/insert` | Create template |
-| `POST /email/email-template/get/:id` | Get by ID |
-| `POST /email/email-template/get-all` | Get all (paginated) |
-| `POST /email/email-template/get-by-slug` | Get by slug |
-| `POST /email/email-template/update` | Update |
-| `POST /email/email-template/delete` | Delete |
+| Service | Description |
+|---------|-------------|
+| `EmailSendService` | Send emails via template slug or raw HTML |
+| `EmailTemplateService` | CRUD for email templates |
+| `EmailProviderConfigService` | CRUD for provider configurations |
+| `EmailConfigService` | Exposes runtime config (provider defaults, rate limits) |
+| `EmailDataSourceProvider` | Dynamic TypeORM DataSource resolution per request |
 
-### Email Sending
-
-| Endpoint | Description |
-|----------|-------------|
-| `POST /email/send/direct` | Send direct email |
-| `POST /email/send/template` | Send using template |
-| `POST /email/send/test` | Test configuration |
-
-### Example Requests
-
-```bash
-# Send template email
-curl -X POST http://localhost:3000/email/send/template \
-  -H "Authorization: Bearer <token>" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "templateSlug": "welcome-email",
-    "to": "user@example.com",
-    "variables": { "userName": "John" }
-  }'
-
-# Test configuration
-curl -X POST http://localhost:3000/email/send/test \
-  -H "Authorization: Bearer <token>" \
-  -d '{ "emailConfigId": "uuid", "recipient": "test@example.com" }'
-```
-
-### Controller Permissions
-
-Controllers use permission-based security via `createApiController`:
-
-```typescript
-// Email Config permissions
-EMAIL_CONFIG_PERMISSIONS.CREATE  // 'email-config.create'
-EMAIL_CONFIG_PERMISSIONS.READ    // 'email-config.read'
-EMAIL_CONFIG_PERMISSIONS.UPDATE  // 'email-config.update'
-EMAIL_CONFIG_PERMISSIONS.DELETE  // 'email-config.delete'
-
-// Email Template permissions
-EMAIL_TEMPLATE_PERMISSIONS.CREATE  // 'email-template.create'
-EMAIL_TEMPLATE_PERMISSIONS.READ    // 'email-template.read'
-EMAIL_TEMPLATE_PERMISSIONS.UPDATE  // 'email-template.update'
-EMAIL_TEMPLATE_PERMISSIONS.DELETE  // 'email-template.delete'
-
-// Email Send permission
-'email.send'
-```
+> **Note:** Always use `@Inject(ServiceClass)` explicitly — esbuild bundling loses TypeScript metadata.
 
 ---
 
-## Swagger Documentation
+## Sending Emails Programmatically
 
-### Setup Swagger for Email Module
+Inject `EmailSendService` to send emails from other services:
 
 ```typescript
-import { emailSwaggerConfig } from '@flusys/nestjs-email';
-import { setupSwaggerDocs } from '@flusys/nestjs-core/docs';
-
-// In your bootstrap function
-setupSwaggerDocs(app, emailSwaggerConfig(bootstrapAppConfig));
-```
+import { EmailSendService } from '@flusys/nestjs-email';
 
-### Swagger Config Options
+@Injectable()
+export class UserService {
+  constructor(
+    @Inject(EmailSendService) private readonly emailSendService: EmailSendService,
+  ) {}
+
+  async sendWelcomeEmail(user: { email: string; name: string }): Promise<void> {
+    await this.emailSendService.sendTemplateEmail({
+      templateSlug: 'welcome',
+      to: user.email,
+      variables: { userName: user.name, appName: 'My App' },
+    });
+  }
 
-```typescript
-function emailSwaggerConfig(bootstrapConfig?: IBootstrapAppConfig): IModuleSwaggerOptions {
-  return {
-    title: 'Email API',
-    description: '...',            // Auto-generated based on features
-    version: '1.0',
-    path: 'api/docs/email',        // Swagger UI path
-    bearerAuth: true,
-    excludeTags: [],
-    excludeSchemaProperties: [...], // Excludes companyId when company feature disabled
-  };
+  async sendRawEmail(): Promise<void> {
+    await this.emailSendService.sendRawEmail({
+      to: 'recipient@example.com',
+      subject: 'Hello',
+      html: '<p>Hello world</p>',
+      attachments: [
+        {
+          filename: 'report.pdf',
+          content: base64EncodedPdfString,
+          contentType: 'application/pdf',
+        },
+      ],
+    });
+  }
 }
 ```
 
-The Swagger documentation automatically adapts based on `enableCompanyFeature`:
-- When enabled: Shows company isolation and multi-tenant features
-- When disabled: Hides companyId fields from schemas
-
 ---
 
-## Multi-Tenant Support
-
-### Company Isolation
-
-When `enableCompanyFeature: true`:
-- Email configs are company-scoped
-- Templates are company-scoped
-- Users can only access their company's resources
+## Troubleshooting
 
-### Company Filtering
+**`No default email config found`**
 
-Services automatically filter by `companyId`:
-
-```typescript
-// In EmailTemplateService
-if (this.emailConfig.isCompanyFeatureEnabled() && user?.companyId) {
-  query.andWhere('emailTemplate.companyId = :companyId', {
-    companyId: user.companyId,
-  });
-}
-```
-
-### Dynamic Entity Selection
-
-```typescript
-protected resolveEntity(): EntityTarget<EmailTemplateBase> {
-  return this.emailConfig.isCompanyFeatureEnabled()
-    ? EmailTemplateWithCompany
-    : EmailTemplate;
-}
+Create at least one `EmailConfig` record and mark it as default:
+```json
+POST /email/email-config/set-default
+{ "id": "your-config-id" }
 ```
 
 ---
 
-## Best Practices
-
-### 1. Use Template Slugs
-
-```typescript
-// Use slug for stable references
-await emailSendService.sendTemplateEmail({
-  templateSlug: 'welcome-email',  // Stable
-  ...
-});
-
-// Avoid hardcoded IDs
-templateId: 'f47ac10b-58cc-4372-a567-...'  // May change
-```
-
-### 2. Provide Both HTML and Text
-
-```typescript
-await templateService.insert({
-  isHtml: true,
-  htmlContent: '<h1>Thank you!</h1>',
-  textContent: 'Thank you!',  // For clients that don't render HTML
-});
-```
+**`Template not found`**
 
-### 3. Test Before Production
-
-```typescript
-const result = await emailSendService.sendTestEmail(
-  configId,
-  'admin@example.com',
-  user,
-);
-if (!result.success) throw new Error(result.error);
-```
-
-### 4. Use Variables for Personalization
-
-```typescript
-// Template
-subject: 'Hello {{userName}}!'
-
-// Sending
-variables: { userName: 'John' }
-```
+Check the `templateSlug` matches exactly (case-sensitive). Use `POST /email/email-template/get-all` to list available templates.
 
 ---
 
-## API Reference
+**SMTP connection refused**
 
-### Main Exports
-
-```typescript
-// Module
-import { EmailModule } from '@flusys/nestjs-email';
-
-// Services
-import {
-  EmailConfigService,           // Module configuration service
-  EmailProviderConfigService,   // CRUD for email provider configs
-  EmailTemplateService,
-  EmailSendService,
-  EmailDataSourceProvider,
-} from '@flusys/nestjs-email/services';
-
-// Entities
-import {
-  EmailConfig,
-  EmailConfigBase,
-  EmailConfigWithCompany,
-  EmailTemplate,
-  EmailTemplateBase,
-  EmailTemplateWithCompany,
-  EmailCoreEntities,
-  EmailCompanyEntities,
-  getEmailEntitiesByConfig,
-} from '@flusys/nestjs-email/entities';
-
-// DTOs
-import {
-  CreateEmailConfigDto,
-  UpdateEmailConfigDto,
-  EmailConfigResponseDto,
-  CreateEmailTemplateDto,
-  UpdateEmailTemplateDto,
-  EmailTemplateResponseDto,
-  EmailAttachmentDto,
-  SendEmailDto,
-  SendTemplateEmailDto,
-  TestEmailDto,
-  EmailSendResultDto,
-} from '@flusys/nestjs-email/dtos';
-
-// Interfaces
-import {
-  IEmailProvider,
-  IEmailSendOptions,
-  IEmailSendResult,
-  IEmailAttachment,
-  IEmailProviderConfig,
-  IEmailConfig,
-  IEmailTemplate,
-  IEmailTemplateVariable,
-  IEmailSection,
-  IEmailSectionStyle,
-  IEmailBlock,
-  IEmailBlockStyle,
-  IEmailSettings,
-  IEmailSchema,
-  ISmtpConfig,
-  ISmtpTlsConfig,
-  ISendGridConfig,
-  IMailgunConfig,
-  IEmailModuleConfig,
-  EmailModuleOptions,
-  EmailModuleAsyncOptions,
-  EmailOptionsFactory,
-} from '@flusys/nestjs-email/interfaces';
-
-// Providers
-import {
-  EmailProviderRegistry,
-  EmailFactoryService,
-  SmtpProvider,
-  SendGridProvider,
-  MailgunProvider,
-} from '@flusys/nestjs-email/providers';
-
-// Controllers
-import {
-  EmailConfigController,
-  EmailTemplateController,
-  EmailSendController,
-} from '@flusys/nestjs-email/controllers';
-
-// Enums
-import { EmailProviderTypeEnum } from '@flusys/nestjs-email/enums';
-
-// Constants
-import {
-  EMAIL_MODULE_OPTIONS,
-  DEFAULT_FROM_NAME,
-} from '@flusys/nestjs-email/config';
-
-// Utilities
-import {
-  getOtpEmailFormat,
-  getResetPasswordEmailFormat,
-} from '@flusys/nestjs-email/utils';
-
-// Swagger Config
-import { emailSwaggerConfig } from '@flusys/nestjs-email/docs';
+Use the test endpoint first:
+```json
+POST /email/email-config/test
+{ "id": "your-config-id", "to": "test@example.com" }
 ```
 
-### Service Methods Reference
+For Gmail, enable "App Passwords" and use the app password, not your account password.
 
-#### EmailConfigService
-
-```typescript
-class EmailConfigService {
-  isCompanyFeatureEnabled(): boolean;
-  getDatabaseMode(): DatabaseMode;
-  isMultiTenant(): boolean;
-  getDefaultFromName(): string;
-  getOptions(): EmailModuleOptions;
-}
-```
-
-#### EmailProviderConfigService
-
-```typescript
-class EmailProviderConfigService {
-  // Standard CRUD (inherited from RequestScopedApiService)
-  insert(dto, user): Promise<EmailConfigBase>;
-  getById(id, user): Promise<EmailConfigBase | null>;
-  getAll(filterDto, user): Promise<{ list: EmailConfigBase[]; total: number }>;
-  update(dto, user): Promise<EmailConfigBase>;
-  delete(id, user): Promise<boolean>;
-
-  // Custom methods
-  findByIdDirect(id): Promise<EmailConfigBase | null>;
-  getDefaultConfig(user?): Promise<EmailConfigBase | null>;
-  getConfigByProvider(provider, user?): Promise<EmailConfigBase[]>;
-}
-```
+---
 
-#### EmailTemplateService
+**`No metadata for entity`**
 
+Call `EmailModule.getEntities()` with the correct flags when registering `TypeOrmModule`:
 ```typescript
-class EmailTemplateService {
-  // Standard CRUD (inherited from RequestScopedApiService)
-  insert(dto, user): Promise<EmailTemplateBase>;
-  getById(id, user): Promise<EmailTemplateBase | null>;
-  getAll(filterDto, user): Promise<{ list: EmailTemplateBase[]; total: number }>;
-  update(dto, user): Promise<EmailTemplateBase>;
-  delete(id, user): Promise<boolean>;
-
-  // Custom methods
-  findByIdDirect(id): Promise<EmailTemplateBase | null>;
-  findBySlug(slug, user?): Promise<EmailTemplateBase | null>;
-  getActiveTemplates(user?): Promise<EmailTemplateBase[]>;
-}
+entities: [...EmailModule.getEntities({ enableCompanyFeature: true })]
 ```
 
-#### EmailSendService
-
-```typescript
-class EmailSendService {
-  sendEmail(dto: SendEmailDto, user?): Promise<IEmailSendResult>;
-  sendTemplateEmail(dto: SendTemplateEmailDto, user?): Promise<IEmailSendResult>;
-  sendTestEmail(emailConfigId, recipient, user?): Promise<IEmailSendResult>;
-}
-```
+---
 
-#### EmailFactoryService
+## License
 
-```typescript
-class EmailFactoryService {
-  createProvider(config: IEmailProviderConfig): Promise<IEmailProvider>;
-  // Providers are cached by config hash for reuse
-  // Connections cleaned up on module destroy
-}
-```
+MIT © FLUSYS
 
 ---
 
-**Last Updated:** 2026-02-25
+> Part of the **FLUSYS** framework — a full-stack monorepo powering Angular 21 + NestJS 11 applications.