{"openapi":"3.1.0","info":{"title":"DirectMailAmerica 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; optional Certified ERR is $2.40. Authenticate with `Authorization: Bearer lbl_live_...` (production; mails on the live deployment) or `lbl_test_...` (developer sandbox, never mails). Paid resources may return HTTP 402 with x402 `PAYMENT-REQUIRED`. Live x402 stables: USDC on Base (`eip155:8453`) and USDC on Solana. Hosted MCP (`/api/mcp`) supports the same rail plus guest send_letter (no key; ephemeral org-on-pay) and Square card checkout tools that never collect PAN. See `/docs/mcp` and `/.well-known/mcp.json`.","contact":{"name":"Rainmaker LLC d/b/a DirectMailAmerica.com","email":"support@directmailamerica.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://directmailamerica.com/api/v1","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"Letters"},{"name":"Addresses"},{"name":"Pricing"},{"name":"Credits"}],"x-mcp":{"url":"https://directmailamerica.com/api/mcp","discovery":"https://directmailamerica.com/.well-known/mcp.json","docs":"https://directmailamerica.com/docs/mcp","guestX402":true,"tools":["send_letter","get_letter_status","list_jobs","get_pricing","get_credits","purchase_credits","create_credit_checkout","get_payment_status","start_account_login"],"stables":[{"symbol":"USDC","network":"eip155:8453","networkLabel":"Base","live":true},{"symbol":"USDC","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","networkLabel":"Solana","live":true}]},"paths":{"/letters":{"get":{"tags":["Letters"],"summary":"List mailings","operationId":"listLetters","responses":{"200":{"description":"Job list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Letters"],"summary":"Create a mailing","description":"Spends org credits when the balance covers the quote. Otherwise HTTP 402 + x402 PAYMENT-REQUIRED (USDC on Base and Solana). Retry with PAYMENT-SIGNATURE. REST requires a Bearer key. MCP `send_letter` uses this same rail and also allows guest (no-key) x402 with ephemeral org-on-pay.","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"},"couponCode":{"type":"string"}}}}}},"responses":{"201":{"description":"Job created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required (x402)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/addresses/validate":{"post":{"tags":["Addresses"],"summary":"Validate a postal address (format stub)","description":"Checks required fields and US ZIP shape. Does not call USPS or LetterStream. The `provider` field is always `stub`.","operationId":"validateAddress","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"responses":{"200":{"description":"Stub validation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressValidation"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/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"}},{"name":"couponCode","in":"query","schema":{"type":"string"},"description":"Server-validated catalog code (case-insensitive). Changes quoted cents only. Unknown codes return 400."}],"responses":{"200":{"description":"Quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/credits":{"post":{"tags":["Credits"],"summary":"Purchase credits via x402","description":"Requires a Bearer API key (same as other `/api/v1` routes). Without `PAYMENT-SIGNATURE`, returns HTTP 402 with `PAYMENT-REQUIRED`. Live stables: USDC on Base and USDC on Solana. MCP equivalent: `purchase_credits`. Card top-up for agents: MCP `create_credit_checkout` (Square hosted; no PAN).","operationId":"purchaseCredits","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseCredits"}}}},"responses":{"200":{"description":"Credits added, PAYMENT-RESPONSE header set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditsPurchase"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"PAYMENT-REQUIRED challenge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"lbl","description":"API key issued in the Developers page. Prefix `lbl_live_` (production; purchases postage on the live deployment) or `lbl_test_` (developer sandbox, never mails)."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"amountCents":{"type":"integer"}}},"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"}}},"Document":{"type":"object","required":["kind","content"],"description":"Text body or base64 PDF. For multipart uploads, send the file as `pdf` instead of `content`.","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":"Optional hint. The 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"}}},"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":{"$ref":"#/components/schemas/Document"},"pdfBase64":{"type":"string","description":"Optional raw PDF as base64 (same as document.kind=pdf)."},"couponCode":{"type":"string","description":"Server-validated catalog code (case-insensitive). Applied to charged/quoted cents only. Staging keys still never buy postage. Unknown codes return 400."}}},"Job":{"type":"object","required":["id","status","mailClass","priceCents","createdAt"],"properties":{"id":{"type":"string"},"status":{"type":"string","enum":["queued","in_production","processing","printed","mailed","in_transit","delivered","returned","failed","cancelled"]},"mailClass":{"type":"string","enum":["first_class","certified","postcard"]},"certified":{"type":"boolean"},"electronicReturnReceipt":{"type":"boolean"},"priceCents":{"type":"integer"},"trackingNumber":{"type":"string"},"provider":{"type":"string","enum":["mock","letterstream"]},"fulfillmentMode":{"type":"string","enum":["mock","live","dry_run"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"JobResponse":{"type":"object","required":["letter"],"properties":{"letter":{"$ref":"#/components/schemas/Job"}}},"JobList":{"type":"object","required":["letters"],"properties":{"letters":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}},"Quote":{"type":"object","required":["mailClass","totalCents","currency"],"properties":{"mailClass":{"type":"string","enum":["first_class","certified","postcard"]},"recipientCount":{"type":"integer"},"pageCount":{"type":"integer"},"perPieceCents":{"type":"integer"},"subtotalCents":{"type":"integer"},"optionsCents":{"type":"integer"},"totalCents":{"type":"integer"},"listTotalCents":{"type":"integer","description":"List price before any coupon."},"discountCents":{"type":"integer"},"coupon":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"percentOff":{"type":"integer"}}},"currency":{"type":"string","enum":["USD"]},"note":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"cents":{"type":"integer"}}}}}},"PurchaseCredits":{"type":"object","required":["amountCents"],"properties":{"amountCents":{"type":"integer","minimum":100,"default":1000,"description":"Credit purchase in USD cents. Minimum 100 ($1.00)."}}},"CreditsPurchase":{"type":"object","required":["creditsCents","amountCents"],"properties":{"creditsCents":{"type":"integer"},"amountCents":{"type":"integer"}}},"AddressValidation":{"type":"object","description":"Format-only stub. Not USPS CASS.","required":["valid","provider"],"properties":{"valid":{"type":"boolean"},"provider":{"type":"string","enum":["stub"]},"note":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}}}}}}