User Browser --(1. Submits Form)--> Next.js Frontend
Next.js Frontend --(2. POST Request)--> Next.js API Route (/api/send-bulk)
Next.js API Route --(3. Reads Credentials)--> Environment Variables (.env.local)
Next.js API Route --(4. Loops through Recipients)--> For Each Recipient
  For Each Recipient --(5. Prepare & Send Request w/ Retries)--> Sinch Conversation API
    Sinch Conversation API --(6. Send Message)--> Recipient Phone
    Sinch Conversation API --(7. API Response)--> For Each Recipient
  For Each Recipient --(8. Aggregated Results)--> Next.js API Route
Next.js API Route --(9. API Response)--> Next.js Frontend
Next.js Frontend --(10. Display Status)--> User Browser

npx create-next-app@latest sinch-bulk-messaging --typescript --eslint --tailwind --src-dir --app --import-alias "@/*"

cd sinch-bulk-messaging

npm install axios jsonwebtoken libphonenumber-js
npm install --save-dev @types/jsonwebtoken

# or using yarn
# yarn add axios jsonwebtoken libphonenumber-js
# yarn add --dev @types/jsonwebtoken

# or using pnpm
# pnpm add axios jsonwebtoken libphonenumber-js
# pnpm add --save-dev @types/jsonwebtoken

# .env.local

# Sinch API Credentials (Obtain from your Sinch Dashboard)
SINCH_PROJECT_ID="YOUR_SINCH_PROJECT_ID"
SINCH_ACCESS_KEY_ID="YOUR_SINCH_ACCESS_KEY_ID"    # The Key ID
SINCH_ACCESS_KEY="YOUR_SINCH_ACCESS_KEY_SECRET" # The Key Secret
SINCH_APP_ID="YOUR_REGISTERED_SINCH_APP_ID"

# Sender ID (e.g., your provisioned Sinch phone number in E.164 format)
# This MUST be associated with your SINCH_APP_ID
SINCH_SENDER_ID="YOUR_SINCH_PHONE_NUMBER_OR_SENDER_ID"

# Sinch API Region Base URL (e.g., eu, us, etc.)
# Check Sinch documentation for the correct region for your account
SINCH_API_BASE_URL="https://eu.conversation.api.sinch.com" # Or other region like us.conversation.api.sinch.com

# A secret used ONLY if generating *internal* application JWTs (e.g., for sessions), NOT for Sinch auth.
# Generate a strong random string (e.g., using openssl rand -hex 32)
JWT_SECRET="generate-a-strong-random-secret-here-for-internal-use"

// src/app/page.tsx
'use client'; // Required for interactive components in App Router

import { useState } from 'react';
import axios from 'axios';

