region: 'us' (default) or region: 'eu'. Things to know before you send:
- Real mail costs real money.
postcards.create,letters.create,letters.postandsms.createspend from the balance unless you passtest: true, which renders a PDF proof (or builds the SMS) without posting or charging; test mailpieces come back with id 0.campaigns.bookandaccount.topuphave no test mode: they always charge. All of these aredestructive, so they need approval. - Sending takes two steps for campaigns.
campaigns.createbuilds a draft for a group;campaigns.approvelocks it (this cannot be undone) andcampaigns.bookschedules dispatch and takes payment. Mailpieces send immediately on create unlesstestis set, and can be cancelled withpostcards.cancel/letters.cancelonly before processing starts. - Idempotent sends. The create and book operations accept an
idempotencyKey, sent as theX-Idempotency-Keyheader. A repeat call with the same key and body returns the original response with HTTP 409 instead of running again; the original body is onerror.bodyof the thrownStannpAPIError. - Recipient ids are strings in lists and numbers in mailpiece reads. Stannp returns
"id": "1943"for recipients, groups and campaigns but numeric ids for mailpieces; the schemas keep both as documented. - Paging.
recipients.listandgroups.listpage withoffsetandlimit. Reporting pages by date range (reporting.summary,reporting.list). - Rate limits. Paid plans allow 300 requests per minute or more; the free plan allows 10. Responses carry
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset(seconds until the window resets); the plugin reads the reset header and retries a 429 up to three times with backoff. - Webhooks are created in the Stannp platform, not through the API (account settings, webhooks page). On creation Stannp sends a validation POST (
event: "test_url") that must answer HTTP 200, whichwebhooks.testUrlhandles. Set a secret on the webhook to enable signing: deliveries then carry an HMAC-SHA256 signature inX-Stannp-Signature, which the plugin verifies. Give Corsair the same secret (thewebhookSecretoption or the stored webhook signature): with no secret on the Corsair side, deliveries are accepted unverified, matching Stannp’s optional signing. A stored secret that cannot be read rejects the delivery. - Binary uploads. File parameters accept the documented URL and base64 forms; binary multipart bodies are not exposed.
- Under the hood. All requests use HTTP Basic auth with the API key as the username and an empty password, over HTTPS. Every v1 response is wrapped in
{ "success": true, "data": ... }or{ "success": false, "error": "..." }; a 200 body that still says error throws. Two documented operations are left out:qrcode/create(needs a separate public key and returns a binary JPEG) andPOST /v2/balance(a separate API style;account.topupon/v1/accounts/topupis implemented instead).
- 41 typed API operations
- 4 incoming webhook event types
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Stannp API key before the first call: More: API Key
pnpm corsair setup --plugin=stannp --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Get a postcard by idWebhooks
This plugin registers 4 webhook event types. Configure the provider to POST to your Corsair HTTP handler, then usewebhookHooks on the plugin factory.
See Webhooks for every event path and payload shape, and Webhooks concept for routing.
What’s next
API reference
Every
stannp.api.* operation with input and output types.Webhooks
Event paths, payloads, and
webhookHooks examples.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.