Building Production-Ready SMS Marketing Campaigns with NestJS and Vonage

This guide provides a step-by-step walkthrough for building a robust SMS marketing campaign application using NestJS, TypeScript, TypeORM, PostgreSQL, and the Vonage Messages API. We will cover everything from initial project setup and Vonage configuration to implementing core features, handling webhooks, ensuring security, and deploying the application.

By the end of this tutorial, you will have a functional NestJS application capable of:

• Managing marketing campaigns and subscriber lists.
• Sending bulk SMS messages via the Vonage Messages API.
• Receiving inbound SMS messages (e.g., STOP replies).
• Tracking message delivery statuses.
• Implementing basic security, error handling, and logging.

This guide aims to be a complete reference, enabling developers to build and deploy a production-ready system, following the specified guidelines and structure.

Prerequisites:

• Node.js and npm/yarn: Ensure you have a recent LTS version installed.
• NestJS CLI: Install globally: npm install -g @nestjs/cli
• Docker and Docker Compose: For running PostgreSQL locally and containerizing the application.
• Vonage API Account: Sign up for free at vonage.com. You'll need your Application ID and Private Key.
• Vonage Phone Number: Purchase an SMS-capable number from your Vonage dashboard.
• ngrok: Useful for testing webhooks locally. Sign up for a free account at ngrok.com and install it. Note: For production environments, you will need a stable, publicly accessible URL for your webhook endpoints. This could be your deployed application's URL on a server, a PaaS, or a dedicated tunneling service with a stable address. Using a staging environment that mirrors production is recommended for testing before deploying live.

1. Setting Up the NestJS Project

Let's initialize our NestJS project and install the necessary dependencies.

1. Create a New NestJS Project: Open your terminal and run:

   bash

   nest new vonage-sms-campaign-app
   cd vonage-sms-campaign-app
   

   Choose your preferred package manager (npm or yarn).

2. Install Dependencies: We need modules for configuration, database interaction (TypeORM with PostgreSQL), validation, the Vonage SDK, rate limiting, and health checks.

   bash

   # Core NestJS & Utility Modules
   npm install @nestjs/config @nestjs/typeorm typeorm pg class-validator class-transformer dotenv
   
   # Vonage SDK
   npm install @vonage/server-sdk
   
   # Optional but Recommended for Production
   npm install @nestjs/terminus nestjs-rate-limiter helmet # Health checks, rate limiting, security headers
   npm install --save-dev @types/helmet # Types for helmet
   
   • @nestjs/config: Manages environment variables.
   • @nestjs/typeorm, typeorm, pg: For PostgreSQL database integration using TypeORM.
   • class-validator, class-transformer: For request data validation using DTOs.
   • dotenv: Loads environment variables from a .env file.
   • @vonage/server-sdk: The official Vonage Node.js SDK.
   • @nestjs/terminus: Implements health check endpoints.
   • nestjs-rate-limiter: Adds rate limiting to protect endpoints.
   • helmet: Sets various HTTP headers for security.

3. Project Structure (Conceptual): NestJS promotes a modular structure. We'll organize our code logically:

   vonage-sms-campaign-app/
   ├── src/
   │   ├── app.module.ts         # Root module
   │   ├── main.ts               # Application entry point
   │   ├── config/               # Configuration setup (env vars)
   │   ├── database/             # Database connection, entities, migrations
   │   ├── campaigns/            # Campaign management module (controller, service, entity)
   │   ├── subscribers/          # Subscriber management module (controller, service, entity)
   │   ├── vonage/               # Vonage integration module (service, config)
   │   ├── webhooks/             # Webhook handling module (controller, service)
   │   ├── common/               # Shared utilities, filters, interceptors
   │   └── health/               # Health check module
   ├── .env                      # Environment variables (DO NOT COMMIT SENSITIVE DATA)
   ├── .env.example              # Example environment variables
   ├── ormconfig.json            # TypeORM configuration (optional, can be in AppModule)
   ├── Dockerfile
   ├── docker-compose.yml
   └── ... (other NestJS files)
   

2. Vonage Account and Application Setup

Before writing code, configure your Vonage account and application correctly. This is critical for authentication and receiving webhooks.

