To mock an SMS API in unit tests, put the HTTP call behind a one-method interface, hand your code a fake that records what it was asked to send, and keep a single slower contract test that talks to a test key. The fake proves your logic, and the contract test proves the request shape.

We make Ready, so the examples use the Ready request shape (POST /v1/messages), but nothing here is specific to one provider.

Three layers, three jobs

LayerWhat it provesSpeed
Fake sender (in-memory)Your code decides to send the right text to the right personInstant
HTTP stubYour client builds the right request and handles each statusFast
Test key against the real APIThe request shape and auth still workSlow, run on a schedule

Most teams stop at the first layer and then get surprised when a header is wrong in production. Use all three, in that proportion: many fakes, some HTTP stubs, one contract test.

Layer 1: a fake that records

class FakeSms:
    def __init__(self):
        self.sent = []

    def send(self, to, body, key):
        self.sent.append({"to": to, "body": body, "key": key})
        return 202

def test_shipping_notice_sent_once():
    sms = FakeSms()
    notify_shipped(order, sms)
    assert sms.sent == [{"to": "+12125550199", "body": "Your order #1042 has shipped.", "key": order.sms_key}]

Assert on the key too. A test that checks the key is stable across two calls catches the most expensive bug in this area, a new key on every retry, which turns a timeout into a duplicate text.

Layer 2: stub HTTP, not your own code

Stub at the network edge so your real client runs. In Python, the responses library does it:

import responses

@responses.activate
def test_429_is_retried_with_same_key():
    url = "https://api.tryready.com/v1/messages"
    responses.add(responses.POST, url, status=429)
    responses.add(responses.POST, url, status=202)
    send_with_retry("+12125550199", "Hi", key="k-1")
    keys = [c.request.headers["Idempotency-Key"] for c in responses.calls]
    assert keys == ["k-1", "k-1"]

In Go, use httptest.NewServer and point your base URL at it. In JavaScript, MSW intercepts fetch. Cover each branch of your policy: 2xx, 429, 5xx, a timeout, a 409 quiet-hours refusal and a plain 4xx that must not be retried. The retries guide lists the branches.

Layer 3: one contract test

A test key simulates every send with no card, number or charge, so it's safe to run in CI. Send one text, assert you get an accepted status back, and stop. Don't assert on message text or timing. This test exists to tell you when the provider's request shape or your credentials drift, so run it nightly, not on every commit. Our sandbox guide covers the options.

What not to mock

Don't mock the clock in a way that hides quiet-hours logic from your tests, and don't assert on the exact wording of provider error text. Assert on status codes and the codes the docs list, and read the error docs for those.

FAQ

Should I mock the provider's SDK or the HTTP layer?

Mock the HTTP layer if you call REST directly, because your client code is then under test. Mock a wrapper interface of your own if you want tests that don't care how sends happen.

Is a contract test worth it?

Yes, one is. It's the only layer that fails when a header name or auth rule changes under you.

Will a test key text real phones?

No. A test key simulates send requests and refuses anything that would change or bill an account.

The short version

A fake for logic, an HTTP stub for the client, a nightly test-key call for the shape. The messages API docs hold the request reference.

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.