blog: add three new posts on templates, transporters, and testing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: juandav

apps/website/blog/2020-03-07-mailer.md

@@ -5,10 +5,10 @@ authors:
 tags: [nestjs, mailer, nodemailer]
 ---
 
-# Introducing @nestjs-modules/mailer
-
 A mailer module for the NestJS framework powered by Nodemailer.
 
+<!-- truncate -->
+
 ## Install
 
 ```bash

apps/website/blog/2025-03-21-multiple-transporters.md

@@ -0,0 +1,115 @@
+---
+title: "Using Multiple SMTP Transporters in Production"
+authors:
+  - name: Juan David
+tags: [nestjs, smtp, transporters, production]
+---
+
+Many production applications need more than one email provider. You might send transactional emails through one service and marketing emails through another, or you might want a fallback transporter for reliability.
+
+<!-- truncate -->
+
+## Why Multiple Transporters?
+
+Common scenarios:
+
+- **Separate transactional and marketing emails** - different providers optimize for different use cases
+- **Failover** - if your primary SMTP goes down, switch to a backup
+- **Regional compliance** - send emails from specific regions based on user location
+- **Cost optimization** - use a cheaper provider for bulk sends
+
+## Configuration
+
+Define multiple transporters in your module setup:
+
+```typescript
+MailerModule.forRoot({
+  defaults: {
+    from: '"App" <noreply@example.com>',
+  },
+  // Default transporter
+  transport: {
+    host: 'smtp.primary.com',
+    port: 587,
+    auth: {
+      user: 'primary@example.com',
+      pass: 'password',
+    },
+  },
+});
+```
+
+Then add additional transporters at runtime:
+
+```typescript
+@Injectable()
+export class EmailService {
+  constructor(private readonly mailerService: MailerService) {
+    // Register additional transporters
+    this.mailerService.addTransporter('marketing', {
+      host: 'smtp.marketing.com',
+      port: 587,
+      auth: {
+        user: 'marketing@example.com',
+        pass: 'password',
+      },
+    });
+
+    this.mailerService.addTransporter('backup', {
+      host: 'smtp.backup.com',
+      port: 587,
+      auth: {
+        user: 'backup@example.com',
+        pass: 'password',
+      },
+    });
+  }
+}
+```
+
+## Sending with a Specific Transporter
+
+Use the `transporterName` option in `sendMail()`:
+
+```typescript
+// Uses the default transporter
+await this.mailerService.sendMail({
+  to: 'user@example.com',
+  subject: 'Order Confirmation',
+  template: 'order-confirmation',
+  context: { orderId: '12345' },
+});
+
+// Uses the marketing transporter
+await this.mailerService.sendMail({
+  transporterName: 'marketing',
+  to: 'user@example.com',
+  subject: 'Weekly Newsletter',
+  template: 'newsletter',
+  context: { edition: 42 },
+});
+```
+
+## Simple Failover Pattern
+
+```typescript
+async sendWithFallback(mailOptions: ISendMailOptions) {
+  try {
+    return await this.mailerService.sendMail(mailOptions);
+  } catch (error) {
+    console.warn('Primary transporter failed, trying backup:', error.message);
+    return await this.mailerService.sendMail({
+      ...mailOptions,
+      transporterName: 'backup',
+    });
+  }
+}
+```
+
+## Tips
+
+- **Use environment variables** for all SMTP credentials. Never hardcode them.
+- **Monitor delivery rates** per transporter to catch issues early.
+- **Set timeouts** on your transporters to avoid hanging requests.
+
+Check the [Configuration](/docs/configuration#multiple-transporters) docs for more details.

apps/website/blog/2025-03-21-template-engines.md

@@ -0,0 +1,101 @@
+---
+title: "Choosing the Right Template Engine for Your Emails"
+authors:
+  - name: Juan David
+tags: [nestjs, templates, handlebars, pug, ejs, mjml]
+---
+
+Picking the right template engine can make or break your email development workflow. Here's a practical comparison of the engines supported by `@nestjs-modules/mailer`.
+
+<!-- truncate -->
+
+## Handlebars
+
+The most popular choice. Handlebars keeps logic out of templates and is easy to learn.
+
+```bash
+pnpm add @nestjs-modules/mailer-handlebars-adapter handlebars
+```
+
+```typescript
+import { HandlebarsAdapter } from '@nestjs-modules/mailer/adapters/handlebars.adapter';
+
+MailerModule.forRoot({
+  template: {
+    dir: join(__dirname, 'templates'),
+    adapter: new HandlebarsAdapter(),
+    options: { strict: true },
+  },
+});
+```
+
+**Best for:** Most projects. Simple syntax, great community support, and partials/layouts work well for email structures.
+
+## Pug
+
+Pug's indentation-based syntax produces clean, readable templates with less markup.
+
+```bash
+pnpm add @nestjs-modules/mailer-pug-adapter pug
+```
+
+```typescript
+import { PugAdapter } from '@nestjs-modules/mailer/adapters/pug.adapter';
+
+MailerModule.forRoot({
+  template: {
+    dir: join(__dirname, 'templates'),
+    adapter: new PugAdapter(),
+  },
+});
+```
+
+**Best for:** Teams that prefer concise markup and are already familiar with Pug from web projects.
+
+## EJS
+
+EJS uses plain JavaScript inside templates, giving you full control without learning a new syntax.
+
+```bash
+pnpm add @nestjs-modules/mailer-ejs-adapter ejs
+```
+
+```typescript
+import { EjsAdapter } from '@nestjs-modules/mailer/adapters/ejs.adapter';
+
+MailerModule.forRoot({
+  template: {
+    dir: join(__dirname, 'templates'),
+    adapter: new EjsAdapter(),
+  },
+});
+```
+
+**Best for:** Developers who want to use plain JavaScript expressions in templates without learning a DSL.
+
+## MJML
+
+MJML is purpose-built for responsive emails. It compiles to battle-tested HTML that works across all email clients.
+
+```bash
+pnpm add mjml
+```
+
+**Best for:** Production email systems where cross-client rendering is critical. MJML handles the responsive email quirks so you don't have to.
+
+## Quick Comparison
+
+| Engine      | Syntax      | Learning Curve | Responsive Emails | Use Case              |
+|------------|-------------|----------------|--------------------|-----------------------|
+| Handlebars | Mustache    | Low            | Manual             | General purpose       |
+| Pug        | Indentation | Medium         | Manual             | Clean markup          |
+| EJS        | JS inline   | Low            | Manual             | JS-native templates   |
+| MJML       | XML tags    | Medium         | Built-in           | Production emails     |
+
+## Recommendation
+
+Start with **Handlebars** if you're unsure. It covers most use cases, has the most examples in the community, and integrates cleanly with layouts and partials.
+
+If you're building marketing or transactional emails that must look perfect across Gmail, Outlook, and Apple Mail, consider adding **MJML**.
+
+Check the [Adapters](/docs/adapters) docs for detailed setup instructions.

apps/website/blog/2025-03-21-testing-emails.md

@@ -0,0 +1,145 @@
+---
+title: "Testing Email Sending in NestJS"
+authors:
+  - name: Juan David
+tags: [nestjs, testing, jest, e2e]
+---
+
+Testing email functionality without actually sending emails is essential for any CI/CD pipeline. Here are practical patterns for unit and integration testing with `@nestjs-modules/mailer`.
+
+<!-- truncate -->
+
+## Unit Testing with a Mock
+
+The simplest approach: mock `MailerService` in your unit tests.
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { MailerService } from '@nestjs-modules/mailer';
+import { NotificationService } from './notification.service';
+
+describe('NotificationService', () => {
+  let service: NotificationService;
+  let mailerService: MailerService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [
+        NotificationService,
+        {
+          provide: MailerService,
+          useValue: {
+            sendMail: jest.fn().mockResolvedValue({ messageId: 'test-id' }),
+          },
+        },
+      ],
+    }).compile();
+
+    service = module.get(NotificationService);
+    mailerService = module.get(MailerService);
+  });
+
+  it('should send welcome email with correct parameters', async () => {
+    await service.sendWelcomeEmail('user@example.com', 'John');
+
+    expect(mailerService.sendMail).toHaveBeenCalledWith(
+      expect.objectContaining({
+        to: 'user@example.com',
+        subject: expect.stringContaining('Welcome'),
+        context: expect.objectContaining({ name: 'John' }),
+      }),
+    );
+  });
+
+  it('should throw when email fails', async () => {
+    jest.spyOn(mailerService, 'sendMail').mockRejectedValueOnce(
+      new Error('SMTP connection refused'),
+    );
+
+    await expect(
+      service.sendWelcomeEmail('user@example.com', 'John'),
+    ).rejects.toThrow('SMTP connection refused');
+  });
+});
+```
+
+## Integration Testing with JSON Transport
+
+For integration tests where you want to verify the full pipeline (templates, context, attachments) without sending real emails, use Nodemailer's `jsonTransport`:
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { MailerModule, MailerService } from '@nestjs-modules/mailer';
+import { HandlebarsAdapter } from '@nestjs-modules/mailer/adapters/handlebars.adapter';
+import { join } from 'path';
+
+describe('Email Integration', () => {
+  let mailerService: MailerService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      imports: [
+        MailerModule.forRoot({
+          transport: { jsonTransport: true },
+          template: {
+            dir: join(__dirname, '../templates'),
+            adapter: new HandlebarsAdapter(),
+          },
+        }),
+      ],
+    }).compile();
+
+    mailerService = module.get(MailerService);
+  });
+
+  it('should render welcome template correctly', async () => {
+    const result = await mailerService.sendMail({
+      to: 'user@example.com',
+      subject: 'Welcome!',
+      template: 'welcome',
+      context: { name: 'John', code: 'ABC123' },
+    });
+
+    // jsonTransport returns the message as a JSON string
+    const message = JSON.parse(result.message);
+    expect(message.subject).toBe('Welcome!');
+    expect(message.html).toContain('John');
+    expect(message.html).toContain('ABC123');
+  });
+});
+```
+
+The `jsonTransport` option tells Nodemailer to return the composed email as a JSON object instead of sending it. This lets you inspect the fully rendered HTML, subject, headers, and attachments.
+
+## Testing with Ethereal (Dev/Staging)
+
+For manual testing or staging environments, [Ethereal](https://ethereal.email/) provides a free fake SMTP service that captures emails without delivering them:
+
+```typescript
+import * as nodemailer from 'nodemailer';
+
+// Generate test SMTP credentials
+const testAccount = await nodemailer.createTestAccount();
+
+MailerModule.forRoot({
+  transport: {
+    host: 'smtp.ethereal.email',
+    port: 587,
+    auth: {
+      user: testAccount.user,
+      pass: testAccount.pass,
+    },
+  },
+});
+```
+
+After sending, you can view captured emails at `https://ethereal.email/messages`.
+
+## Tips
+
+- **Use `jsonTransport` in CI** - it's fast, has no network dependencies, and lets you assert on rendered output.
+- **Mock at the service level for unit tests** - don't pull in the full `MailerModule` when you only need to verify your service logic.
+- **Use Ethereal for visual testing** - when you need to see what the email actually looks like before going to production.
+- **Test error paths** - verify your code handles SMTP failures gracefully.
+
+Check the [Getting Started](/docs/getting-started) guide for setup instructions.