1. Access Vonage Dashboard: Log in to your Vonage API Dashboard.
2. API Settings (Crucial):
   • Navigate to API settings in the left-hand menu.
   • Scroll down to the SMS settings section.
   • Under Default SMS Setting, ensure Messages API is selected. This determines the webhook format and authentication method we'll use. Save changes if necessary.
3. Create a Vonage Application:
   • Go to Applications -> Create a new application.
   • Give it a name (e.g., NestJS SMS Campaigns).
   • Enable the Messages capability.
   • You'll need webhook URLs. For now, enter temporary placeholders like http://example.com/webhooks/inbound for the Inbound URL and http://example.com/webhooks/status for the Status URL. We will update these later with our ngrok URL or public deployment URL.
   • Click Generate public and private key. Save the private.key file securely within your project directory (e.g., at the root). Do not commit this file to Git. Add private.key to your .gitignore file.
   • Note down the Application ID displayed after creation.
4. Link Your Vonage Number:
   • Go to Numbers -> Your numbers.
   • Find the SMS-capable number you purchased.
   • Click Manage or Link next to the number.
   • Select the application you just created (NestJS SMS Campaigns) from the dropdown and save. This directs incoming messages for this number to your application's webhooks.

3. Environment Configuration (.env and ConfigModule)

Securely manage API keys and other configuration settings using environment variables.

1. Create .env and .env.example files: In the project root, create .env (for your local values) and .env.example (as a template). Add .env to your .gitignore.

   File: .env.example

   bash

   # Application
   PORT=3000
   NODE_ENV=development
   
   # Vonage Configuration
   VONAGE_APPLICATION_ID=YOUR_VONAGE_APPLICATION_ID
   VONAGE_PRIVATE_KEY_PATH=./private.key # Relative path to your downloaded key
   VONAGE_NUMBER=YOUR_VONAGE_VIRTUAL_NUMBER # e.g., 14155550100
   
   # Database (PostgreSQL)
   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_USERNAME=your_db_user
   DATABASE_PASSWORD=your_db_password
   DATABASE_NAME=sms_campaigns_db
   
   # ngrok URL (update when running ngrok for local testing) or Public URL
   BASE_URL=http://localhost:3000
   

   File: .env

   bash

   # Fill with your actual values
   PORT=3000
   NODE_ENV=development
   
   VONAGE_APPLICATION_ID=abc123xyz...
   VONAGE_PRIVATE_KEY_PATH=./private.key
   VONAGE_NUMBER=14155550100
   
   DATABASE_HOST=localhost
   DATABASE_PORT=5432
   DATABASE_USERNAME=postgres # Default for docker-compose setup later
   DATABASE_PASSWORD=secret
   DATABASE_NAME=sms_campaigns_db
   
   BASE_URL=http://localhost:3000 # Will be replaced by ngrok URL during development or public URL in deployment
   

2. Integrate ConfigModule: Configure the ConfigModule in your root AppModule to load these variables globally.

   File: src/app.module.ts

   typescript

   import { Module } from '@nestjs/common';
   import { ConfigModule } from '@nestjs/config';
   import { TypeOrmModule } from '@nestjs/typeorm'; // Import later
   // Other module imports...
   
   @Module({
     imports: [
       ConfigModule.forRoot({
         isGlobal: true, // Make ConfigService available globally
         envFilePath: '.env', // Specify the env file
       }),
       // TypeOrmModule will be added here later
       // Other modules...
     ],
     controllers: [],
     providers: [],
   })
   export class AppModule {}
   

4. Database Schema and Data Layer (TypeORM & PostgreSQL)

We'll use TypeORM to define our entities and interact with a PostgreSQL database.

1. Docker Compose for PostgreSQL: Create a docker-compose.yml file in the project root for easy local database setup.

   File: docker-compose.yml

   yaml

   version: '3.8'
   services:
     postgres:
       image: postgres:15-alpine
       container_name: vonage_sms_postgres
       environment:
         POSTGRES_USER: ${DATABASE_USERNAME:-postgres} # Use .env or default
         POSTGRES_PASSWORD: ${DATABASE_PASSWORD:-secret}
         POSTGRES_DB: ${DATABASE_NAME:-sms_campaigns_db}
       ports:
         - ""${DATABASE_PORT:-5432}:5432""
       volumes:
         - postgres_data:/var/lib/postgresql/data
       restart: unless-stopped
   
   volumes:
     postgres_data:
       driver: local
   

   Run docker-compose up -d to start the PostgreSQL container.

