Idempotent Transactional SMS Dispatch
Configure a typed SMS Pro client, attach UUID idempotency keys, test against deterministic sandbox numbers, and parse RFC 7807 errors.
Learn how to build a resilient SMS dispatch helper that safely retries transient network timeouts without double-sending messages or double-charging your wallet.
Idempotent SMS Dispatch Client
Scroll through the narrative or click any step to inspect the corresponding TypeScript module.
Configure Gateway & Auth Headers
Initialize configuration from environment variables. Test keys and live keys both use https://api.smspro.com. The key prefix selects simulated delivery or carrier delivery.
src/lib/smspro-client.ts
export interface SmsProConfig {baseUrl: string;apiKey: string;}export function getSmsProConfig(): SmsProConfig {const apiKey = process.env.SMSPRO_API_KEY;if (!apiKey) { throw new Error('Missing SMSPRO_API_KEY environment variable');}const defaultBaseUrl = 'https://api.smspro.com';return { baseUrl: process.env.SMSPRO_BASE_URL ?? defaultBaseUrl, apiKey,};}Attach UUID Idempotency-Key
Generate a single UUID Idempotency-Key per logical notification outside your retry loop. SMS Pro caches the initial dispatch result for 24 hours so network retries remain side-effect free.
src/lib/send-sms.ts
import { randomUUID } from 'node:crypto';import { getSmsProConfig } from './smspro-client';export interface SendSmsInput {to: string;message: string;senderId?: string;deliveryCallbackUrl?: string;idempotencyKey?: string;}export async function dispatchTransactionalSms(input: SendSmsInput) {const { baseUrl, apiKey } = getSmsProConfig();const idempotencyKey = input.idempotencyKey ?? randomUUID();const response = await fetch(`${baseUrl}/api/v1/public/sms/send`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Api-Key': apiKey, 'Idempotency-Key': idempotencyKey, }, body: JSON.stringify({ to: input.to, message: input.message, senderId: input.senderId ?? 'SMSPRO', deliveryCallbackUrl: input.deliveryCallbackUrl, }),});return { response, idempotencyKey };}Test Deterministic Sandbox Outcomes
With a sk_test_... key configured, send to SMS Pro's magic test numbers (+233200000001 through +233200000004) to simulate DELIVERED, UNDELIVERABLE, EXPIRED, and REJECTED_SPAM receipts without incurring charges.
scripts/test-sandbox.ts
import { dispatchTransactionalSms } from '../src/lib/send-sms';const SANDBOX_NUMBERS = {DELIVERED: '+233200000001',UNDELIVERABLE: '+233200000002',EXPIRED: '+233200000003',REJECTED_SPAM: '+233200000004',} as const;async function verifySandboxMatrix() {const { response, idempotencyKey } = await dispatchTransactionalSms({ to: SANDBOX_NUMBERS.DELIVERED, message: 'Your order #4821 has been dispatched.', senderId: 'SMSPRO',});const body = await response.json();console.log('Status:', response.status, 'Idempotency-Key:', idempotencyKey);console.log('Message ID:', body.data?.messageId);}verifySandboxMatrix();Handle RFC 7807 Problem Details
All non-2xx responses return application/problem+json conforming to RFC 7807. Surface problem.code and problem.requestId in application logs for rapid support correlation, and only retry 429 / 5xx errors.
src/lib/errors.ts
export interface ProblemDetails {type: string;title: string;status: number;detail: string;instance: string;code: string;requestId: string;}export async function parseSmsProResponse<T>(response: Response): Promise<T> {if (response.ok) { const json = (await response.json()) as { data: T }; return json.data;}const contentType = response.headers.get('content-type') ?? '';if (contentType.includes('application/problem+json')) { const problem = (await response.json()) as ProblemDetails; throw new Error( `SMS Pro [${problem.code}] (${problem.status}): ${problem.detail} (requestId=${problem.requestId})`, );}throw new Error(`Unexpected SMS Pro HTTP ${response.status}`);}