Post API
The street address, the post that arrives, and letters and postcards sent. The steps are in the Street address and Letters and postcards guides.
Post
Your agents get a US street address that receives post, and can send letters and postcards. The address is yours: you sign up at the address supplier (mailbox.bot) as its renter, complete the supplier's own identity step there (USPS Form 1583: two IDs and a short notary video call) and create an agent key there. STACK never collects or sees the identity documents. You give STACK that key once; it is stored encrypted and never returned. One address per customer: the post for an agent carries that agent's own line on the envelope, and arrives as a message of the account with channel post.
Getting the address, step by step. The mailbox is provided by mailbox.bot, not by STACK, and STACK earns a referral fee when you sign up through https://mailbox.bot/signup?intent=mailbox&ref=stack. Sign up there with your own details, complete the USPS Form 1583 (mailbox.bot includes its own online notary step for it), then create an agent key in your mailbox.bot dashboard (a key that starts with sk_agent_, never the account-wide sk_live_ key) and give it to STACK on the one-time page your assistant links you to. Post must be addressed to you, or to a business named on your Form 1583, with your private mailbox number on the street line written "PMB", never "#".
Your street address (owner or admin)
- GET /v1/post/address - status (pending_identity, active, suspended, closed), the address once issued, identity.url (the supplier page for your steps) and the webhook address the supplier should call. 404 before you start one.
- POST /v1/post/address - start the address. Returns identity.url.
- POST /v1/post/address/connect - { api_key, webhook_secret? }. The agent-scoped key you created at the supplier. A sandbox key and the supplier's account-wide key are refused. Never through a chat tool: use the CLI (stdin), the SDK or the Console.
- POST /v1/post/address/refresh | pause | resume and DELETE /v1/post/address - look at the supplier again, pause, lift your own pause, disconnect. Disconnecting deletes the supplier key and the mailbox details STACK held (its address and private mailbox number); your mailbox at the supplier is untouched and every item and scan you already received stays.
- GET /v1/post/items?limit&cursor&routing - every item at the address. routing is routed, pending or unassigned (an item that names no agent is offered to every agent of the account until one takes it).
- POST /v1/post/items/:itemId/assign - { account_id }. Give an item that no agent has taken to an account.
An account's post
- GET /v1/accounts/:id/post/address - the agent's own line on the address, to print on a form.
- GET /v1/accounts/:id/post/items?limit&cursor and GET /v1/accounts/:id/post/items/:itemId - the post that arrived, with each request made for it.
- POST /v1/accounts/:id/post/items/:itemId/scan - { capture?: document_pdf | contents_photos | both }. Returns 202.
- POST /v1/accounts/:id/post/items/:itemId/forward - { destination, mail_class? }. A US address. Returns 202.
- POST /v1/accounts/:id/post/items/:itemId/shred - { confirm: true }. It cannot be undone. Returns 202.
- POST /v1/accounts/:id/post/address-check - { address }. Whether the address is deliverable, and how the provider standardises it.
- POST /v1/accounts/:id/post/letters - a letter ({ to, sender_name, content: { text } | { pdf_base64 }, use_type, color?, double_sided?, mail_class?, extra_service?, idempotency_key?, description? }) or a postcard ({ kind: "postcard", to, sender_name, front: { text }, back: { text }, use_type, size? }). 201 when the provider took it, 202 while it has not answered yet, 200 for a repeat of a request already made.
- GET /v1/accounts/:id/post/letters?limit&cursor and GET /v1/accounts/:id/post/letters/:letterId - letters with their state and tracking events.
A scan, forward or shred is only proposed: you approve it at the supplier, who bills your own account there. The text read from a scan arrives as a message of the account and is scanned for prompt injection like any inbound message. A letter or postcard is held on the account's credit at the provider's price, charged at cost when the provider accepts it, and released when it does not. Each is one action under your controls (kinds letter.send, post.scan, post.forward and post.shred) and is in the account's record with a hash of the content. use_type is required on a send: operational, or marketing for promotion. So is sender_name, the name on the return address above the agent's line (up to 40 characters). What a letter may say is the print provider's to judge: its refusal comes back as provider_refused.
- 400 or 422 POST_REFUSED - details.reason: address_undeliverable, pdf_unreadable, too_many_pages or provider_refused. Nothing is held or charged.
- 409 POSTAL_ADDRESS_NOT_ACTIVE - details.status: none, pending_identity or suspended.
- 503 POST_UNAVAILABLE - the letter provider is down on STACK's side. Nothing is charged.
- 402 AGENT_BUDGET_EXCEEDED - the credit cannot cover the letter.