2. Define Entities: Create entity files for Campaign, Subscriber, and MessageLog.

   File: src/database/entities/subscriber.entity.ts

   typescript

   import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn, Index } from 'typeorm';
   
   export enum SubscriptionStatus {
     SUBSCRIBED = 'subscribed',
     UNSUBSCRIBED = 'unsubscribed',
   }
   
   @Entity('subscribers')
   export class Subscriber {
     @PrimaryGeneratedColumn('uuid')
     id: string;
   
     @Index({ unique: true })
     @Column({ type: 'varchar', length: 20 })
     phoneNumber: string; // E.164 format recommended
   
     @Column({ type: 'varchar', length: 100, nullable: true })
     firstName?: string;
   
     @Column({ type: 'varchar', length: 100, nullable: true })
     lastName?: string;
   
     @Column({
       type: 'enum',
       enum: SubscriptionStatus,
       default: SubscriptionStatus.SUBSCRIBED,
     })
     status: SubscriptionStatus;
   
     @CreateDateColumn()
     subscribedAt: Date;
   
     @UpdateDateColumn()
     updatedAt: Date;
   
     @Column({ type: 'timestamp', nullable: true })
     unsubscribedAt?: Date;
   }
   

   File: src/database/entities/campaign.entity.ts

   typescript

   import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, OneToMany } from 'typeorm';
   import { MessageLog } from './message-log.entity';
   
   export enum CampaignStatus {
     DRAFT = 'draft',
     SCHEDULED = 'scheduled',
     SENDING = 'sending',
     SENT = 'sent',
     FAILED = 'failed',
   }
   
   @Entity('campaigns')
   export class Campaign {
     @PrimaryGeneratedColumn('uuid')
     id: string;
   
     @Column({ type: 'varchar', length: 255 })
     name: string;
   
     @Column({ type: 'text' })
     messageTemplate: string;
   
     @Column({
       type: 'enum',
       enum: CampaignStatus,
       default: CampaignStatus.DRAFT,
     })
     status: CampaignStatus;
   
     @CreateDateColumn()
     createdAt: Date;
   
     @Column({ type: 'timestamp', nullable: true })
     scheduledAt?: Date;
   
     @Column({ type: 'timestamp', nullable: true })
     sentAt?: Date;
   
     // Relation: A campaign can have many message logs
     @OneToMany(() => MessageLog, (log) => log.campaign)
     messageLogs: MessageLog[];
   }
   

   File: src/database/entities/message-log.entity.ts

   typescript

   import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, UpdateDateColumn, ManyToOne, Index } from 'typeorm';
   import { Campaign } from './campaign.entity';
   import { Subscriber } from './subscriber.entity';
   
   export enum MessageStatus {
     PENDING = 'pending', // Initial state before sending attempt
     SUBMITTED = 'submitted', // Successfully submitted to Vonage
     DELIVERED = 'delivered', // Confirmed delivery
     EXPIRED = 'expired', // Message expired before delivery
     FAILED = 'failed', // Delivery failed
     REJECTED = 'rejected', // Rejected by carrier or Vonage
     UNKNOWN = 'unknown', // Status unknown or not yet received
   }
   
   @Entity('message_logs')
   @Index(['vonageMessageId']) // Index for quick lookup via webhook
   export class MessageLog {
     @PrimaryGeneratedColumn('uuid')
     id: string;
   
     @Column({ type: 'varchar', length: 50, nullable: true }) // Vonage Message UUID
     vonageMessageId?: string;
   
     @ManyToOne(() => Campaign, (campaign) => campaign.messageLogs, { onDelete: 'CASCADE' })
     campaign: Campaign;
   
     @ManyToOne(() => Subscriber, { eager: true, onDelete: 'CASCADE' }) // Eager load subscriber for easy access
     subscriber: Subscriber;
   
     @Column({
       type: 'enum',
       enum: MessageStatus,
       default: MessageStatus.PENDING,
     })
     status: MessageStatus;
   
     @Column({ type: 'text', nullable: true })
     errorMessage?: string; // Store error details from Vonage
   
     @CreateDateColumn()
     createdAt: Date; // When we created the log/attempted send
   
     @UpdateDateColumn()
     updatedAt: Date; // When the status was last updated (e.g., via webhook)
   
     @Column({ type: 'timestamp', nullable: true })
     submittedAt?: Date; // Timestamp from Vonage status webhook
   
     @Column({ type: 'timestamp', nullable: true })
     deliveredAt?: Date; // Timestamp from Vonage status webhook
   }
   

