Skip to Content

Idempotent Transactional SMS Dispatch

Configure a typed SMS Pro client, attach UUID idempotency keys, test against deterministic sandbox numbers, and parse RFC 7807 errors.

View Markdown (.md)

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.

1

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
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,};}
2

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
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 };}
3

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
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();
4

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
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}`);}