X-Api-Key header. A key starting ep_live_ sends real cards. A key starting ep_test_ is a sandbox key: its cards, contacts and groups are stored apart and are never printed or billed, so use one while building.
Things to know:
- Creating a card sends a postcard and costs money.
cards.createandcards.createFromTemplateprint and post a card to every recipient and bill the account per card, so they aredestructive; with a permissions mode such aspermissions: { mode: 'cautious' }they wait for approval. Checkaccount.creditsfirst. - Recipients. Pass saved contacts in
recipient_ids, whole groups ingroup_ids, or new postal addresses inrecipients.{anrede}in the text becomes each recipient’s salutation (seegreeting_styleon a contact). - Motives. A motive is the front design.
motives.getsays which text fields it allows (content_available,content_ps_available,vertical_text_available); text the motive does not allow is refused with 422. - Check the text first.
cards.previewFitsays whether the text fits at a font and size, and suggests a size when it does not. It creates nothing. - Delivery.
deliver_attakesYYYY-MM-DD,today,asap,tomorroworN-days-from-now, at most 90 days out; weekends and printer holidays move to the next print date unlessmove_to_next_print_dateis false. - Cancelling.
cards.cancelworks while the card is stillcancelable; it runs asynchronously and cannot be undone. - Errors are RFC 7807 problem details; a failed call drops its request body (names, addresses) from the error. Events log ids only.
- 22 typed API operations
- 1 synced entity (
templates) for fast.search()/.list()
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 Echtpost API key before the first call: More: API Key
pnpm corsair setup --plugin=echtpost --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
List scheduled cardsQuery synced data
Synced entities supporttenant.echtpost.db.<entity>.search() and .list(): templates.
See Database for filters and operators.
What’s next
API reference
Every
echtpost.api.* operation with input and output types.Database
Synced entities, search filters, and operators.
Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.