Lob

Lob

Purpose

Send physical mail through Lob's Print and Mail API: verify US addresses; create postcards and letters that get printed and mailed; list what was sent; cancel a piece while it is still before production. Reach for this when the user wants a real letter or postcard in the mail rather than an email.

Tooling

All commands go through bin/lob.py:

bashCopy code
bin/lob.py auth                                   # verify the API key
bin/lob.py verify-address --file address.json     # verify/correct a US address (no mail sent)
bin/lob.py send-postcard --file postcard.json \
    --confirm "mail postcard to Jane Doe at 123 Main St"   # send a postcard (test key: simulated)
bin/lob.py send-letter --file letter.json \
    --confirm "mail letter to Jane Doe at 123 Main St"     # send a letter (test key: simulated)
bin/lob.py send-postcard --file postcard.json --live \
    --confirm "mail postcard to Jane Doe at 123 Main St"   # production key path: --live AND --confirm
bin/lob.py postcards                               # list postcards
bin/lob.py get-letter --id ltr_abc123             # retrieve a letter
bin/lob.py cancel-postcard --id psc_abc123        # cancel before production (no effect after)
bin/lob.py cancel-letter --id ltr_abc123          # cancel before production (no effect after)

postcard.json / letter.json hold the Lob create payloads (to, from, front/back HTML or template, size). Address verification never sends anything.

Auth

• Provider id: lob (credential is collected as custom.lob)
• Collection: API key via the secure credential flow (credentials.request_api_access); issued in the Lob dashboard
• Auth scheme: HTTP Basic with the API key as the username and a blank password; placement is resolved by the helper from the credential config
• Allowed hosts: api.lob.com
• Status check: bin/lob.py auth
• Key types: keys beginning test_ simulate the full lifecycle free (nothing printed, nothing charged). Keys beginning live_ print and mail for real.

Operating Rules

1. Test keys are the default path. With a test_ key the full lifecycle is simulated free. Never send real mail on a test run.
2. Live sends are a HIGH actuation: POST /postcards and POST /letters with a live key print a physical piece, hand it to the postal stream, and charge printing plus postage per piece. Once a piece enters production it cannot be recalled. The CLI enforces the gate: --live (your explicit acknowledgment that the stored key is live and real mail will go out) AND --confirm with the exact string the CLI echoes (recipient and address) are both required. The string must match exactly.
3. Cancellation only works pre-production. DELETE /postcards/{id} and DELETE /letters/{id} cancel a piece only while it is still in a cancellable state; after production starts they do nothing and spent fees are not refunded.
4. Per-piece pricing: printing plus postage are charged per piece on live keys; current prices are published on lob.com. Always state the piece count and type when confirming a send.
5. Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/lob.py). Do not print, log, or transmit the key value.

Files

• SKILL.mdCheck Domain?
• bin/lob.py

Maturity

Draft: written from Lob's public API docs; not yet live-tested end-to-end.