export default function HomePage() {
  const [recipients, setRecipients] = useState('');
  const [message, setMessage] = useState('');
  const [status, setStatus] = useState('');
  const [isLoading, setIsLoading] = useState(false);

  const handleSubmit = async (event: React.FormEvent<HTMLFormElement&gt;) =&gt; {
    event.preventDefault();
    setIsLoading(true);
    setStatus('Sending messages...');

    // Basic validation
    if (!recipients.trim() || !message.trim()) {
      setStatus('Please enter recipients and a message.');
      setIsLoading(false);
      return;
    }

    // Split recipients string into an array, trim whitespace, filter empty strings
    const recipientList = recipients
      .split(',')
      .map(num =&gt; num.trim())
      .filter(num =&gt; num.length &gt; 0);

    if (recipientList.length === 0) {
        setStatus('Invalid recipient list.');
        setIsLoading(false);
        return;
    }

    try {
      const response = await axios.post('/api/send-bulk', {
        recipients: recipientList,
        message,
      });

      if (response.data.success) {
        setStatus(`Successfully initiated sending to ${response.data.sentCount} recipients. Failures: ${response.data.failedCount}.`);
        // Optionally display failure details if needed: response.data.failures
      } else {
        setStatus(`Error: ${response.data.error || 'Failed to send messages.'}`);
      }
    } catch (error: any) {
      console.error('Error sending bulk message:', error);
      const errorMessage = error.response?.data?.error || error.message || 'An unexpected error occurred.';
      setStatus(`Error: ${errorMessage}`);
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <main className=""flex min-h-screen flex-col items-center justify-center p-12 bg-gray-50""&gt;
      <div className=""w-full max-w-md p-8 space-y-6 bg-white rounded-lg shadow-md""&gt;
        <h1 className=""text-2xl font-bold text-center text-gray-800""&gt;Sinch Bulk Message Sender</h1&gt;

        <form onSubmit={handleSubmit} className=""space-y-4""&gt;
          <div&gt;
            <label htmlFor=""recipients"" className=""block text-sm font-medium text-gray-700""&gt;
              Recipients (comma-separated phone numbers, e.g., +15551234567,+447700900000)
            </label&gt;
            <textarea
              id=""recipients""
              name=""recipients""
              rows={3}
              value={recipients}
              onChange={(e) =&gt; setRecipients(e.target.value)}
              required
              className=""mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 sm:text-sm""
              placeholder=""+15551234567,+447700900000""
            /&gt;
          </div&gt;

          <div&gt;
            <label htmlFor=""message"" className=""block text-sm font-medium text-gray-700""&gt;
              Message
            </label&gt;
            <textarea
              id=""message""
              name=""message""
              rows={4}
              value={message}
              onChange={(e) =&gt; setMessage(e.target.value)}
              required
              className=""mt-1 block w-full px-3 py-2 border border-gray-300 rounded-md shadow-sm focus:outline-none focus:ring-indigo-500 focus:border-indigo-500 sm:text-sm""
              placeholder=""Enter your message here...""
            /&gt;
          </div&gt;

          <div&gt;
            <button
              type=""submit""
              disabled={isLoading}
              className={`w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white ${
                isLoading ? 'bg-indigo-400 cursor-not-allowed' : 'bg-indigo-600 hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500'
              }`}
            &gt;
              {isLoading ? 'Sending...' : 'Send Bulk Message'}
            </button&gt;
          </div&gt;
        </form&gt;

        {status && (
          <div className={`mt-4 p-3 rounded-md text-sm ${status.startsWith('Error:') ? 'bg-red-100 text-red-700' : 'bg-green-100 text-green-700'}`}&gt;
            {status}
          </div&gt;
        )}
      </div&gt;
    </main&gt;
  );
}

// src/lib/sinch.ts
import axios, { AxiosInstance } from 'axios';
import * as jwt from 'jsonwebtoken'; // For potential JWT-based auth

// --- Environment Variable Validation ---
const projectId = process.env.SINCH_PROJECT_ID;
const accessKeyId = process.env.SINCH_ACCESS_KEY_ID; // Key ID from Sinch portal
const accessKeySecret = process.env.SINCH_ACCESS_KEY; // Key Secret from Sinch portal
const appId = process.env.SINCH_APP_ID;
const senderId = process.env.SINCH_SENDER_ID;
const sinchApiBaseUrl = process.env.SINCH_API_BASE_URL;
// JWT_SECRET is intentionally not validated here as it's for internal use, not Sinch auth

if (!projectId || !accessKeyId || !accessKeySecret || !appId || !senderId || !sinchApiBaseUrl) {
    console.error(""FATAL ERROR: Missing required Sinch environment variables."");
    // In a real app, throw an error to prevent startup or handle appropriately
    throw new Error(""Missing required Sinch environment variables."");
}
// --- End Environment Variable Validation ---


// --- Sinch Authentication (Bearer Token Generation - PLACEHOLDER) ---
// **CRITICAL**: You MUST verify the correct authentication method with the official
// Sinch Conversation API documentation for the endpoint being used.
// Common methods include:
// 1. Basic Authentication: `Authorization: Basic <base64(keyId:keySecret)&gt;`
// 2. Bearer Token (Short-lived JWT): Generated using Key ID/Secret, potentially specific claims.
// 3. Bearer Token (Long-lived): A pre-generated token from the Sinch portal.
//
// The function below provides examples but is a GUESS. DO NOT use in production without verification.

async function getSinchAccessToken(): Promise<string&gt; {
    console.warn(""Using PLACEHOLDER Sinch authentication logic. VERIFY with official Sinch documentation!"");

    // ** Option 1: Pre-generated Long-Lived Token (if available & preferred) **
    // If your `SINCH_ACCESS_KEY` *is* the long-lived token provided by Sinch:
    // return `Bearer ${accessKeySecret}`;

    // ** Option 2: Basic Authentication (if supported by the endpoint) **
    // const credentials = Buffer.from(`${accessKeyId}:${accessKeySecret}`).toString('base64');
    // return `Basic ${credentials}`;

    // ** Option 3: Generating a Short-Lived JWT (EXAMPLE - VERIFY CLAIMS & SIGNING) **
    // This example assumes HS256 signing with the Key Secret. Sinch might require different claims,
    // algorithm (e.g., RS256 with a private key), or a call to a token endpoint.
    try {
        const now = Math.floor(Date.now() / 1000);
        const expiry = now + 3600; // Token expires in 1 hour
        const claims = {
            // Common JWT claims (verify exact requirements with Sinch)
            iss: 'self', // Or your specific issuer identifier if required
            // aud: 'https://conversationapi.sinch.com', // Example audience
            iat: now,
            exp: expiry,
            // Sinch-specific claims (VERIFY THESE)
            keyid: accessKeyId, // Often required
            project_id: projectId, // Often required
            // application_id: appId, // Sometimes required
        };

        // Sign using the Key Secret (SINCH_ACCESS_KEY)
        // **VERIFY THE ALGORITHM (HS256, RS256, etc.) with Sinch Docs**
        const token = jwt.sign(claims, accessKeySecret, { algorithm: 'HS256' });
        return `Bearer ${token}`;

    } catch (error) {
        console.error(""Error generating Sinch JWT (using placeholder logic):"", error);
        throw new Error(""Failed to generate Sinch authentication token."");
    }

    // ** Fallback/Error **
    // throw new Error(""No valid Sinch authentication method configured or verified."");
}


// --- Axios Instance for Sinch API ---
const sinchApiClient = axios.create({
    baseURL: sinchApiBaseUrl,
    headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
    },
    // Add timeout to prevent hanging requests
    timeout: 15000, // 15 seconds
});

