Configuration

Learn how to configure NestJS Mailable for different environments and transport providers.

Module Configuration

Basic Configuration

import { MailModule, TransportType, TEMPLATE_ENGINE } from 'nestjs-mailable';

@Module({
  imports: [
    MailModule.forRoot({
      transport: {
        type: TransportType.SMTP,
        host: 'localhost',
        port: 1025,
        ignoreTLS: true,
        secure: false,
        auth: {
          user: 'test',
          pass: 'test'
        }
      },
      from: {
        address: 'noreply@yourapp.com',
        name: 'Your App'
      },
      templates: {
        engine: TEMPLATE_ENGINE.HANDLEBARS,
        directory: './templates'
      }
    })
  ],
})
export class AppModule {}

Async Configuration

For dynamic configuration using environment variables or external services:

import { ConfigModule, ConfigService } from '@nestjs/config';
import { MailConfiguration } from 'nestjs-mailable';

@Module({
  imports: [
    ConfigModule.forRoot(),
    MailModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService): Promise<MailConfiguration> => ({
        transport: {
          type: configService.get('MAIL_TRANSPORT', TransportType.SMTP),
          host: configService.get('MAIL_HOST'),
          port: configService.get('MAIL_PORT', 587),
          secure: configService.get('MAIL_SECURE') === 'true',
          auth: {
            user: configService.get('MAIL_USERNAME'),
            pass: configService.get('MAIL_PASSWORD'),
          },
        },
        from: {
          address: configService.get('MAIL_FROM_ADDRESS'),
          name: configService.get('MAIL_FROM_NAME'),
        },
        templates: {
          engine: configService.get('TEMPLATE_ENGINE', TEMPLATE_ENGINE.HANDLEBARS) as any,
          directory: path.join(__dirname, '../templates'),
        },
      }),
      inject: [ConfigService],
    }),
  ],
})

Transport Providers

SMTP Transport

Perfect for most email providers like Gmail, Outlook, or custom SMTP servers.

{
  transport: {
    type: TransportType.SMTP,
    host: 'smtp.gmail.com',
    port: 587,
    secure: false, // true for 465, false for other ports
    auth: {
      user: 'your-email@gmail.com',
      pass: 'your-app-password' // Use app-specific password for Gmail
    }
  }
}

Common SMTP Providers

Gmail:

{
  host: 'smtp.gmail.com',
  port: 587,
  secure: false,
  auth: {
    user: 'your-email@gmail.com',
    pass: 'your-app-password'
  }
}

Outlook/Hotmail:

{
  host: 'smtp-mail.outlook.com',
  port: 587,
  secure: false,
  auth: {
    user: 'your-email@outlook.com',
    pass: 'your-password'
  }
}

SendGrid:

{
  host: 'smtp.sendgrid.net',
  port: 587,
  auth: {
    user: 'apikey',
    pass: 'your-sendgrid-api-key'
  }
}

Amazon SES Transport

For high-volume email sending with AWS Simple Email Service.

{
  transport: {
    type: TransportType.SES,
    region: 'us-east-1',
    credentials: {
      accessKeyId: 'your-access-key',
      secretAccessKey: 'your-secret-key'
    },
    // Optional: Custom SES endpoint (for LocalStack)
    endpoint: 'http://localhost:4566'
  }
}

Mailgun Transport

For transactional emails with Mailgun's reliable delivery.

{
  transport: {
    type: TransportType.MAILGUN,
    options: {
      apiKey: 'your-mailgun-api-key',
      domain: 'your-domain.com',
      host: 'api.mailgun.net' // or 'api.eu.mailgun.net' for EU
    }
  }
}

Single Transport Configuration (v1.1+)

The new v1.1+ configuration format focuses on single transport per module instance:

MailModule.forRoot({
  transport: {
    type: TransportType.SMTP,
    host: 'smtp.gmail.com',
    port: 587,
    secure: false,
    auth: {
      user: 'your-email@gmail.com',
      pass: 'your-app-password'
    }
  },
  from: {
    address: 'noreply@yourapp.com',
    name: 'Your App'
  }
})

Use the configured transport in your service:

@Injectable()
export class EmailService {
  constructor(private mailService: MailService) {}

  async sendWelcomeEmail(user: User) {
    await this.mailService
      .to({ address: user.email })
      .send({
        subject: 'Welcome!',
        html: '<p>Welcome to our platform!</p>'
      });
  }

  async sendTemplateEmail(user: User) {
    await this.mailService
      .to({ address: user.email })
      .send({
        subject: 'Special Offer!',
        template: 'marketing/offer',
        context: { userName: user.name }
      });
  }
}

Environment Variables

Create a .env file for your configuration:

# Mail Configuration
MAIL_TRANSPORT=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_SECURE=false
MAIL_FROM_ADDRESS=noreply@yourapp.com
MAIL_FROM_NAME="Your App Name"

# Template Configuration
TEMPLATE_ENGINE=handlebars

# SES Configuration (if using SES)
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1

# Mailgun Configuration (if using Mailgun)
MAILGUN_DOMAIN=your-domain.com
MAILGUN_SECRET=your-mailgun-api-key

Template Configuration

Configure template engines for your emails:

MailModule.forRoot({
  transport: {
    type: TransportType.SMTP,
    // ... transport config
  },
  templates: {
    engine: TEMPLATE_ENGINE.HANDLEBARS, // or TEMPLATE_ENGINE.EJS, TEMPLATE_ENGINE.PUG
    directory: './templates',
    partials: {
      header: './templates/partials/header',
      footer: './templates/partials/footer'
    },
    options: {
      helpers: {
        uppercase: (str: string) => str.toUpperCase(),
        currency: (amount: number) => `$${amount.toFixed(2)}`,
        formatDate: (date: Date) => date.toLocaleDateString()
      }
    }
  }
})

Production Considerations

Security

• Use environment variables for sensitive data
• Enable SSL/TLS for SMTP connections
• Use app-specific passwords for Gmail
• Rotate API keys regularly

Performance

• Enable connection pooling for SMTP
• Implement rate limiting for high volume sending
• Monitor email delivery rates
• Set up proper error handling and retries

Testing Configuration

// Use fake transport for testing
MailModule.forRoot({
  transport: {
    type: 'fake' as any, // For testing
  },
  from: {
    address: 'test@example.com',
    name: 'Test App'
  }
})