[User/Client] ----(HTTP POST Request)----> [Next.js API Route (/api/broadcast)]
      |                                             |
      |                                             | 1. Validates Request
      |                                             | 2. Iterates recipient list
      |                                             | 3. For each recipient:
      |                                             |    - Calls Twilio API (messages.create)
      |                                             |      using Messaging Service SID
      |<----(HTTP Response - Success/Failure)-------|
      |
      |                                [Twilio Platform] <----(API Call)---- |
      |                                     |
      |                                     | Queues & Sends SMS via Messaging Service
      |                                     | (Handles sender selection_ rate limits_ etc.)
      |                                     |
      |                                     v
      |                              [Carrier Networks] ----> [Recipient Phone]
      |
      |                                     |
      |                                     | Status Update (sent, delivered, failed, etc.)
      |<----(Webhook POST Request)----------| ----(Configured Callback URL)----> [Next.js API Route (/api/webhooks/twilio)]
                                                                                    |
                                                                                    | Processes status update
                                                                                    | (e.g., logs, updates DB)

npx create-next-app@latest twilio-bulk-sms
# When prompted:
# > Would you like to use TypeScript? Yes
# > Would you like to use ESLint? Yes
# > Would you like to use Tailwind CSS? Yes
# > Would you like to use `src/` directory? No (or Yes, adjust paths accordingly)
# > Would you like to use App Router? (recommended) Yes
# > Would you like to customize the default import alias? No

cd twilio-bulk-sms

npm install twilio prisma @prisma/client zod

npx prisma init --datasource-provider postgresql

# .env

# Database Connection (replace placeholder with your actual connection string)
# Example format: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public
DATABASE_URL="postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public"

# Twilio Credentials (Obtain from Twilio Console: Account > API keys & tokens)
TWILIO_ACCOUNT_SID="ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TWILIO_AUTH_TOKEN="your_auth_token_xxxxxxxxxxxxxx"

# Twilio Messaging Service SID (Create in Twilio Console: Messaging > Services)
TWILIO_MESSAGING_SERVICE_SID="MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Secret key for securing the broadcast API endpoint
API_SECRET_KEY="generate_a_strong_random_secret_key"

# Public URL of your application (used for webhook callback)
# Example: http://localhost:3000 for local dev, https://your-app.vercel.app for production
NEXT_PUBLIC_APP_URL="http://localhost:3000"

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

// Optional: Model to store recipient details if managing lists within the app
// model Recipient {
//   id          String    @id @default(cuid())
//   phoneNumber String    @unique // Store in E.164 format e.g., +14155552671
//   name        String?
//   optedIn     Boolean   @default(true)
//   createdAt   DateTime  @default(now())
//   updatedAt   DateTime  @updatedAt
// }

model Broadcast {
  id             String          @id @default(cuid())
  messageBody    String
  recipientCount Int
  status         String          @default("initiated") // e.g., initiated, processing, submitted, partial_failure, failed, completed (derived from statuses)
  createdAt      DateTime        @default(now())
  updatedAt      DateTime        @updatedAt
  MessageStatus  MessageStatus[] // Relation to individual message statuses
}

model MessageStatus {
  id           String    @id @default(cuid())
  messageSid   String    @unique // Twilio's Message SID
  broadcastId  String?   // Link back to the broadcast job
  status       String    // e.g., queued, sending, sent, delivered, undelivered, failed
  to           String    // Recipient phone number (E.164)
  errorCode    Int?      // Twilio error code if failed/undelivered
  errorMessage String?
  receivedAt   DateTime  @default(now()) // When the webhook was received/processed
  updatedAt    DateTime  @updatedAt

  // Relation to Broadcast model
  broadcast Broadcast? @relation(fields: [broadcastId], references: [id])

  // Index for querying by status or broadcast ID
  @@index([status])
  @@index([broadcastId])
}

npx prisma migrate dev --name init

// lib/twilioClient.ts
import twilio from 'twilio';

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;

if (!accountSid || !authToken) {
  throw new Error('Twilio credentials (TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN) are not set in environment variables.');
}

const client = twilio(accountSid, authToken);

export default client;

// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

declare global {
  // allow global `var` declarations
  // eslint-disable-next-line no-var
  var prisma: PrismaClient | undefined;
}