// Add an interceptor to dynamically add the Authorization header
sinchApiClient.interceptors.request.use(async (config) =&gt; {
    try {
        // Get a fresh token for each request (consider caching for short periods if generating JWTs)
        const token = await getSinchAccessToken();
        config.headers.Authorization = token;
        return config;
    } catch (error) {
        console.error(""Error setting Sinch auth header:"", error);
        // Prevent the request if token generation fails
        return Promise.reject(new Error('Failed to set Sinch authentication header.'));
    }
}, (error) =&gt; {
    return Promise.reject(error);
});


// --- Send Message Function ---
export interface SendMessageResult {
    success: boolean;
    messageId?: string;
    error?: string;
    recipient: string;
    status?: number; // HTTP status code for context
}

export async function sendSinchMessage(recipient: string, messageBody: string): Promise<SendMessageResult&gt; {
    // Basic phone number validation (can be enhanced with libphonenumber-js)
    if (!/^\+?[1-9]\d{1,14}$/.test(recipient)) {
         console.warn(`Invalid phone number format skipped: ${recipient}`);
         return { success: false, error: 'Invalid phone number format', recipient, status: 400 };
    }

    const endpoint = `/v1/projects/${projectId}/messages:send`;

    // **VERIFY PAYLOAD STRUCTURE WITH SINCH CONVERSATION API DOCS**
    // The fields below (especially `recipients`, `contact_id`, `sms_message.from`)
    // might differ based on the exact API version and channel requirements.
    const payload = {
        app_id: appId,
        // `recipients` structure: Check if it should be `[{ phone_number: recipient }]` or similar.
        recipients: [{ contact_id: recipient }], // Assuming contact_id is the E.164 number
        message: {
            text_message: {
                text: messageBody,
            },
        },
        // Define the channel and potentially sender identity explicitly
        channel_priority_order: [""SMS""], // Prioritize SMS
        // `sms_message`: Check if this block is needed and if `from` is the correct field for sender ID.
        sms_message: {
             from: senderId, // Specify sender for SMS channel
        },
        // Other potential fields: `callback_url`, `processing_strategy`, etc.
    };

    try {
        console.log(`Attempting to send message via Sinch to ${recipient}...`);
        const response = await sinchApiClient.post(endpoint, payload);

        // Check Sinch response structure for success indication and message ID
        // This depends heavily on the actual API response format
        const messageId = response.data?.message_id || response.data?.id || 'N/A'; // Adjust based on actual response

        // Typically 200, 201, or 202 indicate acceptance by Sinch
        if (response.status &gt;= 200 && response.status &lt; 300) {
             console.log(`Message accepted by Sinch for ${recipient}. Message ID: ${messageId}_ Status: ${response.status}`);
            return { success: true_ messageId: messageId_ recipient_ status: response.status };
        } else {
            // This case might not be hit if Axios throws on non-2xx status by default
            console.warn(`Sinch API returned non-success status ${response.status} for ${recipient}:`_ response.data);
            return { success: false_ error: `Sinch API Error: Status ${response.status}`_ recipient_ status: response.status };
        }
    } catch (error: any) {
        let errorMessage = 'Unknown Sinch API error';
        let status = 500; // Default internal error

        if (axios.isAxiosError(error)) {
            status = error.response?.status || 500;
            const errorData = error.response?.data;
            const sinchError = errorData?.error?.message || JSON.stringify(errorData); // Try to extract Sinch error message
            errorMessage = `Sinch API Error (${status}): ${sinchError || error.message}`;
            console.error(`Sinch API error for ${recipient}: Status ${status}_ Data:`_ errorData || error.message);
        } else {
            console.error(`Non-Axios error sending to ${recipient}:`_ error);
            errorMessage = error.message || 'An unexpected error occurred during Sinch request.';
        }
        return { success: false_ error: errorMessage_ recipient_ status };
    }
}

