Build a Bulk SMS System with MessageBird and NestJS (2025 Guide) - SMS Development - MessageBird, NestJS, TypeScript, Bulk SMS, API Integration, Prisma, Node.js

Build a Bulk SMS Broadcasting System with MessageBird and NestJS

Bulk SMS broadcasting lets you send promotional campaigns, alerts, or notifications to thousands of recipients efficiently. This guide shows you how to build a production-ready bulk SMS system using MessageBird's SMS API and NestJS.

Important Note: MessageBird's standard /messages API endpoint accepts a maximum of 50 recipients per request according to their official documentation. For larger volumes, you'll need to batch requests on the application side or verify with MessageBird support about enterprise batch endpoints. Always consult the latest MessageBird API documentation for current limits and features.

What You'll Build with MessageBird and NestJS

By the end of this tutorial, you'll have a NestJS application that:

  • Accepts bulk SMS requests through a REST API
  • Validates phone numbers in E.164 format
  • Processes messages in batches through MessageBird's SMS API (max 50 recipients per request)
  • Handles rate limiting with exponential backoff retry logic
  • Tracks delivery status for each message
  • Stores campaign history in a PostgreSQL database via Prisma

Prerequisites for MessageBird NestJS Integration

Before you begin, ensure you have:

  • Node.js (v18 LTS or later recommended) and npm/pnpm/yarn installed.
  • A MessageBird account with an active API key. Sign up at MessageBird if you don't have one.
  • PostgreSQL installed locally or access to a hosted instance (e.g., Supabase, Neon, or Railway).
  • Basic familiarity with NestJS, TypeScript, and REST APIs.

Step 1: Set Up Your NestJS Project for MessageBird Integration

Create a new NestJS project:

bash
nest new nestjs-messagebird-bulk
cd nestjs-messagebird-bulk

Install the required dependencies:

bash
npm install @nestjs/config @nestjs/axios @nestjs/throttler @prisma/client axios
npm install -D prisma

Dependency breakdown:

  • @nestjs/config – Manages environment variables
  • @nestjs/axios – HTTP client module for MessageBird API calls
  • @nestjs/throttler – Rate limiting to prevent API abuse
  • @prisma/client and prisma – Database ORM for PostgreSQL
  • axios – HTTP library (peer dependency for @nestjs/axios)

Step 2: Configure MessageBird API Environment Variables

Create a .env file in your project root:

bash
# MessageBird API Configuration
MESSAGEBIRD_API_KEY=your_messagebird_api_key_here
MESSAGEBIRD_API_BASE_URL=https://rest.messagebird.com

# Database Configuration
DATABASE_URL="postgresql://user:password@localhost:5432/sms_db?schema=public"

# Application Settings
PORT=3000
NODE_ENV=development

Replace your_messagebird_api_key_here with your actual MessageBird API key from the MessageBird Dashboard.

Update src/app.module.ts to load environment variables:

typescript
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ThrottlerModule } from '@nestjs/throttler';
import { PrismaModule } from './prisma/prisma.module';
import { SmsModule } from './sms/sms.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    ThrottlerModule.forRoot([{
      ttl: 60000, // 60 seconds
      limit: 10,  // 10 requests per minute
    }]),
    PrismaModule,
    SmsModule,
  ],
})
export class AppModule {}

Step 3: Set Up Prisma Database Schema for SMS Campaign Tracking

Initialize Prisma:

bash
npx prisma init

This command creates a prisma directory with a schema.prisma file. Update it to define your SMS campaign and message models:

sql
model SmsCampaign {
  id              Int      @id @default(autoincrement())
  name            String
  totalMessages   Int      @default(0)
  successCount    Int      @default(0)
  failureCount    Int      @default(0)
  createdAt       DateTime @default(now())
  updatedAt       DateTime @updatedAt
  messages        SmsMessage[]
}

model SmsMessage {
  id                    Int      @id @default(autoincrement())
  campaignId            Int
  campaign              SmsCampaign @relation(fields: [campaignId], references: [id])
  recipient             String
  originator            String
  body                  String
  status                String
  messageBirdResponse   Json?
  errorMessage          String?
  createdAt             DateTime @default(now())
  updatedAt             DateTime @updatedAt
}

Schema explanation:

  • SmsCampaign – Stores campaign metadata, total message count, and success/failure tallies
  • SmsMessage – Tracks individual messages with recipient, status, and MessageBird response data
  • Relations connect campaigns to their messages via campaignId