3. Configure TypeORM Connection: Update AppModule to configure the database connection using ConfigService.

   File: src/app.module.ts

   typescript

   import { Module } from '@nestjs/common';
   import { ConfigModule, ConfigService } from '@nestjs/config';
   import { TypeOrmModule } from '@nestjs/typeorm';
   import { Subscriber } from './database/entities/subscriber.entity';
   import { Campaign } from './database/entities/campaign.entity';
   import { MessageLog } from './database/entities/message-log.entity';
   // Other imports...
   // Import your feature modules here later
   import { CampaignsModule } from './campaigns/campaigns.module';
   import { SubscribersModule } from './subscribers/subscribers.module';
   import { VonageModule } from './vonage/vonage.module';
   import { WebhooksModule } from './webhooks/webhooks.module';
   import { HealthModule } from './health/health.module';
   import { RateLimiterModule } from 'nestjs-rate-limiter'; // Import RateLimiterModule if used globally
   
   @Module({
     imports: [
       ConfigModule.forRoot({ isGlobal: true, envFilePath: '.env' }),
       TypeOrmModule.forRootAsync({
         imports: [ConfigModule],
         useFactory: (configService: ConfigService) => ({
           type: 'postgres',
           host: configService.get<string&gt;('DATABASE_HOST'),
           port: configService.get<number&gt;('DATABASE_PORT'),
           username: configService.get<string&gt;('DATABASE_USERNAME'),
           password: configService.get<string&gt;('DATABASE_PASSWORD'),
           database: configService.get<string&gt;('DATABASE_NAME'),
           entities: [Subscriber, Campaign, MessageLog],
           synchronize: configService.get<string&gt;('NODE_ENV') !== 'production', // Auto-create schema in dev, use migrations in prod
           logging: configService.get<string&gt;('NODE_ENV') !== 'production',
           // migrations: [__dirname + '/database/migrations/*{.ts,.js}'], // Configure for production
           // cli: { migrationsDir: 'src/database/migrations' }, // Configure for production
         }),
         inject: [ConfigService],
       }),
       // Feature Modules
       CampaignsModule,
       SubscribersModule,
       VonageModule, // Ensure VonageModule is Global or imported where needed
       WebhooksModule,
       HealthModule,
       // RateLimiterModule // Register RateLimiterModule if using it globally
     ],
     // ... controllers/providers if any at root level
   })
   export class AppModule {}
   

   Note: For production, set synchronize: false and use TypeORM migrations. Refer to the NestJS TypeORM documentation for migration setup. For this guide, synchronize: true simplifies local development.

