{"openapi":"3.1.0","info":{"title":"LettersByLetter API","version":"1.0.0","summary":"Print-and-mail letters, certified mail, and postcards.","description":"Create mailings, check status, validate addresses, and read pricing. First-Class is $1.49 for page 1 then $0.25/page; Certified is $12.99 base + $0.25/extra page; postcards are $1.99. Authenticate with `Authorization: Bearer lbl_...`. Paid resources may return HTTP 402 with x402 `PAYMENT-REQUIRED`.","contact":{"name":"Rainmaker LLC d/b/a LettersByLetter.com","email":"hello@lettersbyletter.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://0.0.0.0:8080/api/v1","description":"Current host"}],"security":[{"apiKey":[]}],"tags":[{"name":"Letters"},{"name":"Addresses"},{"name":"Pricing"},{"name":"Credits"}],"paths":{"/letters":{"get":{"tags":["Letters"],"summary":"List mailings","operationId":"listLetters","responses":{"200":{"description":"Job list"},"401":{"description":"Missing or invalid API key"}}},"post":{"tags":["Letters"],"summary":"Create a mailing","operationId":"createLetter","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLetter"}},"multipart/form-data":{"schema":{"type":"object","description":"Upload a print-ready PDF as `pdf` plus JSON address fields.","properties":{"mailClass":{"type":"string","enum":["first_class","certified","postcard"]},"from":{"type":"string","description":"JSON Address"},"recipients":{"type":"string","description":"JSON Address[]"},"pdf":{"type":"string","format":"binary"},"body":{"type":"string"}}}}}},"responses":{"201":{"description":"Job created"},"401":{"description":"Unauthorized"},"402":{"description":"Payment required (x402)"}}}},"/letters/{id}":{"get":{"tags":["Letters"],"summary":"Get mailing status","operationId":"getLetter","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Job"},"404":{"description":"Not found"}}}},"/addresses/validate":{"post":{"tags":["Addresses"],"summary":"Validate a postal address (stub)","operationId":"validateAddress","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"responses":{"200":{"description":"Validation result"}}}},"/pricing":{"get":{"tags":["Pricing"],"summary":"Quote a mailing","operationId":"getPricing","parameters":[{"name":"mailClass","in":"query","schema":{"type":"string","enum":["first_class","certified","postcard"]}},{"name":"pageCount","in":"query","schema":{"type":"integer"}},{"name":"recipientCount","in":"query","schema":{"type":"integer"}},{"name":"certified","in":"query","schema":{"type":"boolean"}},{"name":"err","in":"query","schema":{"type":"boolean"}},{"name":"color","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Quote"}}}},"/credits":{"post":{"tags":["Credits"],"summary":"Purchase credits via x402","operationId":"purchaseCredits","security":[],"responses":{"200":{"description":"Credits added, PAYMENT-RESPONSE header set"},"402":{"description":"PAYMENT-REQUIRED challenge"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"lbl","description":"API key issued in the Developers page. Prefix `lbl_live_` (production) or `lbl_test_` (staging, never mails)."}},"schemas":{"Address":{"type":"object","required":["name","line1","city","state","postal"],"properties":{"name":{"type":"string"},"company":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"postal":{"type":"string"},"country":{"type":"string","default":"US"}}},"CreateLetter":{"type":"object","required":["from","recipients","document"],"properties":{"mailClass":{"type":"string","enum":["first_class","certified","postcard"],"default":"first_class"},"certified":{"type":"boolean"},"electronicReturnReceipt":{"type":"boolean"},"from":{"$ref":"#/components/schemas/Address"},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"document":{"type":"object","required":[],"properties":{"kind":{"type":"string","enum":["pdf","text"]},"filename":{"type":"string"},"content":{"type":"string","description":"UTF-8 letter body or base64 PDF. Prefer uploading a PDF so embedded fonts pass through."},"pageCount":{"type":"integer","description":"Server re-counts PDF pages and prices $1.49 + $0.25 extra (First-Class) or $12.99 + $0.25 extra (Certified)."},"color":{"type":"boolean"},"doubleSided":{"type":"boolean"}}},"pdfBase64":{"type":"string","description":"Optional raw PDF as base64 (same as document.kind=pdf)."}}}}}}