The Stannp Letters API does something most APIs never have to do: it puts paper in a postbox. It has four operations. You can create a letter from a template or HTML, post a pre-merged PDF, get a letter, and cancel one before it ships. Of the seven APIs Stannp has on the network, it is the one where a mistake costs postage. It is also the one where Stannp already built the safety rail an agent needs most. Our record of it does not show that.
What it ships
| Operation | Method and path | Effect |
|---|---|---|
| createLetter | POST /letters/create | write |
| postLetter | POST /letters/post | write |
| getLetter | GET /letters/get/{id} | read |
| cancelLetter | POST /letters/cancel | destructive |
Both write operations take a test boolean. In the contract’s words, it produces a “sample PDF without dispatch or charges.” createLetter also takes an idempotency_key “for safe request retries.” So a caller can preview a real mailpiece for free and retry a send without paying for it twice. For a physical, billable action, those are the two properties that matter most. The artifact set has the OpenAPI, an overlay, three JSON Schemas (recipient, mailpiece, campaign), a vocabulary and a JSON-LD context. The Agent Skill (“send a transactional letter”) and the conversational phrasing were generated by API Evangelist, so Stannp gets no credit for them here.
Stannp scores 74.5 overall, exemplar (76.1 at the previous run). Its Agent Readiness is 38.6, agent-ready. All seven contracts score as callable, and none of them is marked as derived.
The sharp part
The Agent Readiness record has dry_run_mode: false. The contract has a documented test=true that skips dispatch and charges. That is a dry-run mode in every sense an agent cares about. The rubric looks for one under a convention Stannp does not use, so it reads as missing. Either the detector should learn the parameter, or the check is measuring a name rather than a capability. In either case the defect is in our rubric, not in Stannp’s API.
There are two smaller issues, and both are ours as well. The record lists auth_clarity as bearer, but the contract declares HTTP Basic auth with the API key. And every Stannp API page shows api-eu1.stannp.com as its base URL, while the contract lists the US server first and the page’s own entry base is api-us1.stannp.com. For a mail API that is a real problem, because the region decides which country’s postal network carries the letter. The letter size enum offers only US-LETTER and US-LETTER-XL-WINDOW.
The contract has gaps that belong to Stannp, too. postLetter takes a test flag but no idempotency_key, so a retried PDF send could post twice. And cancelLetter does not say how long after creation a letter can still be stopped.
Takeaway
Stannp could add idempotency_key to postLetter and give a cancellation window on cancelLetter. We need to recognise test as a dry run, read the auth scheme from the contract, and stop displaying the EU host for a contract that defaults to the US. Stannp has already done the hard part. The record just has to catch up with it.
See the API at apis.io/apis/stannp/stannp-letters-api/ and Stannp’s own guide at stannp.com/us/direct-mail-api/guide.