mail-safety

Applies to: **/mail/**, **/lob/**, **/postscanmail/**, **/letters/**, **/postcards/**

Mail Safety Rules

The Iron Law

Physical mail sends are irreversible. Once a mail item enters the USPS stream, it cannot be recalled. Every Lob API call that creates a mail item costs real money and cannot be undone.

Lob Environment Verification

Before ANY Lob send operation, check the environment:

# Check which key is loaded
echo $LOB_API_KEY | cut -c1-8
# test_live → test (safe, free)
# live_live → LIVE (real money, irreversible)

Key Prefix	Environment	Cost	Safe to run?
`test_`	Test / sandbox	Free	Yes
`live_`	Production	~$0.89–$9.00/item	Only with explicit confirmation
Unset / unknown	Unknown	Unknown	Block — require confirmation

NEVER call a Lob live endpoint without explicit user confirmation. This includes:

POST /v1/letters
POST /v1/postcards
POST /v1/checks
POST /v1/self_mailers

LOB_ENVIRONMENT Guard

When LOB_ENVIRONMENT is live or unset, emit a warning before proceeding:

⚠ LOB_ENVIRONMENT is set to "live" — this send will cost real money and cannot be recalled.
   Confirm: type YES to proceed or NO to abort.

Only continue on explicit YES. Never infer confirmation from context.

Cost Reference

Mail Type	Test Cost	Live Cost
Postcard (4x6)	Free	~$0.89
Letter (single page)	Free	~$1.19
Certified letter	Free	~$9.00
Check	Free	~$2.00

Rate Limits

Lob enforces 3 sends/minute on the live API. Batch operations must include delays:

// Never exceed 3 sends/minute on live
const RATE_LIMIT_MS = 20_000; // 20 seconds between sends for safety margin

PostScanMail — No Sandbox

PostScanMail has no sandbox environment. Every API call hits production. This applies to:

Creating scan rules
Forwarding mail items
Shredding mail items (destructive — cannot be undone)
Updating mailbox settings

Always confirm intent with the user before write operations. Read-only calls (GET endpoints) are safe.

Multi-API Operations

When both Lob and PostScanMail are involved in the same workflow, verify environment for each independently:

✓ Lob key prefix: test_ → safe
✗ PostScanMail: no sandbox → confirm before write ops

Never assume that a safe Lob environment implies PostScanMail safety.

Address Verification

Always call Lob’s address verification endpoint BEFORE sending a live mail item:

curl -X POST "https://api.lob.com/v1/us_verifications" \
  -u "$LOB_API_KEY:" \
  --data-urlencode "primary_line=185 Berry St" \
  --data-urlencode "city=San Francisco" \
  --data-urlencode "state=CA" \
  --data-urlencode "zip_code=94107"

Reject sends where deliverability is undeliverable — saves cost and avoids returned mail charges.