Generate the Prisma client and run migrations:

bash
npx prisma generate
npx prisma migrate dev --name init

Step 4: Create DTOs for MessageBird SMS Request Validation

NestJS uses Data Transfer Objects (DTOs) with class-validator decorators to validate incoming requests.

Create src/sms/dto/create-bulk-sms.dto.ts:

typescript
import { IsString, IsNotEmpty, IsArray, ArrayNotEmpty, ArrayMaxSize, ValidateNested, Matches, MaxLength } from 'class-validator';
import { Type } from 'class-transformer';

class MessageDto {
  @IsArray()
  @ArrayNotEmpty({ message: 'Recipients array cannot be empty.' })
  @ArrayMaxSize(50, { message: 'Cannot process more than 50 messages per batch request due to MessageBird API limits.' })
  @IsString({ each: true })
  @Matches(/^\+[1-9]\d{1,14}$/, { each: true, message: 'Each recipient must be in E.164 format (e.g., +14155552671).' })
  recipients: string[];

  @IsString()
  @IsNotEmpty({ message: 'Originator (sender ID) is required.' })
  @MaxLength(11, { message: 'Originator cannot exceed 11 characters.' })
  originator: string;

  @IsString()
  @IsNotEmpty({ message: 'Message body is required.' })
  @MaxLength(1600, { message: 'Message body cannot exceed 1600 characters (10 concatenated SMS segments).' })
  body: string;
}

export class CreateBulkSmsDto {
  @IsString()
  @IsNotEmpty({ message: 'Campaign name is required.' })
  campaignName: string;

  @IsArray()
  @ArrayNotEmpty({ message: 'Messages array cannot be empty.' })
  @ValidateNested({ each: true })
  @Type(() => MessageDto)
  messages: MessageDto[];
}

Key validations:

  • E.164 format – Ensures phone numbers include country code (e.g., +14155552671)
  • 50 recipients max – Matches MessageBird's standard API limit per request
  • Originator length – Alphanumeric sender IDs max 11 characters; numeric max 16 digits
  • Message length – Allows up to 10 concatenated SMS segments (160 chars × 10 = 1600 chars)

Step 5: Build the MessageBird SMS Service with Retry Logic

Create src/sms/sms.service.ts to handle MessageBird API interactions, retry logic, and database persistence:

typescript
import { Injectable, Logger, HttpException, HttpStatus } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { HttpService } from '@nestjs/axios';
import { PrismaService } from '../prisma/prisma.service';
import { CreateBulkSmsDto } from './dto/create-bulk-sms.dto';
import { firstValueFrom } from 'rxjs';
import { AxiosError } from 'axios';

interface MessageBirdResponseItem {
  recipients: string[];
  originator: string;
  body: string;
  messageId?: string;
  status?: string;
  error?: string;
}

@Injectable()
export class SmsService {
  private readonly logger = new Logger(SmsService.name);
  private readonly apiKey: string;
  private readonly baseUrl: string;
  private readonly messageApiEndpoint = '/messages';
  private readonly maxRetries = 3;
  private readonly retryDelayMs = 1000;

  constructor(
    private readonly configService: ConfigService,
    private readonly httpService: HttpService,
    private readonly prisma: PrismaService,
  ) {
    this.apiKey = this.configService.get<string&gt;('MESSAGEBIRD_API_KEY');
    this.baseUrl = this.configService.get<string&gt;('MESSAGEBIRD_API_BASE_URL', 'https://rest.messagebird.com');

    if (!this.apiKey) {
      throw new Error('MESSAGEBIRD_API_KEY is not configured. Check your .env file.');
    }
  }

  async sendBulkSms(createBulkSmsDto: CreateBulkSmsDto) {
    const { campaignName, messages } = createBulkSmsDto;

    // Create campaign record
    const campaign = await this.prisma.smsCampaign.create({
      data: {
        name: campaignName,
        totalMessages: messages.reduce((sum, msg) =&gt; sum + msg.recipients.length, 0),
      },
    });

    this.logger.log(`Created campaign: ${campaign.name} (ID: ${campaign.id})`);

    // Process messages with retry logic
    const results: MessageBirdResponseItem[] = [];

    for (const message of messages) {
      const payload = {
        recipients: message.recipients,
        originator: message.originator,
        body: message.body,
      };

      try {
        const response = await this.sendWithRetry(payload);
        results.push({
          ...message,
          messageId: response.id,
          status: 'sent',
        });

        // Store successful messages in database
        await this.storeMessages(campaign.id, message.recipients, message.originator, message.body, 'sent', response);
      } catch (error) {
        this.logger.error(`Failed to send message after ${this.maxRetries} retries:`, error);
        results.push({
          ...message,
          status: 'failed',
          error: error.message,
        });

        // Store failed messages
        await this.storeMessages(campaign.id, message.recipients, message.originator, message.body, 'failed', null, error.message);
      }
    }

    // Update campaign statistics
    const successCount = results.filter((r) =&gt; r.status === 'sent').length;
    const failureCount = results.filter((r) =&gt; r.status === 'failed').length;

    await this.prisma.smsCampaign.update({
      where: { id: campaign.id },
      data: {
        successCount,
        failureCount,
      },
    });

    return {
      campaignId: campaign.id,
      totalMessages: messages.length,
      successCount,
      failureCount,
      results,
    };
  }