// --- Retry Mechanism ---
// Wrapper function to add retry logic to sendSinchMessage
export async function sendSinchMessageWithRetry(
    recipient: string_
    messageBody: string_
    maxRetries = 2 // Total attempts = 1 + maxRetries
): Promise<SendMessageResult&gt; {
    let attempt = 0;
    while (attempt &lt;= maxRetries) {
        const result = await sendSinchMessage(recipient_ messageBody);

        // If successful_ return immediately
        if (result.success) {
            return result;
        }

        attempt++;

        // Check if the error is potentially retryable and if we haven't exceeded max retries
        const isRetryable = result.status === 429 || result.status &gt;= 500; // Retry on Rate Limit or Server Error
        const shouldRetry = isRetryable && attempt &lt;= maxRetries;

        if (!shouldRetry) {
            if (isRetryable) {
                 console.warn(`Send failed permanently for ${recipient} after ${attempt} attempts. Error: ${result.error}`);
            }
            // Don't retry non-retryable errors (e.g._ 400 Bad Request_ 401 Auth Error)
            return result; // Return the final failure result
        }

        // Calculate delay using exponential backoff with jitter
        const delay = Math.pow(2_ attempt - 1) * 200 + Math.random() * 100; // Exponential backoff (e.g._ ~200ms_ ~400ms_ ~800ms...)
        console.log(`Retrying send for ${recipient} (attempt ${attempt}/${maxRetries + 1}) after ${Math.round(delay)}ms due to status ${result.status}...`);
        await new Promise(resolve =&gt; setTimeout(resolve, delay));
    }

    // Should ideally not be reached if logic is correct, but acts as a final safety net
    return { success: false, error: `Max retries (${maxRetries}) exceeded`, recipient, status: -1 };
}

// src/app/api/send-bulk/route.ts
import { NextResponse } from 'next/server';
import { sendSinchMessageWithRetry, SendMessageResult } from '@/lib/sinch'; // Use retry wrapper