export const prisma =
  global.prisma ||
  new PrismaClient({
    // Optional: Enable logging for development
    // log: ['query', 'info', 'warn', 'error'],
  });

if (process.env.NODE_ENV !== 'production') global.prisma = prisma;

// app/api/send-simple/route.ts
import { NextResponse } from 'next/server';
import twilioClient from '@/lib/twilioClient';

// **Warning:** The following `TWILIO_PHONE_NUMBER` constant is a *placeholder*.
// You **must** replace `'+15017122661'` with your actual, purchased Twilio phone number
// capable of sending SMS for this test to work.
const TWILIO_PHONE_NUMBER = '+15017122661'; // REPLACE THIS with your actual Twilio number

export async function POST(request: Request) {
  console.log('Received request for /api/send-simple');

  if (!process.env.TWILIO_ACCOUNT_SID || !process.env.TWILIO_AUTH_TOKEN) {
      console.error('Server configuration error: Twilio credentials not configured');
      return NextResponse.json({ error: 'Twilio credentials not configured' }, { status: 500 });
  }
   if (!TWILIO_PHONE_NUMBER || TWILIO_PHONE_NUMBER === '+15017122661') {
     console.error('Error: TWILIO_PHONE_NUMBER constant is not set or is still the placeholder. Please edit app/api/send-simple/route.ts.');
     return NextResponse.json({ error: 'Server configuration error: Twilio phone number not set.' }, { status: 500 });
   }

  try {
    const body = await request.json();
    const { to, message } = body;

    // Basic validation
    if (!to || !message) {
      return NextResponse.json({ error: 'Missing `to` or `message` in request body' }, { status: 400 });
    }

    // Validate 'to' number format (basic check, E.164 required)
    if (!/^\+[1-9]\d{1,14}$/.test(to)) {
        return NextResponse.json({ error: 'Invalid `to` phone number format. Use E.164 (e.g., +14155552671)' }, { status: 400 });
    }

    console.log(`Attempting to send message to: ${to} from ${TWILIO_PHONE_NUMBER}`);

    const twilioResponse = await twilioClient.messages.create({
      body: message,
      from: TWILIO_PHONE_NUMBER, // Using a specific purchased number for this test
      to: to, // Recipient number from request body
    });

    console.log('Twilio message SID:', twilioResponse.sid);
    return NextResponse.json({ success: true, messageSid: twilioResponse.sid });

  } catch (error: any) {
    console.error('Error sending message via Twilio:', error);
    // Provide more specific error feedback if possible
    const errorMessage = error.message || 'Failed to send message';
    const statusCode = error.status || 500; // Use Twilio's status code if available
    return NextResponse.json({ error: `Failed to send message: ${errorMessage}`, code: error.code }, { status: statusCode });
  }
}

curl -X POST YOUR_VERCEL_URL/api/send-simple \
  -H ""Content-Type: application/json"" \
  -d '{
    ""to"": ""<YOUR_PHONE_NUMBER_E164&gt;"",
    ""message"": ""Hello from Next.js and Twilio simple send!""
  }'

{
  ""success"": true,
  ""messageSid"": ""SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx""
}

// lib/validators.ts
import { z } from 'zod';

// Basic E.164 format validation (adjust regex as needed for stricter validation)
const phoneSchema = z.string().regex(/^\+[1-9]\d{1,14}$/, {
  message: "Phone number must be in E.164 format (e.g., +14155552671)",
});

export const broadcastSchema = z.object({
  recipients: z.array(phoneSchema).min(1, "At least one recipient is required"),
  message: z.string().min(1, "Message body cannot be empty").max(1600, "Message body is too long"), // Twilio segment limit
});

export type BroadcastPayload = z.infer<typeof broadcastSchema&gt;;

// app/api/broadcast/route.ts
import { NextResponse } from 'next/server';
import twilioClient from '@/lib/twilioClient';
import { prisma } from '@/lib/prisma';
import { broadcastSchema, BroadcastPayload } from '@/lib/validators';
import { ZodError } from 'zod';

const API_SECRET_KEY = process.env.API_SECRET_KEY;
const MESSAGING_SERVICE_SID = process.env.TWILIO_MESSAGING_SERVICE_SID;
const APP_URL = process.env.NEXT_PUBLIC_APP_URL;