  private async sendWithRetry(payload: any, attempt = 1): Promise<any&gt; {
    try {
      const response = await firstValueFrom(
        this.httpService.post(`${this.baseUrl}${this.messageApiEndpoint}`, payload, {
          headers: {
            'Authorization': `AccessKey ${this.apiKey}`,
            'Content-Type': 'application/json',
          },
        }),
      );

      return response.data;
    } catch (error) {
      const axiosError = error as AxiosError;
      const statusCode = axiosError.response?.status;

      // Retry on rate limit (429) or server errors (5xx)
      let shouldRetry = false;
      if (!statusCode || statusCode === 429 || (statusCode &gt;= 500 && statusCode &lt;= 599)) {
        shouldRetry = true;
      }

      if (shouldRetry && attempt &lt; this.maxRetries) {
        const delay = this.retryDelayMs * Math.pow(2_ attempt - 1); // Exponential backoff
        this.logger.warn(`Retry attempt ${attempt}/${this.maxRetries} after ${delay}ms due to status ${statusCode || 'network error'}`);
        await this.sleep(delay);
        return this.sendWithRetry(payload_ attempt + 1);
      }

      // Exhausted retries or non-retriable error
      this.logger.error(`MessageBird API error: ${axiosError.message}`_ axiosError.response?.data);
      throw new HttpException(
        axiosError.response?.data || 'Failed to send SMS via MessageBird'_
        statusCode || HttpStatus.INTERNAL_SERVER_ERROR_
      );
    }
  }

  private async storeMessages(
    campaignId: number_
    recipients: string[]_
    originator: string_
    body: string_
    status: string_
    response?: any_
    error?: string_
  ) {
    const messageData = recipients.map((recipient) =&gt; ({
      campaignId,
      recipient,
      originator,
      body,
      status,
      messageBirdResponse: response ? JSON.stringify(response) : null,
      errorMessage: error || null,
    }));

    await this.prisma.smsMessage.createMany({ data: messageData });
  }

  private sleep(ms: number): Promise<void&gt; {
    return new Promise((resolve) =&gt; setTimeout(resolve, ms));
  }

  async getCampaignStatus(campaignId: number) {
    const campaign = await this.prisma.smsCampaign.findUnique({
      where: { id: campaignId },
      include: { messages: true },
    });

    if (!campaign) {
      throw new HttpException('Campaign not found', HttpStatus.NOT_FOUND);
    }

    return campaign;
  }
}

Key features:

  • Exponential backoff – Retries failed requests with increasing delays (1s, 2s, 4s)
  • Rate limit handling – Detects 429 status codes and retries automatically (MessageBird rate limit: 500 POST requests/second per official documentation)
  • Comprehensive logging – Tracks each API call for debugging
  • Database persistence – Stores all messages with status and error details

Step 6: Create the NestJS SMS Controller with Rate Limiting

Create src/sms/sms.controller.ts to expose REST endpoints:

typescript
import { Controller, Post, Get, Body, Param, ParseIntPipe, UseGuards } from '@nestjs/common';
import { ThrottlerGuard } from '@nestjs/throttler';
import { SmsService } from './sms.service';
import { CreateBulkSmsDto } from './dto/create-bulk-sms.dto';

@Controller('sms')
@UseGuards(ThrottlerGuard) // Rate limiting: 10 requests per minute by default
export class SmsController {
  constructor(private readonly smsService: SmsService) {}

  @Post('bulk')
  async sendBulkSms(@Body() createBulkSmsDto: CreateBulkSmsDto) {
    return this.smsService.sendBulkSms(createBulkSmsDto);
  }