export async function POST(request: Request) {
  console.log(""Received request on /api/send-bulk"");

  let requestBody;
  try {
    requestBody = await request.json();
  } catch (error) {
    console.error(""Error parsing request body:"", error);
    return NextResponse.json({ success: false, error: 'Invalid request body. Must be JSON.' }, { status: 400 });
  }

  const { recipients, message } = requestBody;

  // --- Input Validation ---
  if (!Array.isArray(recipients) || recipients.length === 0) {
    return NextResponse.json({ success: false, error: '`recipients` must be a non-empty array of strings.' }, { status: 400 });
  }
  if (typeof message !== 'string' || !message.trim()) {
    return NextResponse.json({ success: false, error: '`message` must be a non-empty string.' }, { status: 400 });
  }
  // Consider adding more validation (e.g., max recipients, message length)
  const MAX_RECIPIENTS = 1000; // Example limit
  if (recipients.length > MAX_RECIPIENTS) {
     return NextResponse.json({ success: false, error: `Too many recipients. Maximum allowed is ${MAX_RECIPIENTS}.` }, { status: 400 });
  }
  // --- End Input Validation ---


  // --- Rate Limiting (Conceptual - Implement with a library) ---
  // In production, add rate limiting here using libraries like '@upstash/ratelimit'
  // const ip = request.headers.get('x-forwarded-for') ?? '127.0.0.1';
  // const { success } = await rateLimiter.limit(ip);
  // if (!success) {
  //   console.warn(`Rate limit exceeded for IP: ${ip}`);
  //   return NextResponse.json({ error: 'Rate limit exceeded' }, { status: 429 });
  // }
  // --- End Rate Limiting ---

  console.log(`Initiating bulk send to ${recipients.length} recipients.`);

  // Send messages concurrently using the retry wrapper
  // Use Promise.allSettled to wait for all attempts, even failures
  const sendPromises: Promise<SendMessageResult&gt;[] = recipients.map(recipient =&gt;
    sendSinchMessageWithRetry(String(recipient), message) // Ensure recipient is string, call retry wrapper
  );

  let results: SendMessageResult[] = [];
  try {
    const settledResults = await Promise.allSettled(sendPromises);

    results = settledResults.map((result, index) =&gt; {
        const recipient = String(recipients[index]); // Get corresponding recipient
        if (result.status === 'fulfilled') {
            // Promise resolved (sendSinchMessageWithRetry returned a result)
            return result.value; // Contains { success: boolean, messageId?, error?, recipient, status? }
        } else {
            // Promise rejected (unexpected error in sendSinchMessageWithRetry itself, less likely)
            console.error(`Unexpected failure sending to ${recipient}:`, result.reason);
            return {
                success: false,
                error: result.reason?.message || 'Unknown error during promise execution',
                recipient: recipient,
                status: 500 // Indicate internal server error
            };
        }
    });

  } catch (error) {
      // Catch errors in the Promise.allSettled processing itself (unlikely)
      console.error(""Catastrophic error processing bulk send results:"", error);
      return NextResponse.json({ success: false, error: 'Server error processing send results' }, { status: 500 });
  }

  const sentCount = results.filter(r =&gt; r.success).length;
  const failedCount = results.length - sentCount;
  // Collect details only for failures
  const failures = results
      .filter(r =&gt; !r.success)
      .map(r =&gt; ({ recipient: r.recipient, error: r.error, status: r.status }));

  console.log(`Bulk send processing completed. Accepted by Sinch: ${sentCount}, Failed Attempts: ${failedCount}`);
  if (failedCount &gt; 0) {
      console.warn(""Failures occurred:"", JSON.stringify(failures, null, 2)); // Log failure details
  }

  // Return a summary response
  return NextResponse.json({
    success: true, // Indicates the API call itself succeeded in processing
    sentCount,     // Count of messages accepted by Sinch (after retries)
    failedCount,   // Count of messages that failed all attempts
    // Optionally include failure details, but be mindful of response size for large lists
    failures: failedCount &gt; 0 ? failures : undefined,
  });
}