Send email from NestJS with a service, a DTO and a webhook.

// src/notix/notix.service.ts
import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { Notix } from "notix-js";

@Injectable()
export class NotixService {
  private readonly client: Notix;

  constructor(config: ConfigService) {
    // getOrThrow: a missing key fails at boot, not inside a request.
    const apiKey = config.getOrThrow<string>("NOTIX_API_KEY");
    // Pointing at a different Notix base URL (a staging environment, say)?
    // Read it from config and pass it as the second argument.
    this.client = new Notix(apiKey);
  }

  get emails() {
    return this.client.emails;
  }

  webhooks(secret: string) {
    return this.client.webhooks(secret);
  }
}

// src/notix/notix.module.ts
import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
import { NotixService } from "./notix.service";

@Module({
  imports: [ConfigModule],
  providers: [NotixService],
  exports: [NotixService],
})
export class NotixModule {}

// src/receipts/send-receipt.dto.ts
import { IsEmail, IsString, Length } from "class-validator";

export class SendReceiptDto {
  @IsString()
  @Length(1, 64)
  orderId!: string;

  @IsEmail()
  to!: string;
}

// src/receipts/receipts.controller.ts
import { Body, Controller, HttpCode, Post } from "@nestjs/common";
import { NotixService } from "../notix/notix.service";
import { NotixApiException } from "../notix/notix-api.exception";
import { SendReceiptDto } from "./send-receipt.dto";

@Controller("receipts")
export class ReceiptsController {
  constructor(private readonly notix: NotixService) {}

  @Post()
  @HttpCode(202)
  async send(@Body() dto: SendReceiptDto) {
    const { data, error } = await this.notix.emails.send(
      {
        from: "receipts@acme.com",
        to: dto.to,
        templateId: "tpl_receipt_v4",
        variables: { orderId: dto.orderId },
      },
      // One key per business event, so a retried request can never send twice.
      { idempotencyKey: `order-${dto.orderId}-receipt` },
    );

    if (error) throw new NotixApiException(error);
    return { emailId: data.emailId };
  }
}

// src/notix/notix-api.exception.ts
import { HttpException } from "@nestjs/common";

// The API answers every failure as { code, message }. A 401 or 403 from
// Notix is our key, not the caller's problem, so it surfaces as a 500.
const STATUS: Record<string, number> = {
  BAD_REQUEST: 400,
  UNAUTHORIZED: 500,
  FORBIDDEN: 500,
  NOT_FOUND: 404,
  NOT_UNIQUE: 409,
  RISK_REFUSED: 422,
  INSUFFICIENT_BALANCE: 402,
  RATE_LIMITED: 429,
  INTERNAL_SERVER_ERROR: 502,
  SERVICE_UNAVAILABLE: 503,
};

export class NotixApiException extends HttpException {
  constructor(error: { code: string; message: string }) {
    const status = STATUS[error.code] ?? 500;
    super(
      { error: status >= 500 ? "Email could not be sent" : error.message, code: error.code },
      status,
    );
  }
}

// src/webhooks/webhooks.controller.ts
import { BadRequestException, Controller, HttpCode, Post, Req } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import type { RawBodyRequest } from "@nestjs/common";
import type { Request } from "express";
import { NotixService } from "../notix/notix.service";

@Controller("webhooks")
export class WebhooksController {
  private readonly secret: string;

  constructor(private readonly notix: NotixService, config: ConfigService) {
    this.secret = config.getOrThrow<string>("NOTIX_WEBHOOK_SECRET");
  }

  @Post("notix")
  @HttpCode(200)
  handle(@Req() req: RawBodyRequest<Request>) {
    // req.rawBody is the Buffer Nest kept because main.ts passed rawBody: true.
    if (!req.rawBody) throw new BadRequestException("raw body missing");

    let event;
    try {
      event = this.notix.webhooks(this.secret).constructEvent(req.rawBody, { headers: req.headers });
    } catch {
      throw new BadRequestException("invalid signature");
    }

    switch (event.type) {
      case "email.delivered":
        // event.data.id is the emailId the send returned
        break;
      case "email.bounced":
        // event.data.bounce.type === "Permanent": the address is now suppressed
        break;
    }
    return { ok: true }; // answer fast, do the work on a queue
  }
}

// src/main.ts
import { NestFactory } from "@nestjs/core";
import { ValidationPipe } from "@nestjs/common";
import type { NestExpressApplication } from "@nestjs/platform-express";
import { AppModule } from "./app.module";

async function bootstrap() {
  // rawBody: true keeps the unparsed bytes on req.rawBody for the webhook
  // signature; the built-in JSON parser stays on for everything else.
  const app = await NestFactory.create<NestExpressApplication>(AppModule, { rawBody: true });
  app.useGlobalPipes(new ValidationPipe({ whitelist: true }));
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

// src/app.module.ts
import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
import { NotixModule } from "./notix/notix.module";
import { ReceiptsController } from "./receipts/receipts.controller";
import { WebhooksController } from "./webhooks/webhooks.controller";

@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true }), NotixModule],
  controllers: [ReceiptsController, WebhooksController],
})
export class AppModule {}