  @Get('campaign/:id')
  async getCampaignStatus(@Param('id', ParseIntPipe) id: number) {
    return this.smsService.getCampaignStatus(id);
  }
}

Step 7: Create the Prisma Service Module

Create src/prisma/prisma.service.ts:

typescript
import { Injectable, OnModuleInit, OnModuleDestroy } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    await this.$connect();
  }

  async onModuleDestroy() {
    await this.$disconnect();
  }
}

Create src/prisma/prisma.module.ts:

typescript
import { Module, Global } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Global()
@Module({
  providers: [PrismaService],
  exports: [PrismaService],
})
export class PrismaModule {}

Step 8: Wire Up the SMS Module

Create src/sms/sms.module.ts:

typescript
import { Module } from '@nestjs/common';
import { HttpModule } from '@nestjs/axios';
import { SmsService } from './sms.service';
import { SmsController } from './sms.controller';

@Module({
  imports: [HttpModule],
  controllers: [SmsController],
  providers: [SmsService],
})
export class SmsModule {}

Update src/app.module.ts:

typescript
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { ThrottlerModule } from '@nestjs/throttler';
import { PrismaModule } from './prisma/prisma.module';
import { SmsModule } from './sms/sms.module';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    ThrottlerModule.forRoot([{
      ttl: 60000, // 60 seconds
      limit: 10,  // 10 requests per minute
    }]),
    PrismaModule,
    SmsModule,
  ],
})
export class AppModule {}

Step 9: Test Your MessageBird Bulk SMS Integration

Start your NestJS application:

bash
npm run start:dev

Send a test bulk SMS request:

bash
curl -X POST http://localhost:3000/sms/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "campaignName": "Black Friday Sale",
    "messages": [
      {
        "recipients": ["+14155552671", "+14155552672"],
        "originator": "YourBrand",
        "body": "Get 50% off everything! Use code BF2025. Shop now: https://yourbrand.com"
      },
      {
        "recipients": ["+442071234567"],
        "originator": "YourBrand",
        "body": "Exclusive UK offer: Free shipping on all orders today!"
      }
    ]
  }'

Expected response:

json
{
  "campaignId": 1,
  "totalMessages": 2,
  "successCount": 2,
  "failureCount": 0,
  "results": [
    {
      "recipients": ["+14155552671", "+14155552672"],
      "originator": "YourBrand",
      "body": "Get 50% off everything!...",
      "messageId": "abc123def456",
      "status": "sent"
    },
    {
      "recipients": ["+442071234567"],
      "originator": "YourBrand",
      "body": "Exclusive UK offer...",
      "messageId": "xyz789ghi012",
      "status": "sent"
    }
  ]
}

Check campaign status:

bash
curl http://localhost:3000/sms/campaign/1

Production Considerations for MessageBird SMS at Scale

1. Environment Variables Security

Store sensitive credentials securely:

  • Use environment variable management services (AWS Secrets Manager, HashiCorp Vault)
  • Never commit .env files to version control
  • Rotate API keys regularly

2. Rate Limiting Strategy

MessageBird enforces API rate limits (500 POST requests/second per official documentation). Implement application-level rate limiting:

typescript
ThrottlerModule.forRoot([{
  ttl: 60000,  // 1 minute window
  limit: 100,  // 100 requests per minute per IP
}])

For high-volume campaigns, use a queue system (BullMQ, AWS SQS) to throttle requests.

3. Message Queuing for Large Campaigns

For campaigns exceeding 10,000 messages, integrate a job queue:

bash
npm install @nestjs/bull bull

Update sms.service.ts to queue messages:

typescript
import { InjectQueue } from '@nestjs/bull';
import { Queue } from 'bull';

@Injectable()
export class SmsService {
  constructor(@InjectQueue('sms') private smsQueue: Queue) {}

  async sendBulkSms(dto: CreateBulkSmsDto) {
    for (const message of dto.messages) {
      await this.smsQueue.add('send-sms', message, {
        attempts: 3,
        backoff: { type: 'exponential', delay: 2000 },
      });
    }
  }
}

4. Monitoring and Logging

Integrate application performance monitoring (APM):

  • Sentry – Track errors and failed API calls
  • DataDog – Monitor request rates and latency
  • Prometheus + Grafana – Visualize campaign metrics

Add structured logging:

typescript
this.logger.log({
  event: 'bulk_sms_sent',
  campaignId: campaign.id,
  successCount,
  failureCount,
  timestamp: new Date().toISOString(),
});

