EmailVerificationService

Package: @nauth-toolkit/core Type: Service

Email verification service that handles sending verification codes, verifying emails with codes or tokens, and resending with rate limiting.

NestJS

import { EmailVerificationService } from '@nauth-toolkit/nestjs';

Express

import { EmailVerificationService } from '@nauth-toolkit/core';
// Access via nauth.emailVerificationService after NAuth.create()

Fastify

import { EmailVerificationService } from '@nauth-toolkit/core';
// Access via nauth.emailVerificationService after NAuth.create()

Overview

Handles email verification workflow including code generation, email delivery, verification with code or token, and resend operations with rate limiting.

note

Auto-injected by framework. No manual instantiation required.

Methods

resendVerificationEmail()

Resend verification email with rate limiting.

async resendVerificationEmail(dto: ResendVerificationEmailDTO): Promise<ResendVerificationEmailResponseDTO>

Parameters

• dto - ResendVerificationEmailDTO - Request DTO
  • sub - string (optional) - User identifier (UUID v4)
  • email - string (optional) - User email address
  • baseUrl - string (optional) - Base URL for verification link

info

Either sub or email must be provided (not both).

Returns

• ResendVerificationEmailResponseDTO - Response with token ID
  • tokenId - number - Verification token ID (internal)

Errors

Code	When	Details
NOT_FOUND	User not found	{ userId?: string }
RATE_LIMIT_RESEND	Resend delay not met	{ retryAfter: number, resendDelay: number }
VALIDATION_FAILED	Neither sub nor email	{ message: string }

Example

NestJS

import { ResendVerificationEmailDTO } from '@nauth-toolkit/nestjs';

@Injectable()
export class MyService {
  constructor(private emailVerificationService: EmailVerificationService) {}

  async resendBySub() {
    const dto: ResendVerificationEmailDTO = {
      sub: 'a21b654c-2746-4168-acee-c175083a65cd',
      baseUrl: 'https://example.com',
    };
    await this.emailVerificationService.resendVerificationEmail(dto);
  }

  async resendByEmail() {
    const dto: ResendVerificationEmailDTO = {
      email: 'user@example.com',
      baseUrl: 'https://example.com',
    };
    await this.emailVerificationService.resendVerificationEmail(dto);
  }
}

Express

import { ResendVerificationEmailDTO } from '@nauth-toolkit/core';

// Resend by sub
app.post('/resend-verification', async (req, res) => {
  const dto: ResendVerificationEmailDTO = {
    sub: req.body.sub,
    baseUrl: 'https://example.com',
  };
  await nauth.emailVerificationService.resendVerificationEmail(dto);
  res.json({ success: true });
});

// Resend by email
app.post('/resend-verification-email', async (req, res) => {
  const dto: ResendVerificationEmailDTO = {
    email: req.body.email,
    baseUrl: 'https://example.com',
  };
  await nauth.emailVerificationService.resendVerificationEmail(dto);
  res.json({ success: true });
});

Fastify

import { ResendVerificationEmailDTO } from '@nauth-toolkit/core';

// Resend by sub
fastify.post('/resend-verification', nauth.adapter.wrapRouteHandler(async (req, reply) => {
  const dto: ResendVerificationEmailDTO = {
    sub: req.body.sub,
    baseUrl: 'https://example.com',
  };
  await nauth.emailVerificationService.resendVerificationEmail(dto);
  return { success: true };
}));

// Resend by email
fastify.post('/resend-verification-email', nauth.adapter.wrapRouteHandler(async (req, reply) => {
  const dto: ResendVerificationEmailDTO = {
    email: req.body.email,
    baseUrl: 'https://example.com',
  };
  await nauth.emailVerificationService.resendVerificationEmail(dto);
  return { success: true };
}));

---

sendMFAEmailCode()

Send MFA email verification code. Used internally during MFA challenges.

async sendMFAEmailCode(dto: SendVerificationEmailDTO): Promise<SendVerificationEmailResponseDTO>

Parameters

• dto - SendVerificationEmailDTO - Request DTO
  • sub - string - User identifier (UUID v4)
  • challengeSessionId - number (optional) - Challenge session ID to link the verification token to a specific session
  • skipAlreadyVerifiedCheck - boolean (optional) - Skip already verified check

Returns

• SendVerificationEmailResponseDTO - Response with token ID
  • tokenId - number - Verification token ID (internal)

Errors

Code	When	Details
ALREADY_VERIFIED	Email already verified	{}
NOT_FOUND	User not found	{ userId: string }
RATE_LIMIT_EMAIL	Too many requests	{ retryAfter: number, currentCount: number }
RATE_LIMIT_RESEND	Resend delay not met	{ retryAfter: number, resendDelay: number }

---

sendVerificationEmail()

Send verification email to user with code and optional link.

async sendVerificationEmail(dto: SendVerificationEmailDTO): Promise<SendVerificationEmailResponseDTO>

Parameters

• dto - SendVerificationEmailDTO - Request DTO
  • sub - string - User identifier (UUID v4)
  • baseUrl - string (optional) - Base URL for verification link
  • skipAlreadyVerifiedCheck - boolean (optional) - Skip already verified check (for MFA)
  • challengeSessionId - number (optional) - Challenge session ID to link the verification token to a specific session
  • challengeSessionToken - string (optional) - Challenge session token (UUID v4) to embed in the verification link for cross-browser verification

Returns

• SendVerificationEmailResponseDTO - Response with token ID
  • tokenId - number - Verification token ID (internal)

Errors

