Physical Mail Integration Testing With a Lob API Simulator
A local stateful simulator lets you test full mail lifecycles safely.

Integration testing against stateful APIs requires a local simulator that preserves state across calls, so tests can assert the consequences of an operation across responses. For Lob, that means exercising creation, retrieval, cancellation, idempotency, and asynchronous events without contacting live mail-producing endpoints. A stateful Lob API simulator removes the risk of printing and shipping real mail while testing whether the integration handles the full lifecycle correctly.
Why physical mail API calls occupy a different risk category than other API integrations
A CI pipeline can finish successfully while real mail is already moving through the USPS mailstream. That is a structural consequence of calling a live physical mail API. The application requested an action, and the service performed it. A misfired Stripe charge can be voided or refunded, but a retry, rollback, or refund cannot recall a printed letter already in transit.
Lob supports postcards, letters, checks, self mailers, snap packs, and booklets, each with downstream costs once production begins. A check sent to the wrong address is a financial instrument in the wild. Even Lob’s own engineers had to work carefully around their production system during controlled load testing to avoid creating real mailpieces. The distinction is therefore not between careful and careless callers, but between tests that can trigger physical fulfillment and tests that cannot.
What the Lob API's lifecycle actually looks like — and why a test must exercise all of it
Lob’s API documentation exposes distinct Create, Retrieve, Cancel or Delete, and List endpoints for its mailpiece resources, including letters, postcards, and checks. Creation is only the start of the contract. A test must establish that a resource can be found afterward and that cancellation changes what subsequent calls observe. Checks add a related lifecycle through Bank Accounts endpoints for Create, Verify, Retrieve, Delete, and List. A test that cancels a check must also check that the state of its bank account is still correct.
Time and request history complicate that sequence. The documentation includes a Cancellation Windows management surface, so the same cancellation request can produce different results at different points in a mailpiece’s lifecycle. Idempotency is also documented, and how it works depends on earlier requests. To judge a repeated create request correctly, the test must know whether its idempotency key has already been used. Webhooks and tracking events extend the contract beyond synchronous responses into production and delivery updates.
US verifications, international verifications, US autocomplete, and reverse geocode lookups are distinct endpoint groups. Their role is not limited to accepting valid addresses. Normalization and soft-verification results can change how mail is routed later without causing an HTTP error. Full lifecycle coverage therefore includes both the mailpiece’s changing state and address decisions about whether to create it.
How do you test APIs where order of operations matters without stateless mocks?
A fixed-response mock answers each call without reference to earlier calls. It cannot distinguish a cancellation for a newly created mailpiece from one whose cancellation window has passed. Both requests reach the same fixture. As a result, a passing cancellation test may establish only that the application accepts a canned response.
A second create call with the same idempotency key must be interpreted in light of the first, but a history-blind stub cannot reveal duplicate-send bugs. To test a tracking event that arrives before a creation webhook, the test needs an event sequence that a fixed-response stub does not keep. Likewise, a static successful verification response cannot test the routing branch that a soft failure causes mid-campaign.
The expensive failures include a check that cannot be canceled because the integration assumes cancellation always succeeds, or a duplicate postcard run because repeated requests were never tested. A fixture can illustrate an expected response without proving the transition that produced it. To test those transitions, something must remember state across calls within a session, run locally, and never touch a live endpoint.
How a stateful Lob simulator eliminates the irreversibility risk while enabling the full lifecycle
A locally hosted, stateful simulator gives the application a persistent world for each test session without connecting that world to printing or shipping. Creating a letter adds a resource that later List and Retrieve calls can observe. Canceling it changes what the next retrieval returns. Each call sees the state left by earlier calls.
Repeating a create request with the same idempotency key can return the existing resource. Representing a mailpiece as past its cancellation window lets the test assert that the application handles rejection correctly. For checks, a session can create and verify a bank account, create a check against it, and cancel the check while inspecting the relevant state. The session then resets cleanly.
These capabilities define what the simulator must implement. Hosting a fixed-response server locally does not make it stateful, and keeping state alone does not make it follow cancellation or idempotency semantics. The safety boundary also depends on configuration. With the client directed at the local simulator and live credentials removed from CI, ordinary integration runs have no path to producing physical mail.
Running Lob integration tests in CI without coupling builds to live endpoints
Lob’s engineers encountered a limitation of test mode during internal load testing because “creating mail in test mode doesn't kick off certain systems” they needed to exercise. Their production testing required safeguards against real fulfillment. Teams that build integrations face the same difference between getting a successful test response and testing realistic stateful flows. A local simulator provides those flows for application tests without requiring every build to depend on live production behavior.
In practice, the configuration change is compact. Instead of supplying a live base URL and live credentials, the pipeline starts a simulator container with the test suite and directs the client’s base URL to localhost. Tests create, retrieve, list, and cancel mailpieces before the container is torn down. No live credentials enter that test environment. Each parallel worker can run its own fresh instance, preventing resources created by one test run from contaminating another.
This also removes live rate-limit quota from routine builds. Lob documents rate limiting, but a local instance does not consume that quota or make the build wait on a live endpoint. Controlled tests can still simulate throttling when it is relevant. The separation is especially important for Campaigns, which ingests audience files and creates mailpieces at scale. A runaway local test can test that high-volume path through the application without turning its requests into physical mail.
Fault injection for the quiet failures that physical mail testing most commonly misses
The AgentChaos paper, published in August 2026, injected faults into five agent architectures across 65 fault configurations and found that the most damaging faults returned a normal HTTP 200. Existing diagnosis tools caught those faults only a small fraction of the time. The relevant insight extends beyond agent architecture. Transport success does not establish that the requested work succeeded, so testing only non-success HTTP responses leaves a significant blind spot.
For a Lob integration, the corresponding fault is a print-partner routing error that returns 200 while setting the mailpiece status to failed. Monitoring based only on HTTP errors misses the failure. A simulator that injects this response lets a test establish whether the application reads the resource status and recognizes that the requested work failed. Soft address verification failures deserve the same treatment because they can silently change which addresses proceed through a campaign.
Out-of-order webhooks let tests assess whether event handlers are idempotent and independent of arrival order. With latency injection and on-demand 429 responses, tests can check how Campaigns handles backpressure without using up a real quota. A campaign that creates millions of mailpieces needs that behavior even when the usual tests run quickly. Fault injection makes adverse conditions deliberate test inputs rather than incidents the team must wait to encounter.
Why a simulator that is not continuously verified against the live Lob API will silently drift
A simulator can keep state perfectly and still get the behavior wrong. Lob’s documentation is versioned, its changelog is being renovated, and its routing system was rebuilt during the period covered by the supplied material. A simulator built around an earlier contract can continue accepting request shapes that the live API rejects. The test stays green while the first production call exposes the mismatch.
Neither specification-derived nor handwritten mocks escape this problem automatically. The former inherit the accuracy of the OpenAPI document, while the latter inherit the accuracy of the implementation’s assumptions. Months of passing tests do not establish fidelity. Without comparison against the live API, they establish only that the application and the substitute still agree with each other.
A scheduled drift probe compares live API responses with the simulator’s contract. That verification is separate from ordinary isolated integration runs, which remain directed at local instances without live credentials. Because the probe contacts the real service, it retains the physical-mail risk that routine tests avoid. Its results must expose divergences before they become false passes in application tests. Continuous comparison, rather than an unchanged fixture library, is the basis for trusting the simulator over time.
Using the Lob simulator as an RL environment for agents that call physical mail APIs
An agent that uses Lob as a tool needs the same state continuity as a conventional integration test. Its outputs may be non-deterministic, but the environment must still respond coherently to its actions. Otherwise, a failed run cannot be distinguished from a correct sequence encountering a stale fixture. Reinforcement learning adds requirements for deterministic state control and horizontal scalability so that repeated runs remain interpretable and independent.
An agent can compose a letter, verify an address, create a mailpiece, retrieve its status, and cancel it if needed. The simulator changes state after each action that affects it. A reward function can then score schema validity, address normalization, and idempotency handling against that state without producing physical mail.
Simia-RL, published in 2025, demonstrates the LLM-as-environment-simulator pattern for agent training without real environment implementations. The relevant principle for Lob is the separation of training from consequential live actions, while retaining realistic responses and enforced state. Thousands of rollouts make that separation operationally important. Multiple container instances, each with its own state, let training scale without hitting live rate-limit limits or paying mail costs, as long as the simulated contract stays true to the live one.
What a correct Lob simulator setup looks like end to end
The practical setup begins with an isolated local simulator and realistic pre-seeded addresses, mailpieces, and bank accounts. Those resources give tests a place to start without each test having to build its own fixtures. CI directs the application to that instance without live credentials. Each parallel worker has its own instance, and session resets keep earlier runs from changing the results of later ones.
The test suite then traverses each mailpiece type’s lifecycle. It asserts state after creation, retrieval, listing, cancellation within the window, cancellation outside it, and an idempotent duplicate create. Fault configuration adds soft address verification failures, out-of-order webhooks, a 429 on the Campaigns ingest endpoint, and a 200 response whose mailpiece status is failed. Each case asserts the application’s response to the condition. A scheduled live drift probe separately checks whether the simulator’s contract still matches Lob’s behavior.
Local isolation prevents fulfillment, stateful lifecycle tests expose sequencing errors, fault injection exercises quiet failure paths, and drift verification challenges the substitute’s accuracy. A team that leaves CI connected to live mail-producing endpoints remains one misconfiguration away from real mail in the mailstream.


