@flusys/nestjs-email

Database-driven email system for NestJS — multi-provider (SMTP, SendGrid, Mailgun), template engine with {{variable}} interpolation, and company scoping.

Installation

npm install @flusys/nestjs-email @flusys/nestjs-shared @flusys/nestjs-core

# Provider SDKs — install only what you use
npm install nodemailer           # SMTP (default, always safe to install)
npm install @sendgrid/mail       # SendGrid
npm install mailgun.js form-data # Mailgun

1. Module Registration

forRoot (sync)

Mode 1: Single Database

import { EmailModule } from '@flusys/nestjs-email';

@Module({
  imports: [
    EmailModule.forRoot({
      global: true,
      includeController: true,
      bootstrapAppConfig: {
        databaseMode: 'single',
        enableCompanyFeature: false,
      },
      config: {
        defaultDatabaseConfig: {
          type: 'mysql',
          host: process.env.DB_HOST,
          port: Number(process.env.DB_PORT ?? 3306),
          username: process.env.DB_USER,
          password: process.env.DB_PASSWORD,
          database: process.env.DB_NAME,
        },
      },
    }),
  ],
})
export class AppModule {}

Mode 2: Multi-Tenant

EmailModule.forRoot({
  global: true,
  includeController: true,
  bootstrapAppConfig: {
    databaseMode: 'multi-tenant',
    enableCompanyFeature: true,
  },
  config: {
    tenantDefaultDatabaseConfig: {
      type: 'mysql',
      host: process.env.TENANT_DB_HOST,
      port: Number(process.env.TENANT_DB_PORT ?? 3306),
      username: process.env.TENANT_DB_USER,
      password: process.env.TENANT_DB_PASSWORD,
      database: process.env.TENANT_DB_NAME,
    },
    tenants: [
      { id: 'tenant-a', database: 'tenant_a_db' },
      { id: 'tenant-b', database: 'tenant_b_db' },
    ],
  },
});

forRootAsync (factory)

import { ConfigModule, ConfigService } from '@nestjs/config';
import { EmailModule, ITenantDatabaseConfig } from '@flusys/nestjs-email';

// Single database
EmailModule.forRootAsync({
  global: true,
  includeController: true,
  bootstrapAppConfig: {
    databaseMode: 'single',
    enableCompanyFeature: true,
  },
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    defaultDatabaseConfig: {
      type: 'mysql',
      host: config.get('DB_HOST'),
      port: config.get<number>('DB_PORT'),
      username: config.get('DB_USER'),
      password: config.get('DB_PASSWORD'),
      database: config.get('DB_NAME'),
    },
  }),
  inject: [ConfigService],
});

// Multi-tenant
EmailModule.forRootAsync({
  global: true,
  includeController: true,
  bootstrapAppConfig: {
    databaseMode: 'multi-tenant',
    enableCompanyFeature: true,
  },
  imports: [ConfigModule],
  useFactory: (config: ConfigService) => ({
    tenantDefaultDatabaseConfig: {
      type: 'mysql',
      host: config.get('TENANT_DB_HOST'),
      port: config.get<number>('TENANT_DB_PORT'),
      username: config.get('TENANT_DB_USER'),
      password: config.get('TENANT_DB_PASSWORD'),
      database: config.get('TENANT_DB_NAME'),
    },
    tenants: config.get<ITenantDatabaseConfig[]>('TENANTS'),
  }),
  inject: [ConfigService],
});

2. Register Entities

import { getEmailEntitiesByConfig } from '@flusys/nestjs-email/entities';

TypeOrmModule.forRoot({
  entities: [
    ...getEmailEntitiesByConfig(false), // match enableCompanyFeature in bootstrapAppConfig
  ],
});

| enableCompanyFeature | Entities registered | | ---------------------- | ---------------------------------------------------- | | false | EmailConfig, EmailTemplate | | true | EmailConfigWithCompany, EmailTemplateWithCompany |

3. Send Emails

Via template

Create a template first:

POST /email/email-template/insert
{
  "name": "Welcome",
  "slug": "welcome",
  "subject": "Welcome, {{userName}}!",
  "htmlContent": "<h1>Hello {{userName}}</h1><p>Welcome to {{appName}}.</p>",
  "isHtml": true
}

Then send it from your service:

import { EmailSendService } from '@flusys/nestjs-email';

@Injectable()
export class UserService {
  constructor(@Inject(EmailSendService) private readonly emailSend: EmailSendService) {}

  async sendWelcome(user: { email: string; name: string }): Promise<void> {
    await this.emailSend.sendTemplateEmail({
      templateSlug: 'welcome', // or templateId: 'uuid'
      to: user.email,
      variables: { userName: user.name, appName: 'My App' },
    });
  }
}

All {{variable}} values in HTML are HTML-escaped automatically.

Raw email with attachments

await this.emailSend.sendEmail({
  to: '[email protected]',
  subject: 'Your Report',
  html: '<p>See attached.</p>',
  attachments: [
    {
      filename: 'report.pdf',
      content: base64String, // base64-encoded file content
      contentType: 'application/pdf',
    },
  ],
});

License

MIT © FLUSYS