> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Lob

> A stateful replica of Lob's Print & Mail API v1: addresses, letters, postcards and checks, bank accounts, templates and US address verification, where nothing is printed or mailed.

The Lob replica implements 28 endpoints of the Print & Mail API v1. Nothing is printed or mailed: tracking follows the scene clock, and mail to an address the postal directory does not know, or a vacant one, comes back. Its key is `lob`. It was tested with `@lob/lob-typescript-sdk`.

## Connect

| Variable | Value |
| - | - |
| `LOB_API_URL` | Base URL, ending in `/v1`. Pass it as the SDK's `basePath`. |
| `LOB_API_KEY` | Fake test API key. Lob uses HTTP Basic with the key as the username and an empty password. |
| `LOB_ASSETS_URL` | Where proof files are served. Proof links in responses name `https://lob-assets.com`, as Lob's do; replace that host with this URL to fetch them. |

```js Node theme={null}
import { Configuration, LettersApi } from '@lob/lob-typescript-sdk';
const config = new Configuration({ username: process.env.LOB_API_KEY, basePath: process.env.LOB_API_URL, baseOptions: { proxy: false } });
const letters = await new LettersApi(config).list(10);
// A proof PDF: await fetch(letters.data![0].url!.replace('https://lob-assets.com', process.env.LOB_ASSETS_URL!))
```

This is what `ancha connect lob --lang ts` prints. The SDK rejects proof links on any host but `lob-assets.com`, which is why the replica returns those and serves the files under `LOB_ASSETS_URL`.

## Endpoints

All 28 endpoints are partial. Anything else returns HTTP 501 with Lob's error shape and `x-ancha-gap: 1`. Lists take `limit`, `before` and `after` cursors, `include=total_count`, and `date_created` and `metadata` filters; mail lists also take `scheduled`, `send_date`, `mail_type` and `sort_by`.

| Method | Path | Notes |
| - | - | - |
| `GET`, `POST` | `/v1/addresses` | US addresses are upper-cased and standardized against the postal directory. |
| `GET`, `DELETE` | `/v1/addresses/{id}` | |
| `GET`, `POST` | `/v1/letters` | HTML, a template, a file URL (recorded, never fetched) or an uploaded PDF; certified and registered mail; `Idempotency-Key`. |
| `GET`, `DELETE` | `/v1/letters/{id}` | Cancel until production starts: the cancellation window, or a scheduled send date. |
| `GET`, `POST` | `/v1/postcards` | 4x6, 6x9 and 6x11; front and back as HTML, template, URL or upload. |
| `GET`, `DELETE` | `/v1/postcards/{id}` | |
| `GET`, `POST` | `/v1/checks` | From a verified bank account; check numbers advance per account; no money moves. |
| `GET`, `DELETE` | `/v1/checks/{id}` | |
| `GET`, `POST` | `/v1/bank_accounts` | New accounts start unverified. |
| `GET`, `DELETE` | `/v1/bank_accounts/{id}` | |
| `POST` | `/v1/bank_accounts/{id}/verify` | With the two micro-deposit amounts in cents. |
| `GET`, `POST` | `/v1/templates` | `{{variable}}` merge fields with `#if` and `#unless` blocks. |
| `GET`, `POST`, `DELETE` | `/v1/templates/{id}` | Update the description and the published version. |
| `POST` | `/v1/us_verifications` | Against the world's postal directory, or any complete address when the scene has none; `case=upper` or `proper`. |
| `POST` | `/v1/bulk/us_verifications` | Up to 20 addresses. |

## Starter data

The `lob-starter` dataset is Acme's account, with a five-minute cancellation window and a postal directory of eight commercial addresses, one of them vacant.

| Record | Detail |
| - | - |
| Addresses | Acme's billing return address (Anna Fischer, San Francisco); Helix Manufacturing's accounts payable at an old Akron address, which the directory marks vacant, and a new one added three hours ago; Summit Freight billing (Reno); Erin Walsh at Ridgeway Robotics (Pittsburgh); Pinecrest Health accounts payable and Nora Bell (Portland); Kestrel Credit Union procurement (Madison); Grace Lin at Bluefield Logistics (Baltimore). |
| Bank accounts | "Acme operating account", verified, and "Acme refunds account", unverified, with micro-deposits of 17 and 42 cents. |
| Templates | An invoice cover letter and the front and back of a welcome postcard, with `first_name` and `company` merge fields. |
| Letters | Helix Manufacturing's October invoice, sent five days ago to the vacant address, and Pinecrest Health's December invoice, scheduled 23 days ahead. |
| Postcards | Welcome postcards to Erin Walsh and Nora Bell. |
| Checks | A refund check to Summit Freight for a duplicate September charge, canceled. |

## Checks

Lob has no state checks. Use trace checks, for example `{ called: "POST /v1/letters" }` or `{ not_called: "POST /v1/checks" }`.

## Limits

* Nothing is printed or mailed: USPS tracking follows the scene clock, and mail to an address the postal directory does not know, or a vacant one, comes back.
* Pass `LOB_API_URL` as the SDK's `basePath` and `LOB_API_KEY` as its username. Fetch proof links under `LOB_ASSETS_URL`.
* US verification consults the world's postal directory. File URLs are recorded, never fetched; no thumbnails, self-mailers, campaigns, international verification or webhooks.


## Related topics

- [ancha connect](https://docs.ancha.io/cli/connect.md)
- [Tools](https://docs.ancha.io/tools/overview.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)
- [Introduction](https://docs.ancha.io/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.