Ensure legal compliance:

  • GDPR (EU) – Obtain explicit consent before sending promotional messages
  • TCPA (USA) – Maintain opt-in records for marketing messages
  • CASL (Canada) – Include unsubscribe mechanisms in all commercial messages

Store consent timestamps in your database:

sql
model Subscriber {
  id            Int      @id @default(autoincrement())
  phoneNumber   String   @unique
  consentedAt   DateTime
  optedOutAt    DateTime?
}

6. Cost Optimization

MessageBird charges per message segment:

  • GSM-7 encoding – 160 characters per segment
  • UCS-2 (Unicode) – 70 characters per segment

Optimize message length:

typescript
function calculateSegments(body: string): number {
  const isUnicode = /[^\x00-\x7F]/.test(body);
  const maxLength = isUnicode ? 70 : 160;
  return Math.ceil(body.length / maxLength);
}

Display segment count in your API response to help users optimize costs.

Troubleshooting MessageBird NestJS Integration Issues

1. "Invalid phone number format" Error

Cause: Phone numbers must be in E.164 format (+[country code][number]).

Fix: Validate numbers before sending:

typescript
import { parsePhoneNumber } from 'libphonenumber-js';

function validateE164(phone: string): boolean {
  try {
    const parsed = parsePhoneNumber(phone);
    return parsed.isValid() && parsed.format('E.164') === phone;
  } catch {
    return false;
  }
}

2. Rate Limit 429 Errors

Cause: Exceeding MessageBird's rate limits (500 POST requests/second).

Fix: Implement exponential backoff (already included in the service above) or use a queue system to throttle requests.

3. Messages Not Delivering

Possible causes:

  • Recipient opted out or blocked your sender ID
  • Invalid recipient number
  • MessageBird account balance depleted

Debug steps:

  1. Check MessageBird Dashboard for delivery reports
  2. Verify sender ID registration (some countries require pre-registration)
  3. Test with a known working number

4. Database Connection Issues

Cause: Incorrect DATABASE_URL in .env file.

Fix: Verify PostgreSQL connection string format:

bash
DATABASE_URL="postgresql://username:password@localhost:5432/database_name?schema=public"

Test connection:

bash
npx prisma db push

Frequently Asked Questions (FAQ)

How many recipients can I send to in a single MessageBird API request?

MessageBird's standard /messages endpoint accepts a maximum of 50 recipients per request according to their official documentation. For campaigns exceeding 50 recipients, you'll need to batch requests on the application side (as demonstrated in this tutorial) or contact MessageBird support about enterprise batch endpoints. The code example above automatically handles batching by looping through messages.

What is MessageBird's rate limit for SMS API requests?

MessageBird enforces a rate limit of 500 POST requests per second for SMS messaging according to their official documentation. The NestJS service in this tutorial includes exponential backoff retry logic to handle 429 (rate limit) errors automatically. For high-volume campaigns, implement a queue system like BullMQ to throttle requests and stay within limits.

How do I handle MessageBird API failures and retry logic in NestJS?

The tutorial's SmsService includes a sendWithRetry() method with exponential backoff. It automatically retries failed requests up to 3 times with increasing delays (1s, 2s, 4s). The service retries on 429 (rate limit) and 5xx (server error) status codes. All failed messages are logged to the database with error details for monitoring.

What database schema do I need for MessageBird bulk SMS campaigns?

The Prisma schema includes two models: SmsCampaign (stores campaign metadata, success/failure counts) and SmsMessage (tracks individual messages with recipient, status, and MessageBird response data). This schema enables campaign tracking, delivery reports, and historical analytics. Run npx prisma migrate dev to create the tables.

How do I validate phone numbers for MessageBird SMS API?

MessageBird requires phone numbers in E.164 format (e.g., +14155552671). The tutorial uses class-validator with a regex pattern /^\+[1-9]\d&#123;1,14&#125;$/ to validate E.164 format. For production, consider using libphonenumber-js library for more robust validation including country code verification and number type detection.

Can I send Unicode (emoji) messages through MessageBird?

Yes, MessageBird supports Unicode messages using UCS-2 encoding. However, Unicode messages have a reduced character limit of 70 characters per segment (vs. 160 for GSM-7). The tutorial's DTO allows up to 1,600 characters (10 concatenated segments). Calculate costs carefully – Unicode messages consume more segments and cost more.

How do I implement MessageBird delivery status webhooks in NestJS?

