# 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](/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

```text
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

```text
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

```text
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](/docs/api/account-post). Every tool is in the [tool reference](/docs/mcp-tools). To send post, see [Letters and postcards](/docs/account/letters).