4. Create Modules for Entities: Generate modules and services for Campaigns and Subscribers.

   bash

   nest g module campaigns
   nest g service campaigns
   nest g controller campaigns
   
   nest g module subscribers
   nest g service subscribers
   nest g controller subscribers
   

   Import TypeOrmModule.forFeature([...]) into CampaignsModule and SubscribersModule to inject repositories.

   File: src/campaigns/campaigns.module.ts

   typescript

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   import { CampaignsService } from './campaigns.service';
   import { CampaignsController } from './campaigns.controller';
   import { Campaign } from '../database/entities/campaign.entity';
   import { MessageLog } from '../database/entities/message-log.entity';
   import { Subscriber } from '../database/entities/subscriber.entity'; // Import Subscriber if needed by service
   // VonageModule is Global, so no need to import here unless it wasn't global
   
   @Module({
     imports: [
       TypeOrmModule.forFeature([Campaign, MessageLog, Subscriber]), // Add Subscriber repo if needed
     ],
     controllers: [CampaignsController],
     providers: [CampaignsService],
     exports: [CampaignsService], // Export if needed by other modules
   })
   export class CampaignsModule {}
   

   File: src/subscribers/subscribers.module.ts

   typescript

   import { Module } from '@nestjs/common';
   import { TypeOrmModule } from '@nestjs/typeorm';
   import { SubscribersService } from './subscribers.service';
   import { SubscribersController } from './subscribers.controller';
   import { Subscriber } from '../database/entities/subscriber.entity';
   
   @Module({
     imports: [TypeOrmModule.forFeature([Subscriber])],
     controllers: [SubscribersController],
     providers: [SubscribersService],
     exports: [SubscribersService], // Export if needed by other modules
   })
   export class SubscribersModule {}
   

5. Implementing Core Functionality (Vonage Service & Campaign Sending)

Now, let's integrate the Vonage SDK and implement the logic to send campaign messages.

1. Create Vonage Module & Service: Encapsulate Vonage SDK initialization and interaction.

   bash

   nest g module vonage
   nest g service vonage
   

   File: src/vonage/vonage.service.ts

   typescript

   import { Injectable, Logger, OnModuleInit } from '@nestjs/common';
   import { ConfigService } from '@nestjs/config';
   import { Vonage } from '@vonage/server-sdk';
   import { MessageSendRequest } from '@vonage/messages'; // Import specific types
   import * as fs from 'fs'; // Import fs to read the private key
   import * as path from 'path'; // Import path for resolving paths
   
   @Injectable()
   export class VonageService implements OnModuleInit {
     private readonly logger = new Logger(VonageService.name);
     private vonageClient: Vonage;
     private vonageNumber: string;
   
     constructor(private configService: ConfigService) {}
   
     onModuleInit() {
       const applicationId = this.configService.get<string&gt;('VONAGE_APPLICATION_ID');
       const privateKeyPath = this.configService.get<string&gt;('VONAGE_PRIVATE_KEY_PATH');
       this.vonageNumber = this.configService.get<string&gt;('VONAGE_NUMBER');
   
       if (!applicationId || !privateKeyPath || !this.vonageNumber) {
         this.logger.error('Vonage credentials not configured correctly in .env');
         throw new Error('Vonage credentials missing or invalid.');
       }
   
       try {
         // Resolve path relative to the project root (process.cwd())
         const resolvedPath = path.resolve(process.cwd(), privateKeyPath);
         if (!fs.existsSync(resolvedPath)) {
           throw new Error(`Private key file not found at: ${resolvedPath}`);
         }
         const privateKey = fs.readFileSync(resolvedPath); // Read the key file
   
         this.vonageClient = new Vonage({
           applicationId: applicationId,
           privateKey: privateKey, // Pass the key content
         });
         this.logger.log('Vonage client initialized successfully.');
       } catch (error) {
         this.logger.error(`Failed to initialize Vonage client: ${error.message}`, error.stack);
         throw error; // Prevent application startup if Vonage SDK fails
       }
     }
   
     async sendSms(to: string, text: string): Promise&lt;{ success: boolean; messageId?: string; error?: any }&gt; {
       if (!this.vonageClient) {
           this.logger.error('Vonage client not initialized.');
           return { success: false, error: 'Vonage client not initialized.' };
       }
   
       const messageRequest: MessageSendRequest = {
         message_type: 'text',
         channel: 'sms',
         to: to, // E.164 format
         from: this.vonageNumber, // Your Vonage number
         text: text,
       };
   
       try {
         this.logger.log(`Attempting to send SMS to ${to}`);
         const response = await this.vonageClient.messages.send(messageRequest);
         this.logger.log(`SMS submitted to Vonage for ${to}. Message UUID: ${response.message_uuid}`);
         return { success: true, messageId: response.message_uuid };
       } catch (error) {
         // Log the detailed error from the Vonage SDK
         this.logger.error(`Failed to send SMS to ${to}: ${error?.response?.data?.title || error.message}`, error?.response?.data || error);
         return { success: false, error: error?.response?.data || error };
       }
     }
   
     getClient(): Vonage {
       return this.vonageClient;
     }
   
     // Placeholder for JWT verification - needs implementation
     async verifyWebhookJwt(token: string, rawBody: Buffer): Promise<boolean&gt; {
         this.logger.warn('verifyWebhookJwt method called but not implemented.');
         // Implementation would involve:
         // 1. Getting the public key or secret from config/Vonage settings.
         // 2. Using `this.vonageClient.verifyWebhookJwt` or a similar JWT library.
         // Example using potential SDK method (adjust based on actual SDK capabilities):
         /*
         try {
             // Note: Vonage Messages API webhooks typically use signed requests (HMAC-SHA256)
             // rather than JWTs for the main payload verification.
             // Check Vonage documentation for the correct verification method for Messages API webhooks.
             // If using JWT for authentication *before* processing, the logic would go here.
             // If verifying the signature header:
             // const signatureSecret = this.configService.get<string&gt;('VONAGE_SIGNATURE_SECRET');
             // const isValid = this.vonageClient.messages.verifySignature(token, rawBody, signatureSecret); // Hypothetical method
             // return isValid;
         } catch (err) {
             this.logger.error(`Webhook verification failed: ${err.message}`);
             return false;
         }
         */
        return false; // Return false until implemented correctly
     }
   }
   

   File: src/vonage/vonage.module.ts

   typescript

   import { Module, Global } from '@nestjs/common';
   import { VonageService } from './vonage.service';
   import { ConfigModule } from '@nestjs/config'; // Ensure ConfigModule is available
   
   @Global() // Make VonageService available globally without importing VonageModule everywhere
   @Module({
     imports: [ConfigModule], // VonageService depends on ConfigService
     providers: [VonageService],
     exports: [VonageService],
   })
   export class VonageModule {}
   

   Make sure VonageModule is imported into AppModule's imports array (done in step 4.3).

