STACK
MENU
DOCS / THE ACCOUNT / STREET ADDRESS

Street address

How you connect a US street address to the account, and how an agent reads the post that arrives and asks for it to be scanned, forwarded or shredded. What the address is and what it costs is on Services.

Before you start

The account has one address, shared by all of your agents. Each agent has its own line on it. The address is yours at the supplier, mailbox.bot, and you set it up there once:

  • Sign up at the supplier.
  • Complete USPS Form 1583: two IDs and a short notary video call. STACK never sees the documents.
  • Create an agent key at the supplier.

You need to be the owner or an admin for the steps in the next section.

Connect the address

prompt
Start a street address for my STACK account.

The client calls stack_start_postal_address and returns the supplier's sign-up page. When you have the agent key, connect it from the terminal. The key is read from a hidden prompt and never passes through a chat:

bash
npx @getstackrun/cli post address connect

From code, the same step is stack.post.connectAddress({ api_key }).

The address is usable when its status is active. Ask stack_get_postal_address for the status, or stack_refresh_postal_address to check with the supplier now.

Only an agent key is accepted. A test key, or a key of your own login at the supplier, is refused with 400 POSTAL_KEY_REFUSED.

Read the post that arrives

prompt
What post has arrived for the assistant account?

The client calls stack_list_account_postal_items, then stack_get_account_postal_item for one item. From code: stack.post.listAccountItems('acct_123'). From the terminal: post acct_123 items.

  • An item goes to the agent whose line is on the envelope.
  • An item that names no agent is offered to every agent of the account. The first to ask for a scan, forward or shred takes it.
  • stack_get_account_postal_address returns the agent's own line of the address, to put on a form.
  • You can assign such an item yourself: stack_assign_postal_item, or post items assign <item-id> --account <id>.

Scan, forward or shred

prompt
Scan the letter that arrived today and tell me what it says.
typescript
await stack.post.scanItem('acct_123', 'pit_abc', { capture: 'document_pdf' }, { passportToken });

await stack.post.forwardItem('acct_123', 'pit_abc', {
  destination: { name: 'Anna Berg', line1: '1 Main St', city: 'Reno', state: 'NV', postal_code: '89501' },
}, { passportToken });

await stack.post.shredItem('acct_123', 'pit_abc', { passportToken });
  • The tools are stack_scan_postal_item, stack_forward_postal_item and stack_shred_postal_item. Shred requires confirm: true.
  • Each request is only proposed. You approve it at the supplier, and the supplier bills your account there.
  • The text of a finished scan arrives as a message of the account, on the channel post.
  • A forward goes to a US address only.
  • Each request is one action. Reading the address and the items is free.

Pause or disconnect

stack_pause_postal_address and stack_resume_postal_address stop and restart requests. stack_close_postal_address disconnects: STACK forgets the key and the mailbox details, and keeps the items and scans already received. The mailbox stays yours at the supplier.

When a request is refused

  • 409 POSTAL_ADDRESS_NOT_ACTIVE - there is no address, or its status is pending_identity, suspended or closed. A suspended address was paused by you, or suspended by the supplier.
  • 409 POSTAL_ITEM_TAKEN - another agent took the item first.
  • 503 POST_UNAVAILABLE - the supplier cannot be reached. Nothing was charged.
  • 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as post.scan, post.forward or post.shred.

Reference

Every field is on Post. Every tool is in the tool reference. To send post, see Letters and postcards.

Street address | Docs