Create a new controller endpoint to receive MessageBird delivery reports. Configure the webhook URL in your MessageBird dashboard under "Developers > Webhooks." MessageBird sends POST requests with delivery status updates (delivered, failed, expired). Parse the webhook payload and update your SmsMessage records in the database accordingly.

What NestJS modules do I need for MessageBird SMS integration?

The core dependencies are: @nestjs/config (environment variables), @nestjs/axios (HTTP client for MessageBird API), @nestjs/throttler (rate limiting), @prisma/client (database ORM), and axios (HTTP library). Install with npm install @nestjs/config @nestjs/axios @nestjs/throttler @prisma/client axios. Additionally, install prisma as a dev dependency for schema management.

Next Steps: Enhance Your MessageBird NestJS SMS System

Now that you have a working bulk SMS system, consider these enhancements:

  1. Delivery Webhooks – Implement MessageBird delivery status webhooks to track real-time message delivery
  2. Scheduled Campaigns – Use BullMQ's delayed jobs to schedule campaigns for future dates
  3. A/B Testing – Split campaigns into variants and track performance metrics
  4. Unsubscribe Management – Build an opt-out system compliant with GDPR/TCPA
  5. Template System – Create reusable message templates with variable placeholders
  6. Multi-Channel Support – Extend your system to support WhatsApp, RCS, and email

Additional Resources

Related Guides:

Frequently Asked Questions

Use NestJS with MessageBird's Batch SMS API. Create a NestJS service to interact with the API, define DTOs for validation, and set up a controller endpoint to handle requests. This allows sending multiple messages in a single API call, improving efficiency for large-scale SMS needs.

MessageBird's Batch SMS API lets you send many unique SMS messages to different people with one API request. This is far more efficient than sending individual messages, especially for large volumes, and is ideal for applications needing notifications, alerts, or marketing outreach.

NestJS provides a robust framework with features like dependency injection, modularity, and TypeScript support, making it suitable for building scalable applications. This structure simplifies integrating third-party services like MessageBird and managing complex logic for reliable bulk SMS sending.

Install the required packages, including @nestjs/axios, messagebird, and @nestjs/config, then create a messaging module and service. In the module, use HttpModule.registerAsync with ConfigService to inject your API key and endpoint from environment variables for secure configuration.

Prisma is used as an Object-Relational Mapper (ORM) to simplify database interactions. It makes it easier to log bulk SMS requests, responses, and other relevant data, improving tracking and monitoring capabilities within your NestJS application.

Create a .env file in your project root. Add MESSAGEBIRD_ACCESS_KEY (your API key from the MessageBird dashboard) and MESSAGEBIRD_API_ENDPOINT. The project uses @nestjs/config to load these variables, and it's crucial to add .env to your .gitignore file to prevent exposing your credentials.

The @nestjs/throttler package helps prevent abuse and overload by limiting API requests. In this bulk SMS system, it protects the MessageBird API from excessive calls, ensuring service stability and preventing potential issues due to rate limits.

The endpoint (POST /messages/bulk) expects a JSON object with a "messages" array. Each element in this array represents an individual message with "recipients", "originator", and "body" properties. Validation is handled by DTOs to ensure correct data format and prevent invalid requests.

It's critical to secure this endpoint using API keys, JWT, or other authentication methods. An API key guard is recommended to control access and prevent unauthorized usage of the endpoint in a real-world application.

The MessagingService implements retry logic with exponential backoff for transient errors (5xx status codes). It throws HttpExceptions for both retryable and non-retryable errors. The controller catches these exceptions and returns appropriate error responses to the client.

You'll need Node.js v16+, npm/pnpm/yarn, a MessageBird account and API key, a PostgreSQL database (or other Prisma-supported database), and basic knowledge of NestJS, TypeScript, and REST APIs. The guide provides instructions for setting up the project, dependencies, and configuration.

The BulkMessagesDto validates incoming requests to ensure no more than 100 messages are included per batch request. This limit aligns with typical API constraints and helps manage resource usage and response times.

Use the test API key from your MessageBird dashboard during development to avoid sending real messages and incurring costs. Switch to the live API key for production when you're ready to send actual bulk SMS messages.

The provided code includes a simplified response interface. Refer to the official MessageBird API documentation for the complete response structure and handle different status codes and fields accordingly in your application.

Yes, you can customize the API endpoint by setting the MESSAGEBIRD_API_ENDPOINT environment variable. The default is https://rest.messagebird.com, but you might need to change it if you are using a different MessageBird environment or region.