2. Implement Campaign Sending Logic: Add a method in CampaignsService to fetch subscribers and send messages using VonageService.

   File: src/campaigns/campaigns.service.ts

   typescript

   import { Injectable, Logger, NotFoundException } from '@nestjs/common';
   import { InjectRepository } from '@nestjs/typeorm';
   import { Repository } from 'typeorm';
   import { Campaign, CampaignStatus } from '../database/entities/campaign.entity';
   import { Subscriber, SubscriptionStatus } from '../database/entities/subscriber.entity';
   import { MessageLog, MessageStatus } from '../database/entities/message-log.entity';
   import { VonageService } from '../vonage/vonage.service';
   import { CreateCampaignDto } from './dto/create-campaign.dto'; // Define this DTO later
   
   @Injectable()
   export class CampaignsService {
     private readonly logger = new Logger(CampaignsService.name);
   
     constructor(
       @InjectRepository(Campaign)
       private campaignsRepository: Repository<Campaign&gt;,
       @InjectRepository(Subscriber)
       private subscribersRepository: Repository<Subscriber&gt;,
       @InjectRepository(MessageLog)
       private messageLogRepository: Repository<MessageLog&gt;,
       // VonageService is injected because VonageModule is Global
       private vonageService: VonageService,
     ) {}
   
     async create(createCampaignDto: CreateCampaignDto): Promise<Campaign&gt; {
       const campaign = this.campaignsRepository.create(createCampaignDto);
       campaign.status = CampaignStatus.DRAFT;
       return this.campaignsRepository.save(campaign);
     }
   
     findAll(): Promise<Campaign[]&gt; {
       return this.campaignsRepository.find();
     }
   
     async findOne(id: string): Promise<Campaign&gt; {
       const campaign = await this.campaignsRepository.findOne({ where: { id } });
       if (!campaign) {
         // Corrected template literal usage
         throw new NotFoundException(`Campaign with ID "${id}" not found`);
       }
       return campaign;
     }
   
     async sendCampaign(campaignId: string): Promise<void&gt; {
       const campaign = await this.findOne(campaignId);
       if (campaign.status !== CampaignStatus.DRAFT && campaign.status !== CampaignStatus.FAILED) {
           this.logger.warn(`Campaign ${campaignId} is not in DRAFT or FAILED status. Current status: ${campaign.status}`);
           // Optionally throw an error or just return
           return;
       }
   
       // Find subscribed users
       const subscribers = await this.subscribersRepository.find({
           where: { status: SubscriptionStatus.SUBSCRIBED },
       });
   
       if (subscribers.length === 0) {
           this.logger.warn(`No subscribed users found for campaign ${campaignId}.`);
           campaign.status = CampaignStatus.FAILED; // Or SENT if technically no messages needed sending
           campaign.sentAt = new Date();
           await this.campaignsRepository.save(campaign);
           return;
       }
   
       this.logger.log(`Starting campaign ${campaignId} (${campaign.name}) for ${subscribers.length} subscribers.`);
       campaign.status = CampaignStatus.SENDING;
       await this.campaignsRepository.save(campaign);
   
       let successCount = 0;
       let failureCount = 0;
   
       // --- Simple Sequential Sending (See Performance section for improvements) ---
       for (const subscriber of subscribers) {
           // Simple check to avoid sending to unsubscribed (though filtered above, good practice)
           if (subscriber.status !== SubscriptionStatus.SUBSCRIBED) {
               this.logger.warn(`Skipping unsubscribed user ${subscriber.phoneNumber} for campaign ${campaignId}`);
               continue;
           }
   
           const messageLog = this.messageLogRepository.create({
               campaign: campaign,
               subscriber: subscriber,
               status: MessageStatus.PENDING,
           });
           await this.messageLogRepository.save(messageLog); // Save log before sending
   
           try {
               // Basic placeholder substitution (replace with a more robust method if needed)
               const personalizedMessage = campaign.messageTemplate
                   .replace('{firstName}', subscriber.firstName || '')
                   .replace('{lastName}', subscriber.lastName || '')
                   .trim();
   
               const result = await this.vonageService.sendSms(
                   subscriber.phoneNumber,
                   personalizedMessage,
               );
   
               if (result.success && result.messageId) {
                   messageLog.status = MessageStatus.SUBMITTED;
                   messageLog.vonageMessageId = result.messageId;
                   messageLog.submittedAt = new Date();
                   successCount++;
               } else {
                   messageLog.status = MessageStatus.FAILED;
                   messageLog.errorMessage = JSON.stringify(result.error || 'Unknown error during submission');
                   failureCount++;
               }
           } catch (error) {
               this.logger.error(`Critical error sending to ${subscriber.phoneNumber}: ${error.message}`, error.stack);
               messageLog.status = MessageStatus.FAILED;
               messageLog.errorMessage = `Internal error: ${error.message}`;
               failureCount++;
           }
           await this.messageLogRepository.save(messageLog); // Update log with status and messageId/error
   
           // Basic rate limiting - Vonage default is often 1 SMS/sec for long codes
           // Consider making the delay configurable or using a more sophisticated queue/batching system
           await new Promise(resolve =&gt; setTimeout(resolve, 1100)); // ~1.1 second delay
       }
       // --- End Simple Sequential Sending ---
   
   
       campaign.status = failureCount &gt; 0 ? CampaignStatus.FAILED : CampaignStatus.SENT; // Mark SENT only if all submitted successfully
       campaign.sentAt = new Date();
       await this.campaignsRepository.save(campaign);
   
       this.logger.log(`Campaign ${campaignId} finished. Submitted: ${successCount}, Failed: ${failureCount}`);
     }
   
     // ... other methods (update, delete)
   }
   

