How to Send Email with NestJS

AHASEND_API_KEY=aha-sk-...
AHASEND_ACCOUNT_ID=your-account-uuid
AHASEND_WEBHOOK_SECRET=aha-whsec-...
WELCOME_API_TOKEN=generate-a-long-random-service-token

import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
import { ThrottlerModule } from "@nestjs/throttler";
import { AhaSendService } from "./mail/ahasend.service";
import { MailController } from "./mail/mail.controller";
import { WebhookController } from "./mail/webhook.controller";
import { InternalAuthGuard } from "./mail/internal-auth.guard";

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    // ttl is in milliseconds: at most 20 send requests per minute per client.
    ThrottlerModule.forRoot([{ ttl: 60_000, limit: 20 }]),
  ],
  controllers: [MailController, WebhookController],
  providers: [AhaSendService, InternalAuthGuard],
})
export class AppModule {}

import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { AhaSendClient } from "@ahasend/sdk";
import { createHash } from "node:crypto";

@Injectable()
export class AhaSendService {
  readonly client: AhaSendClient;

  constructor(config: ConfigService) {
    this.client = new AhaSendClient({
      apiKey: config.getOrThrow<string>("AHASEND_API_KEY"),
      accountId: config.getOrThrow<string>("AHASEND_ACCOUNT_ID"),
    });
  }

  async sendWelcome(signupId: string, email: string, name?: string) {
    const idempotencyKey = `welcome-${createHash("sha256").update(signupId).digest("hex")}`;
    const result = await this.client.messages.send({
      from: { email: "hello@yourdomain.com", name: "Your App" },
      recipients: [{ email, name }],
      subject: "Welcome to Your App!",
      html_content: "<h1>Welcome aboard 🎉</h1><p>We're glad you're here.</p>",
      text_content: "Welcome aboard! We're glad you're here.",
    }, { idempotencyKey });
    const rejected = result.data.filter((r) => r.status === "error");
    return { queued: result.data.length - rejected.length, rejected: rejected.length };
  }
}

import {
  CanActivate,
  ExecutionContext,
  Injectable,
  UnauthorizedException,
} from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { createHash, timingSafeEqual } from "node:crypto";
import type { Request } from "express";

@Injectable()
export class InternalAuthGuard implements CanActivate {
  private readonly expected: Buffer;

  constructor(config: ConfigService) {
    const token = config.getOrThrow<string>("WELCOME_API_TOKEN");
    if (token.length < 32) {
      throw new Error("WELCOME_API_TOKEN must contain at least 32 characters");
    }
    this.expected = createHash("sha256").update(token).digest();
  }

  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest<Request>();
    const parts = request.headers.authorization?.split(" ") ?? [];
    if (parts.length !== 2 || parts[0] !== "Bearer") {
      throw new UnauthorizedException();
    }

    const actual = createHash("sha256").update(parts[1]).digest();
    if (!timingSafeEqual(actual, this.expected)) {
      throw new UnauthorizedException();
    }
    return true;
  }
}

import { IsEmail, IsNotEmpty, IsOptional, IsString, MaxLength } from "class-validator";

export class WelcomeDto {
  @IsString()
  @IsNotEmpty()
  @MaxLength(128)
  signupId!: string;

  @IsEmail()
  email!: string;

  @IsOptional()
  @IsString()
  @MaxLength(200)
  name?: string;
}

import {
  BadGatewayException,
  Body,
  Controller,
  Logger,
  Post,
  UnprocessableEntityException,
  UseGuards,
} from "@nestjs/common";
import { ThrottlerGuard } from "@nestjs/throttler";
import { AhaSendAPIError, isAhaSendError } from "@ahasend/sdk";
import { AhaSendService } from "./ahasend.service";
import { InternalAuthGuard } from "./internal-auth.guard";
import { WelcomeDto } from "./welcome.dto";

@Controller("api")
@UseGuards(ThrottlerGuard, InternalAuthGuard)
export class MailController {
  private readonly logger = new Logger(MailController.name);

  constructor(private readonly ahasend: AhaSendService) {}

  @Post("welcome")
  async welcome(@Body() body: WelcomeDto) {
    let result: { queued: number; rejected: number };
    try {
      result = await this.ahasend.sendWelcome(body.signupId, body.email, body.name);
    } catch (err) {
      if (AhaSendAPIError.is(err)) {
        this.logger.error(`AhaSend API error ${err.status}; request ${err.requestId ?? "unknown"}`);
      } else if (isAhaSendError(err)) {
        this.logger.error(`AhaSend SDK error: ${err.code}`);
      } else {
        this.logger.error("Unexpected email send failure");
      }
      throw new BadGatewayException();
    }

    if (result.rejected > 0) throw new UnprocessableEntityException();
    return result;
  }
}

import { NestFactory } from "@nestjs/core";
import { ValidationPipe } from "@nestjs/common";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { rawBody: true });
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    disableErrorMessages: true,
  }));
  app.enableShutdownHooks();
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap().catch(() => {
  console.error("Nest application failed to start");
  process.exitCode = 1;
});

import {
  BadRequestException,
  Controller,
  HttpCode,
  InternalServerErrorException,
  Logger,
  Post,
  Req,
  type RawBodyRequest,
} from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import type { Request } from "express";
import { isAhaSendError } from "@ahasend/sdk";
import { WebhookVerifier } from "@ahasend/sdk/webhooks";

@Controller("webhooks")
export class WebhookController {
  private readonly logger = new Logger(WebhookController.name);
  private readonly verifier: WebhookVerifier;

  constructor(config: ConfigService) {
    this.verifier = new WebhookVerifier(
      config.getOrThrow<string>("AHASEND_WEBHOOK_SECRET"),
    );
  }

  @Post("ahasend")
  @HttpCode(204)
  async handle(@Req() req: RawBodyRequest<Request>) {
    if (req.rawBody === undefined) throw new BadRequestException();

    try {
      await this.verifier.parse(req.headers, req.rawBody);
    } catch (err) {
      if (isAhaSendError(err) && err.code === "webhook_verification_error") {
        throw new BadRequestException();
      }
      this.logger.error("Unexpected webhook processing failure");
      throw new InternalServerErrorException();
    }
  }
}