export async function POST(request: Request) {
  console.log('Received request for /api/broadcast');

  // 1. Authentication
  const authHeader = request.headers.get('Authorization');
  if (!API_SECRET_KEY) {
    console.error('CRITICAL: API_SECRET_KEY is not set in environment variables.');
    return NextResponse.json({ error: 'Server configuration error: Auth mechanism not configured.' }, { status: 500 });
  }
  // TODO: Use timing-safe comparison for production
  if (!authHeader || authHeader !== `Bearer ${API_SECRET_KEY}`) {
      console.warn('Unauthorized broadcast attempt');
      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // Check required Twilio configurations
  if (!MESSAGING_SERVICE_SID) {
    console.error('CRITICAL: TWILIO_MESSAGING_SERVICE_SID is not set in environment variables.');
    return NextResponse.json({ error: 'Server configuration error: Messaging Service SID missing.' }, { status: 500 });
  }
   if (!process.env.TWILIO_ACCOUNT_SID || !process.env.TWILIO_AUTH_TOKEN) {
      console.error('CRITICAL: Twilio Account SID or Auth Token missing.');
      return NextResponse.json({ error: 'Server configuration error: Twilio credentials missing.' }, { status: 500 });
   }
   if (!APP_URL) {
      console.error('CRITICAL: NEXT_PUBLIC_APP_URL is not set. Cannot set status callback URL.');
      return NextResponse.json({ error: 'Server configuration error: Application URL missing.' }, { status: 500 });
   }

  let payload: BroadcastPayload;

  try {
    // 2. Validation
    const rawBody = await request.json();
    payload = broadcastSchema.parse(rawBody);
    console.log(`Validated broadcast request for ${payload.recipients.length} recipients.`);

  } catch (error) {
    if (error instanceof ZodError) {
      console.error('Validation error:', error.errors);
      return NextResponse.json({ error: 'Invalid request body', details: error.format() }, { status: 400 });
    }
    console.error('Error parsing request body:', error);
    return NextResponse.json({ error: 'Bad Request' }, { status: 400 });
  }

  const { recipients, message } = payload;
  let successfulSubmissions = 0;
  let failedSubmissions = 0;
  const sendPromises: Promise<any&gt;[] = [];
  const startTime = Date.now();
  const statusCallbackUrl = `${APP_URL}/api/webhooks/twilio`;

  // 3. Log Broadcast Attempt
  let broadcastRecord;
  try {
     broadcastRecord = await prisma.broadcast.create({
        data: {
           messageBody: message,
           recipientCount: recipients.length,
           status: 'processing', // Initial status
        },
     });
     console.log(`Created broadcast record: ${broadcastRecord.id}`);
  } catch (dbError) {
     console.error("Failed to create broadcast record in DB:", dbError);
     // Decide if you want to proceed without logging or return an error
     // For this guide, we'll log the error but proceed with sending
     // return NextResponse.json({ error: 'Database error logging broadcast' }, { status: 500 });
  }

  // 4. Iterate and Send using Messaging Service
  console.log(`Initiating send to ${recipients.length} recipients via Messaging Service: ${MESSAGING_SERVICE_SID}`);
  recipients.forEach((recipient) =&gt; {
    const promise = twilioClient.messages
      .create({
        body: message,
        messagingServiceSid: MESSAGING_SERVICE_SID, // *** Use Messaging Service SID ***
        to: recipient,
        // Define the Status Callback URL to receive status updates
        statusCallback: statusCallbackUrl,
      })
      .then((msg) =&gt; {
        successfulSubmissions++;
        console.log(`Successfully submitted message to ${recipient}, SID: ${msg.sid}`);
        // Optionally log individual message submission status here or rely on webhooks for final status
        // Associate message SID with broadcast ID immediately if possible (though webhook is more reliable for final status)
        if (broadcastRecord) {
          prisma.messageStatus.create({
            data: {
              messageSid: msg.sid,
              broadcastId: broadcastRecord.id,
              status: msg.status, // Initial status from Twilio (e.g., 'queued', 'accepted')
              to: recipient,
            }
          }).catch(dbError =&gt; console.error(`Failed to log initial status for ${msg.sid}:`, dbError));
        }
      })
      .catch((error) =&gt; {
        failedSubmissions++;
        console.error(`Failed to submit message to ${recipient}: ${error.message} (Code: ${error.code})`);
        // Optionally log individual message failure status here
        // Common submission errors: 21211 (Invalid 'To'), 21610 (Opt-out), 21612 (Msg Service unavailable)
        if (broadcastRecord) {
          prisma.messageStatus.create({
            data: {
              messageSid: `failed_submission_${recipient}_${Date.now()}`, // Placeholder SID for failed submissions
              broadcastId: broadcastRecord.id,
              status: 'failed_submission',
              to: recipient,
              errorCode: error.code,
              errorMessage: error.message,
            }
          }).catch(dbError =&gt; console.error(`Failed to log failed submission for ${recipient}:`, dbError));
        }
      });
    sendPromises.push(promise);
  });

  // 5. Wait for all submission requests to Twilio to complete (or fail)
  // Note: This only confirms Twilio *accepted* the request to send, not delivery.
  await Promise.allSettled(sendPromises);

  const duration = Date.now() - startTime;
  console.log(`Broadcast submission processing finished in ${duration}ms. Success: ${successfulSubmissions}, Failed: ${failedSubmissions}`);

  // 6. Update Broadcast Record Status (Optional)
   if (broadcastRecord) {
      try {
         const finalStatus = failedSubmissions &gt; 0
            ? (successfulSubmissions &gt; 0 ? 'partial_failure' : 'failed')
            : 'submitted'; // Indicate submission complete, final status via webhooks

         await prisma.broadcast.update({
            where: { id: broadcastRecord.id },
            data: {
               status: finalStatus,
            },
         });
      } catch (dbError) {
         console.error("Failed to update broadcast record status in DB:", dbError);
      }
   }

  // 7. Return Response
  return NextResponse.json({
    message: `Broadcast initiated. Submitted to Twilio: ${successfulSubmissions}, Failed submissions: ${failedSubmissions}`,
    broadcastId: broadcastRecord?.id ?? null, // Include ID if logged
  });
}

# .env
# ... other variables
TWILIO_MESSAGING_SERVICE_SID=""MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"" # Paste the SID here
# ...

// app/api/webhooks/twilio/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prisma } from '@/lib/prisma';
import { twilio } from 'twilio'; // Import to use the validator

const TWILIO_AUTH_TOKEN = process.env.TWILIO_AUTH_TOKEN;

// Helper function to get the full URL, handling potential proxy headers
function getAbsoluteUrl(req: NextRequest): string {
  const protocol = req.headers.get('x-forwarded-proto') || (process.env.NODE_ENV === 'production' ? 'https' : 'http');
  const host = req.headers.get('host'); // Host includes port if non-standard
  const pathname = req.nextUrl.pathname;
  const search = req.nextUrl.search; // Include query params if any

  if (!host) {
    // Fallback or error handling if host is missing
    console.error("Webhook handler couldn't determine host header.");
    // Attempt using NEXT_PUBLIC_APP_URL as a fallback base, but this might be less accurate
    const appUrl = process.env.NEXT_PUBLIC_APP_URL || '';
    return `${appUrl}${pathname}${search}`;
  }

  return `${protocol}://${host}${pathname}${search}`;
}


export async function POST(request: NextRequest) {
  console.log('Received Twilio webhook');

  if (!TWILIO_AUTH_TOKEN) {
     console.error("CRITICAL: TWILIO_AUTH_TOKEN is not set for webhook validation. Cannot validate request.");
     // Return 200 OK to Twilio even on server config error to prevent retries.
     // Log the error internally. This is the recommended approach.
     return new Response(null, { status: 200 });
     // Avoid returning 5xx, as Twilio retries might worsen the problem. Rely on internal monitoring.
  }

  // 1. Validate Twilio Request (Security)
  // Get headers needed for validation. Header names are case-insensitive per HTTP spec,
  // but NextRequest provides them lower-cased via request.headers.get().
  const signature = request.headers.get('x-twilio-signature');
  const url = getAbsoluteUrl(request); // Use helper to reconstruct the full URL
  const rawBody = await request.text(); // Get raw body for validation

  // Reconstruct body as key/value pairs (Twilio webhooks are form-urlencoded)
  const params = new URLSearchParams(rawBody);
  const bodyParams: Record<string_ string&gt; = {};
  params.forEach((value, key) =&gt; {
      bodyParams[key] = value;
  });

  if (!signature) {
      console.warn('Webhook received without x-twilio-signature header.');
      // Still return 200 to prevent retries, but log the issue.
      return new Response('Missing validation signature header', { status: 400 }); // Use 400 Bad Request
  }

  let isValid = false;
  try {
    isValid = twilio.validateRequest(
        TWILIO_AUTH_TOKEN,
        signature,
        url,
        bodyParams // Pass the parsed key/value object
    );
  } catch (validationError) {
    console.error("Error during Twilio validation:", validationError);
    // Treat validation errors as invalid requests
    isValid = false;
  }


  if (!isValid) {
      console.warn(`Invalid Twilio webhook signature for URL: ${url}`);
      // Return 403 Forbidden if the signature is invalid
      return new Response('Invalid signature', { status: 403 });
  }

  console.log('Twilio webhook signature validated successfully.');

  // 2. Process Status Update
  const messageSid = bodyParams.MessageSid;
  const messageStatus = bodyParams.MessageStatus; // delivered, undelivered, failed, sent, queued etc.
  const to = bodyParams.To;
  const errorCode = bodyParams.ErrorCode ? parseInt(bodyParams.ErrorCode, 10) : undefined;
  const errorMessage = bodyParams.ErrorMessage;

  if (!messageSid || !messageStatus || !to) {
      console.warn('Webhook missing required parameters (MessageSid, MessageStatus, To)');
      // Return 200 OK but log the issue
      return new Response('Missing required parameters', { status: 400 });
  }

  console.log(`Status Update: SID=${messageSid}, Status=${messageStatus}, To=${to}, ErrorCode=${errorCode || 'N/A'}`);

  try {
    // 3. Store or Update Status in Database
    // Use upsert: update if messageSid exists, create if it doesn't
    // This handles cases where the initial submission log failed or webhook arrives first
    const updatedStatus = await prisma.messageStatus.upsert({
        where: { messageSid: messageSid },
        update: {
            status: messageStatus,
            errorCode: errorCode,
            errorMessage: errorMessage,
            // updatedAt is handled automatically by Prisma @updatedAt
        },
        create: {
            messageSid: messageSid,
            status: messageStatus,
            to: to,
            errorCode: errorCode,
            errorMessage: errorMessage,
            // Attempt to find associated broadcastId if not already linked
            // This requires a more complex lookup or passing broadcastId via custom Twilio params
            // broadcastId: findBroadcastIdForMessage(messageSid), // Placeholder for lookup logic
        }
    });
    console.log(`Stored/Updated status for ${messageSid}. New status: ${updatedStatus.status}`);

    // Optional: Update overall Broadcast status based on aggregated MessageStatus updates
    // This logic can be complex (e.g., check if all messages are final, calculate success rate)
    // if (updatedStatus.broadcastId) {
    //   await updateBroadcastStatus(updatedStatus.broadcastId);
    // }

  } catch (dbError) {
    console.error(`Database error processing webhook for ${messageSid}:`, dbError);
    // IMPORTANT: Return 200 OK to Twilio even if DB write fails to prevent retries.
    // Ensure robust internal logging/monitoring alerts on these DB errors.
    // Acknowledge receipt so Twilio doesn't retry endlessly on a DB issue.
    return new Response(null, { status: 200 });
  }

  // 4. Acknowledge Receipt to Twilio
  // Return an empty 200 OK response to signal successful receipt.
  return new Response(null, { status: 200 });
}

// Placeholder functions for potential enhancements
// async function findBroadcastIdForMessage(messageSid: string): Promise<string | null&gt; {
//   // Implement logic to find the broadcast ID, maybe based on custom parameters
//   // passed during message creation or other contextual information.
//   return null;
// }

// async function updateBroadcastStatus(broadcastId: string): Promise<void&gt; {
//   // Implement logic to check all MessageStatus records for the broadcast
//   // and update the Broadcast record's status (e.g., to 'completed', 'failed').
//   console.log(`Triggering status update check for broadcast ${broadcastId}`);
// }