6. Building the API Layer (Controllers and DTOs)

Expose endpoints to manage campaigns and subscribers.

1. Define Data Transfer Objects (DTOs) with Validation: Use class-validator decorators for robust input validation.

   File: src/subscribers/dto/create-subscriber.dto.ts

   typescript

   import { IsString, IsNotEmpty, IsPhoneNumber, IsOptional, MaxLength } from 'class-validator';
   
   export class CreateSubscriberDto {
     @IsNotEmpty()
     @IsPhoneNumber(null) // Use null for international format validation (e.g., +14155550100)
     @MaxLength(20)
     phoneNumber: string;
   
     @IsOptional()
     @IsString()
     @MaxLength(100)
     firstName?: string;
   
     @IsOptional()
     @IsString()
     @MaxLength(100)
     lastName?: string;
   }
   

   File: src/campaigns/dto/create-campaign.dto.ts

   typescript

   import { IsString, IsNotEmpty, MinLength, MaxLength, IsOptional, IsDateString } from 'class-validator';
   
   export class CreateCampaignDto {
     @IsNotEmpty()
     @IsString()
     @MinLength(3)
     @MaxLength(255)
     name: string;
   
     @IsNotEmpty()
     @IsString()
     @MinLength(10)
     messageTemplate: string;
   
     @IsOptional()
     @IsDateString()
     scheduledAt?: string; // ISO 8601 date string
   }
   