Code	When	Details
ALREADY_VERIFIED	Email already verified	{}
NOT_FOUND	User not found	{ userId: string }
RATE_LIMIT_EMAIL	Too many requests	{ retryAfter: number, currentCount: number }
RATE_LIMIT_RESEND	Resend delay not met	{ retryAfter: number, resendDelay: number }

Example

NestJS

import { SendVerificationEmailDTO } from '@nauth-toolkit/nestjs';

@Injectable()
export class MyService {
  constructor(private emailVerificationService: EmailVerificationService) {}

  async sendCode() {
    const dto: SendVerificationEmailDTO = {
      sub: 'a21b654c-2746-4168-acee-c175083a65cd',
      baseUrl: 'https://example.com',
    };
    const result = await this.emailVerificationService.sendVerificationEmail(dto);
    console.log('Token ID:', result.tokenId);
  }
}

Express

import { SendVerificationEmailDTO } from '@nauth-toolkit/core';

app.post('/send-verification', async (req, res) => {
  const dto: SendVerificationEmailDTO = {
    sub: req.body.sub,
    baseUrl: 'https://example.com',
  };
  const result = await nauth.emailVerificationService.sendVerificationEmail(dto);
  res.json({ tokenId: result.tokenId });
});

Fastify

import { SendVerificationEmailDTO } from '@nauth-toolkit/core';

fastify.post('/send-verification', nauth.adapter.wrapRouteHandler(async (req, reply) => {
  const dto: SendVerificationEmailDTO = {
    sub: req.body.sub,
    baseUrl: 'https://example.com',
  };
  const result = await nauth.emailVerificationService.sendVerificationEmail(dto);
  return { tokenId: result.tokenId };
}));

---

verifyEmailWithCode()

Verify email address using 6-digit code.

async verifyEmailWithCode(dto: VerifyEmailWithCodeDTO): Promise<VerifyEmailResponseDTO>

Parameters

• dto - VerifyEmailWithCodeDTO - Request DTO
  • email - string - User email address
  • code - string - 6-digit verification code

Returns

• VerifyEmailResponseDTO - Response with success message
  • message - string - Success message

Errors

Code	When	Details
NOT_FOUND	User not found	{ email: string }
VERIFICATION_CODE_EXPIRED	Code expired	{}
VERIFICATION_CODE_INVALID	Invalid or expired code	{}
VERIFICATION_TOO_MANY_ATTEMPTS	Too many attempts	{}

Example

NestJS

import { VerifyEmailWithCodeDTO } from '@nauth-toolkit/nestjs';

@Injectable()
export class MyService {
  constructor(private emailVerificationService: EmailVerificationService) {}

  async verify() {
    const dto: VerifyEmailWithCodeDTO = {
      email: 'user@example.com',
      code: '123456',
    };
    const result = await this.emailVerificationService.verifyEmailWithCode(dto);
    console.log(result.message);
  }
}

Express

import { VerifyEmailWithCodeDTO } from '@nauth-toolkit/core';

app.post('/verify-email', async (req, res) => {
  const dto: VerifyEmailWithCodeDTO = {
    email: req.body.email,
    code: req.body.code,
  };
  const result = await nauth.emailVerificationService.verifyEmailWithCode(dto);
  res.json({ message: result.message });
});

Fastify

import { VerifyEmailWithCodeDTO } from '@nauth-toolkit/core';

fastify.post('/verify-email', nauth.adapter.wrapRouteHandler(async (req, reply) => {
  const dto: VerifyEmailWithCodeDTO = {
    email: req.body.email,
    code: req.body.code,
  };
  const result = await nauth.emailVerificationService.verifyEmailWithCode(dto);
  return { message: result.message };
}));

---

verifyEmailWithToken()

Verify email address using URL token (link-based verification).

async verifyEmailWithToken(dto: VerifyEmailWithTokenDTO): Promise<VerifyEmailResponseDTO>

Parameters

• dto - VerifyEmailWithTokenDTO - Request DTO
  • token - string - Verification token (64-character hex string)

Returns

• VerifyEmailResponseDTO - Response with success message
  • message - string - Success message

Errors

Code	When	Details
VERIFICATION_CODE_EXPIRED	Token expired	{}
VERIFICATION_CODE_INVALID	Invalid or expired token	{}

Example

NestJS

import { VerifyEmailWithTokenDTO } from '@nauth-toolkit/nestjs';

@Injectable()
export class MyService {
  constructor(private emailVerificationService: EmailVerificationService) {}

  async verifyWithLink() {
    const dto: VerifyEmailWithTokenDTO = {
      token: 'abc123...', // 64-char hex string from URL
    };
    const result = await this.emailVerificationService.verifyEmailWithToken(dto);
    console.log(result.message);
  }
}

Express

import { VerifyEmailWithTokenDTO } from '@nauth-toolkit/core';

app.get('/verify-email', async (req, res) => {
  const dto: VerifyEmailWithTokenDTO = {
    token: req.query.token as string,
  };
  const result = await nauth.emailVerificationService.verifyEmailWithToken(dto);
  res.json({ message: result.message });
});

Fastify

import { VerifyEmailWithTokenDTO } from '@nauth-toolkit/core';

fastify.get('/verify-email', nauth.adapter.wrapRouteHandler(async (req, reply) => {
  const dto: VerifyEmailWithTokenDTO = {
    token: req.query.token as string,
  };
  const result = await nauth.emailVerificationService.verifyEmailWithToken(dto);
  return { message: result.message };
}));

---

Related

• ResendVerificationEmailDTO
• ResendVerificationEmailResponseDTO
• SendVerificationEmailDTO
• SendVerificationEmailResponseDTO
• VerifyEmailResponseDTO
• VerifyEmailWithCodeDTO
• VerifyEmailWithTokenDTO
• AuthService
• NAuthException