A good SMS abstraction is a thin interface with a few methods and your own message model, so changing providers means writing one adapter and not touching product code. It isn't a way to run two providers at once. Most of the effort goes into deciding what stays out of the interface.

We make Ready, and we'd rather you be able to leave. This guide covers the abstraction itself, and our Twilio migration checklist covers the number side.

Keep the interface small

export interface SmsGateway {
  send(msg: OutboundSms): Promise<SendOutcome>;
  parseInbound(raw: string, headers: Headers): InboundSms;
  parseStatus(raw: string, headers: Headers): StatusUpdate;
}

export type SendOutcome =
  | { kind: 'accepted'; providerId?: string }
  | { kind: 'retry'; reason: string }
  | { kind: 'refused'; reason: 'opted_out' | 'invalid_number' | 'quiet_hours' | 'other' };

export interface OutboundSms {
  to: string;          // E.164
  body: string;
  idempotencyKey: string;
  tenantId: string;
}

Three methods is enough. The trick is SendOutcome: your product code should never see an HTTP status or a provider's error string. It sees three states, accepted, worth retrying and refused, and the adapter does the translating. That's the part that makes a swap cheap, because retry policy and user-facing errors are written once against your types.

What belongs in the adapter

In the adapterOutside it
Auth headers and base URLWho's allowed to text whom
Mapping status codes to SendOutcomeRetry schedule and queueing
Parsing provider webhook JSONStoring messages and conversations
Signature verificationOpt-out records in your own database
Idempotency header nameTemplates, segment counts, cost estimates

Keep your own copy of opt-outs, consent and message history. If those live only inside a provider, switching means losing them, and our post on preserving opt-out history in a migration shows how painful that is.

The Ready adapter

export class ReadyGateway implements SmsGateway {
  constructor(private apiKey: string) {}

  async send(m: OutboundSms): Promise<SendOutcome> {
    const res = await fetch('https://api.tryready.com/v1/messages', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'X-API-Key': this.apiKey, 'Idempotency-Key': m.idempotencyKey },
      body: JSON.stringify({ to: m.to, body: m.body, consent_attested: true }),
      signal: AbortSignal.timeout(35_000),
    });
    if (res.ok) return { kind: 'accepted' };
    const code = (await res.json().catch(() => ({}))).code;
    if (res.status === 202 && code === 'send_outcome_unknown') return { kind: 'unknown' }; // check GET /v1/messages
    if (res.status === 409 && code === 'idempotency_in_progress') return { kind: 'retry', reason: code };
    if (res.status === 409) return { kind: 'refused', reason: 'quiet_hours' };
    if (res.status === 429 || res.status >= 500) return { kind: 'retry', reason: String(res.status) };
    return { kind: 'refused', reason: 'other' };
  }
  // parseInbound and parseStatus omitted
}

Read the real error codes from the error docs before you map a 409 to quiet hours, since a 409 can also mean an idempotent request is still in progress. A 503 that says nothing was sent is stored under the key, so retry it with a new key. Ready answers within 30 s, which is why the timeout is 35 s. This is a sketch, not a finished mapper.

What the abstraction can't do

It can't make two providers behave the same. Registration, throughput, number ownership and error codes differ, and a lowest-common-denominator interface hides features you may want, such as iMessage on a blue line. It also isn't a failover layer: Ready doesn't route between carrier providers, and a second gateway means a second set of numbers and registrations that you'd have to keep warm. Treat the adapter as an exit door, not a redundancy plan. The build versus buy post covers the cost side of those choices.

FAQ

Is an abstraction layer over-engineering?

For a prototype, yes. Once texting is a feature customers pay for, an hour spent on a three-method interface is cheap insurance, and it makes testing easier too.

Should the interface include templates or campaigns?

No. Keep those in your product code. Provider-specific campaign features are exactly what makes an interface leak.

Can I use it for multi-tenant sending?

Yes, pass the tenant ID through so the adapter picks the right sub-account and numbers. See multi-tenant SMS architecture.

The short version

Three methods, your own outcome type, your own copy of consent and opt-outs. Swapping providers then touches one file.

Cost and registration

A segment on the Standard rate is $0.0075 plus a $0.0045 carrier fee, passed through at cost, excluding optional screening. An account can send up to 500 texts a month before it registers for 10DLC, and most approvals take 2 to 7 days. See pricing for the full list.