2. Implement Controllers: Create endpoints using the services and DTOs. Ensure ValidationPipe is enabled globally.

   File: src/main.ts

   typescript

   import { NestFactory } from '@nestjs/core';
   import { AppModule } from './app.module';
   import { Logger, ValidationPipe } from '@nestjs/common';
   import { ConfigService } from '@nestjs/config';
   import helmet from 'helmet'; // Import helmet
   import { NestExpressApplication } from '@nestjs/platform-express'; // Import this for rawBody option
   import * as bodyParser from 'body-parser'; // Import body-parser
   
   async function bootstrap() {
     // Specify NestExpressApplication for access to Express-specific options like bodyParser
     const app = await NestFactory.create<NestExpressApplication&gt;(AppModule, {
       // Enable bodyParser to access raw request body for webhook verification
       bodyParser: false, // Disable NestJS default body parsing temporarily
     });
   
     const configService = app.get(ConfigService);
     const port = configService.get<number&gt;('PORT') || 3000;
     const nodeEnv = configService.get<string&gt;('NODE_ENV');
   
     // Apply Helmet middleware for security headers
     app.use(helmet());
   
     // Enable CORS if your frontend/API clients are on different origins
     app.enableCors(); // Configure origins appropriately for production
   
     // Re-enable JSON body parsing for regular routes, keeping raw body for specific routes
     // Parse JSON bodies
     app.use(bodyParser.json());
     // Parse URL-encoded bodies
     app.use(bodyParser.urlencoded({ extended: true }));
     // Crucially, parse raw body specifically for webhook routes *before* JSON/URL parsing if needed
     // This setup assumes webhooks might need raw body, other routes need parsed body.
     // A more robust approach might involve applying raw body parsing only to webhook routes.
     // Example: app.use('/webhooks', bodyParser.raw({ type: 'application/json' }));
     // For simplicity here, we rely on accessing it if bodyParser hasn't consumed it.
     // NestJS's built-in `rawBody: true` in `NestFactory.create` is often simpler if applicable globally.
     // Let's revert to the simpler NestJS way if it works for Vonage webhooks:
     // Remove `bodyParser: false` from create options.
     // Remove `app.use(bodyParser...)` lines.
     // Add `rawBody: true` to NestFactory.create options:
     // const app = await NestFactory.create<NestExpressApplication&gt;(AppModule, { rawBody: true });
   
     // Use global validation pipe
     app.useGlobalPipes(new ValidationPipe({
       whitelist: true, // Strip properties not defined in DTO
       transform: true, // Automatically transform payloads to DTO instances
       forbidNonWhitelisted: true, // Throw error if non-whitelisted properties are present
     }));
   
     await app.listen(port);
     Logger.log(`🚀 Application is running on: http://localhost:${port} in ${nodeEnv} mode`, 'Bootstrap');
     Logger.log(`📄 Swagger UI available at http://localhost:${port}/api`, 'Bootstrap'); // If Swagger is setup
   }
   bootstrap();
   

   (Note: The main.ts example above shows how to handle rawBody for webhooks. Ensure your final implementation correctly provides the raw body to your webhook verification logic, potentially using NestFactory.create(AppModule, { rawBody: true }) and accessing req.rawBody in the controller, or using middleware as shown.)

   (Implement SubscribersController and CampaignsController with appropriate methods using @Get, @Post, @Param, @Body, etc., calling the respective service methods and using the DTOs.)