Skip to main content
Use Stannp through Corsair: one client, typed API calls, and incoming webhooks. Create your API key at the bottom of the settings page in Stannp. US and Canadian accounts use the api-us1 host and EU/UK accounts api-eu1; build the plugin with region: 'us' (default) or region: 'eu'. Things to know before you send:
  • Real mail costs real money. postcards.create, letters.create, letters.post and sms.create spend from the balance unless you pass test: true, which renders a PDF proof (or builds the SMS) without posting or charging; test mailpieces come back with id 0. campaigns.book and account.topup have no test mode: they always charge. All of these are destructive, so they need approval.
  • Sending takes two steps for campaigns. campaigns.create builds a draft for a group; campaigns.approve locks it (this cannot be undone) and campaigns.book schedules dispatch and takes payment. Mailpieces send immediately on create unless test is set, and can be cancelled with postcards.cancel / letters.cancel only before processing starts.
  • Idempotent sends. The create and book operations accept an idempotencyKey, sent as the X-Idempotency-Key header. A repeat call with the same key and body returns the original response with HTTP 409 instead of running again; the original body is on error.body of the thrown StannpAPIError.
  • 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.list and groups.list page with offset and limit. 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-Remaining and X-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, which webhooks.testUrl handles. Set a secret on the webhook to enable signing: deliveries then carry an HMAC-SHA256 signature in X-Stannp-Signature, which the plugin verifies. Give Corsair the same secret (the webhookSecret option 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) and POST /v2/balance (a separate API style; account.topup on /v1/accounts/topup is implemented instead).
What you get:
  • 41 typed API operations
  • 4 incoming webhook event types

Setup

1

Install

2

Add the plugin

corsair.ts
With multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.
3

Choose authentication

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 id
Send a test letter to a new recipient
See the full list on the API page.

Webhooks

This plugin registers 4 webhook event types. Configure the provider to POST to your Corsair HTTP handler, then use webhookHooks 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.