# Dispatch Docs

This file is the LLM-ready plain text version of the Dispatch documentation. It is generated from the docs source at build time.

Canonical docs: https://docs.dispatchjoin.com/
LLM copy page: https://docs.dispatchjoin.com/llms.txt

## Page Index

- [Dispatch Docs](https://docs.dispatchjoin.com/) - Set up a programmable inbox, claim it into the web app, and use it from CLI or Mail Desk.
- [Overview](https://docs.dispatchjoin.com/getting-started/overview/) - What Dispatch is, how the CLI and web app fit together, and what to do first.
- [Choose Your Path](https://docs.dispatchjoin.com/getting-started/choose-your-path/) - Pick the Dispatch setup route that matches where you are starting.
- [Quickstart](https://docs.dispatchjoin.com/getting-started/quickstart/) - Create, claim, and use your first Dispatch inbox.
- [Create an Inbox](https://docs.dispatchjoin.com/getting-started/create-inbox/) - Provision, select, and manage Dispatch inboxes from the CLI.
- [Claim Inbox in Web](https://docs.dispatchjoin.com/getting-started/claim-inbox/) - Attach a CLI-created inbox to your Dispatch web account.
- [Read and Search Mail](https://docs.dispatchjoin.com/workflows/read-search-mail/) - View inbox messages, watch for new mail, and move between CLI and Mail Desk.
- [Extract Codes and Links](https://docs.dispatchjoin.com/workflows/extract-otp/) - Pull one-time passcodes and links from inbound messages.
- [Send Mail](https://docs.dispatchjoin.com/workflows/send-mail/) - Send outbound email from your selected Dispatch inbox.
- [Plans and Usage](https://docs.dispatchjoin.com/account/plans-and-usage/) - Understand workspace limits, Stripe checkout, x402 payments, and billing verification.
- [x402 Examples](https://docs.dispatchjoin.com/account/x402-examples/) - Practical wallet-backed payment examples for Dispatch.
- [Common Issues](https://docs.dispatchjoin.com/help/common-issues/) - Fast fixes for the most frequent Dispatch setup, billing, and workflow problems.
- [API and CLI Surface](https://docs.dispatchjoin.com/reference/api-cli/) - High-level map of Dispatch commands, API areas, keys, and web surfaces.
- [Repository Map](https://docs.dispatchjoin.com/reference/repo-map/) - Quick map of major directories and responsibilities.

---

## Dispatch Docs

Source: https://docs.dispatchjoin.com/
Description: Set up a programmable inbox, claim it into the web app, and use it from CLI or Mail Desk.

Dispatch gives developers and teams programmable inboxes that work from both CLI and web. Start with the quickstart if you are new, or jump straight to the workflow you need.

## Start Here

- [First inbox](https://docs.dispatchjoin.com/getting-started/quickstart/) - Install the CLI, create an inbox, claim it in the web app, and verify mail access.
- [Claim an existing inbox](https://docs.dispatchjoin.com/getting-started/claim-inbox/) - Attach a CLI-created inbox to your Dispatch account.
- [Wallet sign in](https://docs.dispatchjoin.com/account/x402-examples/#recovery-and-claiming) - Recover a wallet-funded inbox and use the wallet as the identity proof.
- [Extract codes and links](https://docs.dispatchjoin.com/workflows/extract-otp/) - Find a recent message and pull out the useful code or link.
- [Plans and usage](https://docs.dispatchjoin.com/account/plans-and-usage/) - Check inbox limits, Stripe upgrades, and x402 payment behavior.

## Recommended Setup

1. Install the CLI.
2. Create or connect a Dispatch inbox.
3. Claim the inbox into your web account.
4. Receive test mail and extract a code.
5. Open Mail Desk when you need message review or replies.
6. Upgrade only when you need more inbox capacity.

## Common Workflows

- [Create an Inbox](https://docs.dispatchjoin.com/getting-started/create-inbox/)
- [Read and Search Mail](https://docs.dispatchjoin.com/workflows/read-search-mail/)
- [Send Mail](https://docs.dispatchjoin.com/workflows/send-mail/)
- [x402 Examples](https://docs.dispatchjoin.com/account/x402-examples/)
- [Common Issues](https://docs.dispatchjoin.com/help/common-issues/)
- [API and CLI Surface](https://docs.dispatchjoin.com/reference/api-cli/)

---

## Overview

Source: https://docs.dispatchjoin.com/getting-started/overview/
Description: What Dispatch is, how the CLI and web app fit together, and what to do first.

Dispatch is a hosted inbox control plane for developer workflows. It gives you real inboxes that can be created from the CLI, claimed into a web account, read from scripts, used for code and link extraction, and operated from Mail Desk.

## What Dispatch Gives You

- A workspace that owns inboxes and billing state.
- One or more hosted inbox addresses.
- A workspace key for account-level operations such as listing inboxes, billing, and creating additional inboxes.
- Inbox keys for mail operations such as listing messages, extracting codes and links, and sending replies.
- A web account for ownership, recovery, Mail Desk, Billing, and support.

## How the Pieces Fit

```text
CLI install
  -> dispatch inbox create
  -> workspace + inbox keys saved locally
  -> dispatch inbox claim --open
  -> web account owns the workspace
  -> Mail Desk, Billing, and support flows are available
```

The CLI is the fastest setup and automation surface. The web app is the ownership and operations surface.

## The Default Happy Path

1. Install the CLI.
2. Run `dispatch inbox create`.
3. Run `dispatch inbox claim --open`.
4. Finish account signup or sign-in in the browser.
5. Send a test email to the new inbox.
6. Run `dispatch mail code`, `dispatch mail link`, or open Mail Desk.

If you are starting somewhere else, use [Choose Your Path](https://docs.dispatchjoin.com/getting-started/choose-your-path/).

## What to Read Next

- [Quickstart](https://docs.dispatchjoin.com/getting-started/quickstart/) for the full first-inbox flow.
- [Create an Inbox](https://docs.dispatchjoin.com/getting-started/create-inbox/) for inbox naming, selection, and keys.
- [Claim Inbox in Web](https://docs.dispatchjoin.com/getting-started/claim-inbox/) for linking CLI work to your account.
- [Plans and Usage](https://docs.dispatchjoin.com/account/plans-and-usage/) before adding team-scale inbox capacity.

---

## Choose Your Path

Source: https://docs.dispatchjoin.com/getting-started/choose-your-path/
Description: Pick the Dispatch setup route that matches where you are starting.

Use this page when you are not sure whether to begin in the CLI, the web app, or billing.

## Path 1: First Inbox

Best when you are new to Dispatch and want a working inbox as fast as possible.

```bash
/bin/bash -c "$(curl -fsSL https://get.dispatchjoin.com/install_dispatch.sh)"
dispatch inbox create
dispatch inbox claim --open
```

You should end with:

- a workspace key saved in local CLI config
- a selected inbox
- an inbox key for mail commands
- a claim link that attaches the inbox to your web account

Continue with [Quickstart](https://docs.dispatchjoin.com/getting-started/quickstart/).

## Path 2: Existing CLI Inbox

Best when an inbox already exists on your machine and you want it visible in the web app.

```bash
dispatch inbox show
dispatch inbox claim --open
```

Sign in or create an account in the browser, then finish the claim flow. After that, use Mail Desk for reading and replies, and Billing for plan state.

Continue with [Claim Inbox in Web](https://docs.dispatchjoin.com/getting-started/claim-inbox/).

## Path 3: Waiting for a Verification Code

Best when the inbox is already selected and you need the newest verification code or link.

```bash
dispatch mail tail
dispatch mail code
dispatch mail link
```

If nothing appears, check the sender, the selected inbox, and the spam folder.

Continue with [Extract Codes and Links](https://docs.dispatchjoin.com/workflows/extract-otp/).

## Path 4: More Inboxes or Team Capacity

Best when `dispatch inbox create` fails because the workspace needs paid capacity.

Use the web app for the simplest Stripe path:

1. Open Billing.
2. Choose the Team 1000 upgrade.
3. Complete Stripe Checkout.
4. Return to Dispatch and refresh Billing.
5. Retry `dispatch inbox create`.

Use CLI wallet autopay when you want x402:

```bash
dispatch inbox create team --swarm --private-key-path ~/.config/dispatch/wallet.key
```

Continue with [Plans and Usage](https://docs.dispatchjoin.com/account/plans-and-usage/) or [x402 Examples](https://docs.dispatchjoin.com/account/x402-examples/).

## Path 5: Account Recovery

Best when you lost local CLI config or need to regain access.

- If you remember your account password, sign in at `https://dispatchjoin.com/signup`.
- If you forgot it, use `https://dispatchjoin.com/reset-password`.
- If the inbox was funded by a wallet and you need web access, open `https://dispatchjoin.com/signup?mode=wallet`, choose **Use wallet**, connect the funding wallet, and sign the recovery message.
- If the inbox was funded by a wallet and you need CLI access, recover with the same funding wallet:

```bash
dispatch auth wallet --private-key-path ~/.config/dispatch/wallet.key
```

Use `https://dispatchjoin.com/support` for billing, privacy, export, abuse, or account closure requests.

---

## Quickstart

Source: https://docs.dispatchjoin.com/getting-started/quickstart/
Description: Create, claim, and use your first Dispatch inbox.

This is the recommended first run. It creates an inbox, saves CLI credentials locally, links the inbox to your web account, and proves that mail is flowing.

## 1. Install the CLI

```bash
/bin/bash -c "$(curl -fsSL https://get.dispatchjoin.com/install_dispatch.sh)"
```

Verify installation:

```bash
dispatch --version
```

If you are using a non-production API during development, pass `--api-url` on commands or set `DISPATCH_API_URL`.

## 2. Create Your First Inbox

```bash
dispatch inbox create my-first-inbox
```

The CLI provisions a workspace and inbox, then saves local credentials. The text output shows the workspace id, inbox id, and address. Check local state any time:

```bash
dispatch status
```

## 3. Claim the Inbox in the Web App

```bash
dispatch inbox claim --open
```

The claim link opens the Dispatch setup flow. Sign in or create an account, verify your email if prompted, then complete the link. Claiming makes the workspace visible in Mail Desk and Billing.

If the browser does not open, copy the `link_url` from the command output.

## 4. Send Mail Into the Inbox

Send a test email from any mailbox to the Dispatch address printed by `dispatch inbox create`.

Watch for it:

```bash
dispatch mail tail
```

List recent messages:

```bash
dispatch mail ls
```

## 5. Extract the Latest Code or Link

```bash
dispatch mail code
dispatch mail link
```

Use `--folder spam` if the message was filtered.

## 6. Send a Test Reply

```bash
dispatch mail reply latest --text "Hello from Dispatch"
```

## Finish State

You are ready when:

- `dispatch status` shows a workspace or inbox session.
- `dispatch inbox show` returns the selected inbox.
- `dispatch mail ls` can see inbound mail.
- The web app shows the claimed workspace.

Next: [Read and Search Mail](https://docs.dispatchjoin.com/workflows/read-search-mail/) or [Plans and Usage](https://docs.dispatchjoin.com/account/plans-and-usage/).

---

## Create an Inbox

Source: https://docs.dispatchjoin.com/getting-started/create-inbox/
Description: Provision, select, and manage Dispatch inboxes from the CLI.

Use `dispatch inbox create` when you want a new hosted inbox address. The first run creates a workspace, creates the inbox, saves a workspace key, saves an inbox key, and selects that inbox for mail commands.

## Create the First Inbox

```bash
dispatch inbox create support
```

If you omit the name, Dispatch generates a safe address:

```bash
dispatch inbox create
```

Expected result:

- workspace id
- inbox id
- inbox address
- saved workspace key
- saved inbox key
- selected inbox id

Use JSON output for scripts:

```bash
dispatch --format json inbox create support
```

## Check the Current Inbox

```bash
dispatch status
```

This confirms which inbox follow-up commands will use.

## List Inboxes

```bash
dispatch inbox ls
```

This requires workspace-level access. If you only have one inbox, create or claim it first:

```bash
dispatch inbox create
dispatch inbox claim --open
```

## Select a Different Inbox

```bash
dispatch inbox use <inbox_id>
```

Selecting an inbox also makes sure the CLI has an inbox key for that inbox.

## Create Another Inbox

```bash
dispatch inbox create qa-login
```

If additional capacity is required, the command can fail with a billing or policy error. The happy paths are:

- Complete the Team 1000 upgrade in the web Billing page, then retry.
- Use wallet-backed x402 autopay:

  ```bash
  dispatch inbox create qa-login --swarm --private-key-path ~/.config/dispatch/wallet.key
  ```

Read [Plans and Usage](https://docs.dispatchjoin.com/account/plans-and-usage/) before adding team capacity.

## Key Safety

- Treat workspace and inbox keys like passwords.
- Do not paste keys into issues, chat, screenshots, or git commits.
- Prefer `--private-key-path` over inline wallet keys so secrets do not land in shell history.
- If a key is exposed, stop using it and create a fresh session from the web app or support flow.

## Next Steps

- Claim the inbox into your account with [Claim Inbox in Web](https://docs.dispatchjoin.com/getting-started/claim-inbox/).
- Read mail with [Read and Search Mail](https://docs.dispatchjoin.com/workflows/read-search-mail/).
- Extract codes and links with [Extract Codes and Links](https://docs.dispatchjoin.com/workflows/extract-otp/).

---

## Claim Inbox in Web

Source: https://docs.dispatchjoin.com/getting-started/claim-inbox/
Description: Attach a CLI-created inbox to your Dispatch web account.

Claiming links a CLI-created inbox to a signed-in Dispatch account. Wallet recovery is a related flow: it restores a browser workspace session from the wallet that funded an inbox, without requiring an email account first. After either flow, the workspace can be managed from Mail Desk, Billing, Settings, and support flows.

## Create and Open a Claim Link

```bash
dispatch inbox claim --open
```

The CLI uses the selected inbox. If you need a specific inbox:

```bash
dispatch inbox claim <inbox_id> --open
```

If the browser does not open, copy the `link_url` from the output and paste it into a browser.

## Complete the Web Flow

1. Sign in or create a Dispatch account.
2. Verify your account email if prompted.
3. Confirm that the inbox address matches the one you intended to link.
4. Finish the claim.
5. Open Mail Desk or Billing from the top navigation.

## Verify the Claim

In the CLI:

```bash
dispatch status
```

In the web app:

- Mail Desk should show the inbox.
- Billing should show the workspace plan and entitlements.
- Settings should show workspace and inbox keys for the connected session.

## Link an Inbox Created Somewhere Else

If a teammate or automation already created the inbox, ask them for one of these:

- a claim link from `dispatch inbox claim --open`
- an inbox API key
- a workspace API key

Use the Dispatch setup page to link an existing inbox. The standard claim path asks for the inbox address and claim token. The API-key path asks for the inbox or workspace key.

## Wallet-Paid or x402 Inboxes

If the inbox was funded by an x402 wallet flow, Dispatch can use the funding wallet as an identity proof. The wallet signs a recovery or claim message locally; no private key is sent to Dispatch, and the signature is not an on-chain transaction.

### Recover in the Web App

Use this when you want to sign in directly with the wallet that funded the inbox:

1. Open `https://dispatchjoin.com/signup?mode=wallet`.
2. Choose **Use wallet**.
3. Select Ethereum or Solana.
4. Connect the wallet that paid for or verified the x402 transaction.
5. Sign the wallet recovery message.
6. If more than one recoverable inbox appears, choose the inbox you want to restore.
7. Open Mail Desk, Billing, or Settings.

A recovered wallet session receives workspace and inbox access in the browser. It is not an email-account claim; the wallet is the identity proof for the session.

### Claim Into a Dispatch Account

Use this when you are already signed in with email and want the inbox attached to that Dispatch account:

1. Sign in to Dispatch.
2. Choose the existing inbox link path.
3. Choose x402 claim.
4. Connect the funding wallet.
5. Sign the wallet proof message.
6. Claim the discovered inbox.

## If Claim Fails

- Re-run `dispatch inbox claim --open`; claim links expire.
- Confirm the selected inbox with `dispatch status`.
- Confirm you are signed into the intended web account.
- If the inbox was wallet-funded, use the same wallet that funded or verified the payment. For browser wallet sign-in, start at `https://dispatchjoin.com/signup?mode=wallet`.
- Check [Common Issues](https://docs.dispatchjoin.com/help/common-issues/).

---

## Read and Search Mail

Source: https://docs.dispatchjoin.com/workflows/read-search-mail/
Description: View inbox messages, watch for new mail, and move between CLI and Mail Desk.

Use the CLI for fast recent-message checks, scripts, and lightweight replies. Use Mail Desk when you want to inspect the full message or organize state visually.

## Confirm the Selected Inbox

```bash
dispatch inbox show
```

If the wrong inbox is selected:

```bash
dispatch inbox ls
dispatch inbox use <inbox_id>
```

## List Recent Messages

```bash
dispatch mail ls
```

Increase the page size:

```bash
dispatch mail ls --limit 50
```

Check spam or all folders:

```bash
dispatch mail ls --folder spam
dispatch mail ls --folder all
```

## Watch for New Mail

```bash
dispatch mail tail
```

Tune polling if you are waiting in a slower flow:

```bash
dispatch mail tail --poll-seconds 10 --limit 50
```

## Use JSON for Automation

```bash
dispatch --format json mail ls --limit 20
```

JSON output includes message ids, sender, subject, timestamps, and pagination cursor data where available.

## Open and Inspect Messages

The CLI is optimized for listing and extraction. For full message reading, message state, and replies, open Mail Desk in the web app after the inbox is claimed.

Recommended loop:

1. `dispatch mail tail` while waiting.
2. `dispatch mail code` or `dispatch mail link` when the message arrives.
3. `dispatch mail reply latest --text "Thanks, got it."` for a quick reply, or open Mail Desk if you need the full body.

## Common Gotchas

- `dispatch mail` commands use the selected inbox.
- Listing recent messages is not the same as server-side full-text search.
- Use `--folder spam` when a sender has poor authentication.
- If the CLI says credentials are missing, run `dispatch status`. Recreate an inbox with `dispatch inbox create`, claim it with `dispatch inbox claim --open`, or reconnect with a workspace/inbox key if you are using keys directly.

---

## Extract Codes and Links

Source: https://docs.dispatchjoin.com/workflows/extract-otp/
Description: Pull one-time passcodes and links from inbound messages.

Use this flow when a service is sending a verification email to your Dispatch inbox.

## Fastest Path

Start a watcher in one terminal:

```bash
dispatch mail tail
```

Trigger the verification email, then read the newest code:

```bash
dispatch mail code
```

## Extract Codes from Recent Mail

```bash
dispatch mail extract --kind code --first
```

Look deeper into recent history:

```bash
dispatch mail extract --kind code --limit 50
```

## Extract Links

```bash
dispatch mail link
```

Use this for magic-link sign-ins, password reset links, or invite links.

## Check Spam

```bash
dispatch mail code --folder spam
dispatch mail extract --kind code --folder spam --first
```

## Script-Friendly Output

```bash
dispatch --format json mail code
dispatch --format json mail extract --kind code --first
```

## When Nothing Is Returned

1. Confirm the selected inbox with `dispatch inbox show`.
2. Run `dispatch mail ls --folder all` to confirm the message arrived.
3. Check the sender address and target inbox address.
4. Try `--folder spam`.
5. Open Mail Desk if you need to inspect the raw body.

Dispatch extracts common verification-code patterns. If the sender uses an unusual format, list the message and read the code manually in Mail Desk.

---

## Send Mail

Source: https://docs.dispatchjoin.com/workflows/send-mail/
Description: Send outbound email from your selected Dispatch inbox.

Use `dispatch mail send` when you want the selected inbox to send a plain text or HTML message.

## Before You Send

Confirm the selected inbox:

```bash
dispatch inbox show
```

Confirm credentials:

```bash
dispatch status
```

If the wrong inbox is active, select the intended inbox:

```bash
dispatch inbox use <inbox_id>
```

## Send Plain Text

```bash
dispatch mail send user@example.com "Hello" --text "Test message"
```

## Reply to Recent Mail

```bash
dispatch mail reply latest --text "Thanks, got it."
```

Pass a message id instead of `latest` when you need to answer a specific message.

## Send HTML

```bash
dispatch mail send user@example.com "HTML test" --html "<p>Hello from <strong>Dispatch</strong></p>"
```

## Send HTML from a File

```bash
dispatch mail send user@example.com "HTML test" --html-file ./message.html
```

You must provide at least one body flag: `--text`, `--html`, or `--html-file`.

## Verify Delivery

The CLI prints a provider message id when the API accepts the send. If the recipient does not see it:

1. Confirm the recipient address.
2. Check the recipient spam folder.
3. Retry with a minimal text body.
4. Check plan or policy errors in the command output.
5. Use Mail Desk for manual reply workflows.

## Good Defaults

- Keep transactional sends short and specific.
- Use text bodies for verification and automation workflows.
- Use HTML only when the recipient needs formatting.
- Avoid sending to large or scraped recipient lists.

---

## Plans and Usage

Source: https://docs.dispatchjoin.com/account/plans-and-usage/
Description: Understand workspace limits, Stripe checkout, x402 payments, and billing verification.

Billing is attached to a Dispatch workspace. A claimed workspace can be reviewed in the web Billing page, and workspace entitlements can be listed from the CLI.

## What Usage Affects

Usage and plan state can affect:

- creating additional inboxes
- outbound send volume
- team-scale inbox capacity
- support review when something looks wrong

Your first setup path creates a workspace and inbox. Additional capacity can require a paid entitlement.

## Check Current State

Web:

1. Sign in at `https://dispatchjoin.com/signup`.
2. Open Billing.
3. Check current plan, inbox count, and entitlement history.

CLI:

```bash
dispatch billing ls
dispatch inbox ls
```

`dispatch billing list` and `dispatch billing entitlements` are aliases for the same entitlement list.

## Upgrade With Stripe

Use Stripe when you want the normal web checkout path.

1. Open Billing in the web app.
2. Choose the Team 1000 upgrade.
3. Complete Stripe Checkout.
4. Return to Dispatch.
5. Refresh Billing.
6. Retry the action that needed more capacity.

Stripe upgrades are recorded from signed webhook events. If Checkout succeeds but Billing does not update immediately, wait briefly and refresh. If it still does not update, contact support with your account email and workspace id.

## Upgrade or Confirm With x402

Use x402 when you want wallet-backed payment from the CLI or API.

Simplest CLI autopay path:

```bash
dispatch inbox create team --swarm --private-key-path ~/.config/dispatch/wallet.key
```

Manual confirmation path:

```bash
dispatch billing confirm x402.<payment_reference> \
  --product multi-inbox \
  --chain eth \
  --tx-hash 0xabc123 \
  --private-key-path ~/.config/dispatch/wallet.key
```

Read [x402 Examples](https://docs.dispatchjoin.com/account/x402-examples/) before manual confirmation. The payment id must be the quoted `payment_reference`, not the transaction hash.

## When a Command Hits a Limit

If `dispatch inbox create` or `dispatch mail send` fails with a billing or policy error:

1. Run `dispatch status` to confirm you are using the intended workspace.
2. Run `dispatch billing ls` to inspect entitlements.
3. Open Billing in the web app and refresh.
4. Upgrade with Stripe or x402 if more capacity is required.
5. Retry the original command.
6. Contact support if the payment is visible but the entitlement is missing.

## What to Include in Support Requests

Open `https://dispatchjoin.com/support` and include:

- account email
- workspace id
- inbox id or address
- payment provider: Stripe or x402
- Stripe Checkout timing or x402 transaction hash
- command output or error text

---

## x402 Examples

Source: https://docs.dispatchjoin.com/account/x402-examples/
Description: Practical wallet-backed payment examples for Dispatch.

x402 is Dispatch's wallet-backed payment path. Use it when you want the CLI to request a quote, send a payment, verify the transaction, and attach an entitlement to the current workspace.

## When to Use x402

Use x402 when:

- you want wallet-backed CLI setup instead of Stripe Checkout
- you need to create an inbox and pay in the same command
- you already sent a valid on-chain payment and need to confirm it
- you need to recover or claim a wallet-funded inbox

Use Stripe instead when you want the normal web Billing flow.

## Product Names

Public commands accept these product names:

- `agent`: wallet-backed inbox credit path
- `multi-inbox`: team or swarm capacity path

API responses may normalize those names to internal plan codes:

- `inbox_credit`
- `team_1000`

## Before You Start

- Connect a workspace key before manual billing commands:

  ```bash
  dispatch auth workspace <workspace_key>
  ```

- Prefer key files over inline secrets.
- For EVM chains, use a hex private key or a file containing that key.
- For Solana, use a standard keypair JSON file or supported secret format.
- Keep the payment reference returned by the quote; it is required for confirmation.

## One-Command Autopay

Create a wallet-backed inbox in the current or new workspace:

```bash
dispatch inbox create paid --private-key-path ~/.config/dispatch/wallet.key
```

Create another inbox and pay for multi-inbox capacity:

```bash
dispatch inbox create team --swarm --private-key-path ~/.config/dispatch/wallet.key
```

What the CLI does:

1. Requests an x402 quote from the API.
2. Signs and submits the transfer locally.
3. Confirms the transaction with the API.
4. Stores the entitlement on the workspace.
5. Retries inbox creation if billing was the blocker.

## Quote a Payment Manually

Use the API when you need to inspect the amount and recipient before sending funds:

```bash
curl -X POST https://api.dispatchjoin.com/v1/billing/x402/quote \
  -H "Authorization: Bearer <workspace_key>" \
  -H "Content-Type: application/json" \
  -d '{"product":"multi-inbox","chain":"eth"}'
```

Typical response shape:

```json
{
  "provider": "x402",
  "product": "team_1000",
  "chain": "eth",
  "payment_reference": "x402.<workspace>.<user>.<suffix>",
  "rpc_url": "https://...",
  "recipient_address": "0x...",
  "amount_base_units": "49000000000000000",
  "currency": "USDC",
  "asset_address": "0x...",
  "chain_id": "0x...",
  "mint_address": null
}
```

Use the returned `payment_reference` in the confirm step. Do not substitute the transaction hash.

## Confirm an Existing EVM Payment

```bash
PAYMENT_REFERENCE='x402.<workspace>.<user>.<suffix>'

dispatch billing confirm "$PAYMENT_REFERENCE" \
  --product multi-inbox \
  --chain eth \
  --tx-hash 0xabc123 \
  --private-key-path ~/.config/dispatch/wallet.key
```

Use `--chain base` for the same EVM-style confirmation when the transaction was sent on Base.

## Confirm an Existing Solana Payment

```bash
PAYMENT_REFERENCE='x402.<workspace>.<user>.<suffix>'

DISPATCH_SOLANA_KEYPAIR_PATH=~/.config/dispatch/solana.json \
dispatch billing confirm "$PAYMENT_REFERENCE" \
  --product agent \
  --chain solana \
  --tx-hash 5oLanaSig
```

The CLI signs the wallet confirmation message locally. You do not need to hand-build `wallet_message` or `wallet_signature`.

## Check the Result

```bash
dispatch billing ls
```

A successful confirmation returns an active entitlement for the workspace. If the workspace is later claimed into a web account, Dispatch links the entitlement and transaction verification to that account.

## Recovery and Claiming

Wallet-funded inboxes can use the funding wallet as an identity proof. The wallet signs a local message for recovery or claiming; Dispatch never receives the wallet private key, and the proof signature is not an on-chain transaction.

### Web Wallet Sign-In

Use the web wallet flow when you want Mail Desk, Billing, Settings, and other browser surfaces without first signing in with an email account:

1. Open `https://dispatchjoin.com/signup?mode=wallet`.
2. Choose **Use wallet**.
3. Select Ethereum or Solana.
4. Connect the wallet that funded or verified the x402 payment.
5. Sign the recovery message.
6. Choose the recoverable inbox if the wallet controls more than one.

This creates a browser workspace session with workspace and inbox access for the recovered agent.

### CLI Wallet Recovery

Use the CLI flow when you need local command-line access restored:

```bash
dispatch auth wallet --private-key-path ~/.config/dispatch/wallet.key
```

### Claim Into a Web Account

Use the web claim path when you are already signed in with email and want the wallet-funded inbox attached to that Dispatch account. Choose the x402 claim path, connect the same wallet, and sign the displayed proof message.

## Common x402 Mistakes

- Using the transaction hash as the payment id. Use the quote `payment_reference`.
- Confirming with a different wallet from the payer.
- Trying wallet recovery with a wallet that did not fund or verify the inbox.
- Sending less than the quoted amount.
- Sending to the wrong recipient or asset contract.
- Confirming before the transaction is finalized.
- Using an inline private key that lands in shell history.

---

## Common Issues

Source: https://docs.dispatchjoin.com/help/common-issues/
Description: Fast fixes for the most frequent Dispatch setup, billing, and workflow problems.

Use this page when a happy path breaks. Most issues come from missing local auth, the wrong selected inbox, expired claim links, or billing state that has not refreshed yet.

## CLI Not Found

Symptom:

```text
dispatch: command not found
```

Fix:

```bash
/bin/bash -c "$(curl -fsSL https://get.dispatchjoin.com/install_dispatch.sh)"
dispatch --version
```

Restart your shell if the command still is not found.

## CLI Says Credentials Are Missing

Check local auth:

```bash
dispatch status
```

Reconnect with one of:

```bash
dispatch inbox create
dispatch inbox claim --open
dispatch auth wallet --private-key-path ~/.config/dispatch/wallet.key
```

Use direct workspace or inbox keys only when you are wiring Dispatch into existing secret management.

## Wrong Inbox Is Active

```bash
dispatch inbox ls
dispatch inbox use <inbox_id>
dispatch inbox show
```

Mail commands use the selected inbox.

## Claim Link Expired

Fix:

```bash
dispatch inbox claim --open
```

Claim links are one-time and time-limited. Make sure you are signed into the intended web account before completing the claim.

## Verification Email Did Not Arrive

Fix checklist:

1. Confirm the account email was typed correctly.
2. Use the resend verification action on the setup page.
3. Check spam.
4. If mail still does not arrive, submit a request at `https://dispatchjoin.com/support`.

## Forgot Password

Fix:

1. Open `https://dispatchjoin.com/reset-password`.
2. Request a reset email.
3. Finish the reset with the emailed code.
4. Sign back in and restore or claim the inbox.

## Code Extraction Returns Nothing

Fix checklist:

```bash
dispatch inbox show
dispatch mail ls --folder all
dispatch mail code --folder spam
dispatch mail extract --kind code --limit 50
```

If the message has an unusual code format, open it in Mail Desk and read the code manually.

## Unable to Send Mail

Fix checklist:

1. Confirm the selected inbox with `dispatch inbox show`.
2. Retry with a minimal text body:

   ```bash
   dispatch mail send user@example.com "Test" --text "hello"
   ```

3. Check plan or policy errors.
4. Confirm the recipient address and spam folder.

## Additional Inbox Requires Billing

Use the simplest path first:

1. Open Billing in the web app.
2. Complete the Team 1000 Stripe upgrade.
3. Refresh Billing.
4. Retry `dispatch inbox create`.

For wallet-backed payment:

```bash
dispatch inbox create next --swarm --private-key-path ~/.config/dispatch/wallet.key
```

## Stripe Checkout Completed but Plan Did Not Update

Stripe upgrades are applied by webhook. Wait briefly, refresh Billing, then run:

```bash
dispatch billing ls
```

If the entitlement is still missing, contact support with account email, workspace id, and checkout timing.

## x402 Payment Was Sent but Confirmation Fails

Check:

- The payment id is the quote `payment_reference`, not the transaction hash.
- The `--tx-hash` is the actual on-chain transaction.
- The confirming wallet is the payer wallet.
- The transaction amount, recipient, asset, and chain match the quote.
- Solana transactions may need more time to finalize.

Then retry:

```bash
dispatch billing confirm x402.<payment_reference> --chain eth --tx-hash 0xabc123 --private-key-path ~/.config/dispatch/wallet.key
```

## Need Billing, Privacy, Export, Abuse, or Closure Help

Open `https://dispatchjoin.com/support` and include:

- account email
- workspace id
- inbox address or inbox id
- payment provider and transaction details, if relevant
- the exact command or web flow that failed

---

## API and CLI Surface

Source: https://docs.dispatchjoin.com/reference/api-cli/
Description: High-level map of Dispatch commands, API areas, keys, and web surfaces.

This page is a compact reference. For step-by-step setup, start with [Quickstart](https://docs.dispatchjoin.com/getting-started/quickstart/).

## CLI Command Map

| Area | Commands | Use when |
| --- | --- | --- |
| Status | `dispatch status` | Check the API target, workspace, selected inbox, and local auth state. |
| Auth | `dispatch auth workspace`, `dispatch auth inbox`, `dispatch auth wallet`, `dispatch auth clear` | Connect direct keys, recover wallet-funded access, or clear saved credentials. |
| Inbox | `dispatch inbox create`, `dispatch inbox ls`, `dispatch inbox show`, `dispatch inbox use`, `dispatch inbox claim --open` | Provision, select, and claim inboxes. |
| Mail | `dispatch mail ls`, `dispatch mail tail`, `dispatch mail code`, `dispatch mail link`, `dispatch mail links`, `dispatch mail reply`, `dispatch mail send` | Read recent mail, wait for messages, extract codes or links, and send replies. |
| Memory | `dispatch memory write`, `dispatch memory read` | Store and retrieve subject-keyed text through the selected inbox. |
| Billing | `dispatch billing ls`, `dispatch billing confirm` | List entitlements or confirm x402 payments. |
| Guide | `dispatch guide` | Print the bundled operator quickstart and command reference. |

Common aliases:

- `dispatch inbox list` -> `dispatch inbox ls`
- `dispatch inbox select` -> `dispatch inbox use`
- `dispatch inbox link` -> `dispatch inbox claim`
- `dispatch mail list` -> `dispatch mail ls`
- `dispatch mail watch` -> `dispatch mail tail`
- `dispatch mail otp` -> `dispatch mail code`
- `dispatch mail artifacts` -> `dispatch mail extract`
- `dispatch billing list` -> `dispatch billing ls`

## Key Types

| Key | Scope | Typical commands |
| --- | --- | --- |
| Workspace key | Workspace and account-level operations | `inbox ls`, `inbox create`, `billing ls`, `billing confirm`, issuing inbox keys |
| Inbox key | One inbox's mail operations | `mail ls`, `mail tail`, `mail code`, `mail link`, `mail reply`, `mail send` |
| Claim token | One-time web account linking | `inbox claim` output and setup link flow |
| Wallet proof | Signed EVM or Solana message proving control of the funding wallet | web wallet sign-in, x402 claim, `auth wallet` |

Treat all keys like passwords.

## Public API Areas

Dispatch web and CLI operate against the same backend control plane.

| Area | Representative routes |
| --- | --- |
| Agent and workspace setup | `POST /v1/agent/signup`, `POST /v1/agent/claim`, `POST /v1/agent/unclaimed-inboxes`, `POST /v1/agent/recoverable-inboxes`, `POST /v1/agent/recover`, `GET /v1/agent/session` |
| Inbox management | `GET /v1/inboxes`, `POST /v1/inboxes`, `POST /v1/inboxes/{id}/api-key` |
| Mail access | `GET /v1/inboxes/{id}/messages`, `GET /v1/inboxes/{id}/otp`, `POST /v1/send` |
| Billing | `GET /v1/billing/entitlements`, `POST /v1/billing/checkout/session`, `POST /v1/billing/x402/quote`, `POST /v1/billing/payments/confirm` |
| Webhooks | `POST /v1/webhooks/stripe`, `POST /v1/webhooks/inbound`, `POST /v1/webhooks/aws/sns` |
| Account support | signup, email verification, password reset, and support request routes |

The CLI handles most request formatting for you. Use raw API calls when integrating Dispatch into automation that cannot shell out to the CLI.

## Web Surfaces

| Surface | Purpose |
| --- | --- |
| Setup | Create or sign into an account, verify email, create an inbox, recover with a wallet, or link an existing inbox. |
| Mail Desk | Read, organize, and reply from a claimed or wallet-recovered inbox. |
| Billing | See plan, usage, entitlements, and Stripe upgrade actions. |
| Settings | Inspect workspace and inbox key state for the current session. |
| Support | Submit billing, privacy, export, abuse, or account lifecycle requests. |

## Next Reading

- [Choose Your Path](https://docs.dispatchjoin.com/getting-started/choose-your-path/)
- [Plans and Usage](https://docs.dispatchjoin.com/account/plans-and-usage/)
- [Common Issues](https://docs.dispatchjoin.com/help/common-issues/)

---

## Repository Map

Source: https://docs.dispatchjoin.com/reference/repo-map/
Description: Quick map of major directories and responsibilities.

## Top-Level Map

```text
.
├── api/               Rust API service + worker + migrations + tests
├── cli/               Rust command-line client
├── docs/              Source markdown and docs site
│   └── site/          Astro + Starlight documentation app
├── infra/terraform/   AWS infrastructure as code
├── scripts/           Bootstrap and operational shell scripts
└── web/               Next.js product surfaces
```

## Ownership Expectations

- Backend behavior and contracts live in `api/`.
- Auth lifecycle behavior includes signup verification, password reset, and public support intake in `api/src/domains/auth`.
- User-facing workflow docs should link to both `cli/` and `web/`.
- User-facing account recovery and legal/support surfaces live in `web/app/reset-password` and `web/app/support`.
- Public architecture docs live in `docs/site`; the root `docs/` copies should only point there or hold private operator notes without drifting from the site copy.