{"openapi":"3.1.0","info":{"title":"Piloxa Certified Mail","version":"0.30.3","description":"Turn a letter an assistant wrote into USPS Certified Mail. The API only PREPARES a letter and returns a review link: the person opens it, reads the exact document, sees the total, pays by card and authorizes. Nothing is printed, mailed or charged by any call here. No API key, no account and no OAuth. The same three operations are available as a remote MCP server at https://piloxa.com/mcp.","contact":{"name":"Piloxa support","email":"support@piloxa.com","url":"https://piloxa.com/support"},"termsOfService":"https://piloxa.com/terms"},"servers":[{"url":"https://piloxa.com"}],"externalDocs":{"description":"What Piloxa does and refuses to do, for assistants and agents","url":"https://piloxa.com/for-ai-agents"},"paths":{"/api/v1/quote":{"get":{"operationId":"quoteCertifiedLetter","summary":"Price a certified letter","description":"Read only. Returns the exact all-in total for a certified letter: printing, envelope and postage included, nothing added at checkout. Safe to call just to answer \"what would that cost\". Prepares, stores, mails and charges nothing.","parameters":[{"name":"page_count","in":"query","required":false,"description":"Number of printed pages in the letter, 1 to 60. Defaults to 1.","schema":{"type":"integer"}},{"name":"service","in":"query","required":false,"description":"CERTIFIED is Certified Mail with USPS tracking. CERTIFIED_ERR adds the Electronic Return Receipt (the record of who signed, kept when USPS reports it back). CERTIFIED_EVIDENCE is CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing and 7 years of retention. CERTIFIED_DEADLINE is CERTIFIED_EVIDENCE plus a same-day First-Class copy and an unclaimed-letter warning. Defaults to CERTIFIED_ERR, the same default prepare_certified_letter uses.","schema":{"type":"string","enum":["CERTIFIED","CERTIFIED_ERR","CERTIFIED_EVIDENCE","CERTIFIED_DEADLINE"]}}],"responses":{"200":{"description":"The price.","content":{"application/json":{"schema":{"type":"object","properties":{"service":{"type":"string","enum":["CERTIFIED","CERTIFIED_ERR","CERTIFIED_EVIDENCE","CERTIFIED_DEADLINE"]},"evidence_pack":{"type":"boolean"},"page_count":{"type":"integer"},"total_cents":{"type":"integer","description":"The whole price in cents. Nothing else is added at checkout."},"total":{"type":"string","description":"The same total, formatted for a person, e.g. \"$16.17\"."},"currency":{"type":"string"},"postage_and_print_cents":{"type":"integer","description":"The part that goes to printing and USPS."},"service_fee_cents":{"type":"integer","description":"The rest of the total: the Piloxa service fee, including the card cost."},"includes_printing_envelope_and_postage":{"type":"boolean"},"account_required":{"type":"boolean"},"subscription_required":{"type":"boolean"},"minimum_order":{"type":"boolean"},"mailed":{"type":"boolean","description":"Always false: this tool never mails."},"charged":{"type":"boolean","description":"Always false: this tool never charges."}},"required":["service","page_count","total_cents","total","currency","mailed","charged"]}}}},"400":{"description":"The request was refused; nothing was prepared, mailed or charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, in words that can be read straight to the person, and how to fix the call."}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Too many requests from this address. Wait a few minutes.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, in words that can be read straight to the person, and how to fix the call."}},"required":["code","message"]}},"required":["error"]}}}}}}},"/api/v1/letters":{"post":{"operationId":"prepareCertifiedLetter","summary":"Prepare a certified letter for review","description":"One call turns the finished letter into a priced USPS Certified Mail item and returns approval_url. Give the person that link: they read the document, pay and authorize there. This call never mails and never charges. Pass one of letter_text, document_text, document_base64 or person_has_pdf.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"letter_text":{"type":"string","description":"The complete, final letter body exactly as it should print: salutation, paragraphs separated by blank lines, and closing. Do not include the addresses or date; they are laid out from the other fields. Up to 60,000 characters."},"document_text":{"type":"string","description":"The COMPLETE text of a document that is already finished, printed exactly as written: no return address, no date line, no \"Re:\" line and no signature block are added, and line breaks and indentation are kept. This is the right field for a document the person gave you, for text you read out of a PDF or an attachment, for a filled-in form or a notice — anything you did not compose as a letter in this conversation. Include every word that must print, the addresses and signature line included if the document carries them. Up to 60,000 characters. Mutually exclusive with letter_text and document_base64."},"subject":{"type":"string","description":"The \"Re:\" line of the letter, in a few words."},"letter_date":{"type":"string","description":"Date to print on the letter, e.g. \"September 5, 2026\". Defaults to today."},"signature_name":{"type":"string","description":"Name printed under the closing."},"sender_address_block":{"type":"string","description":"The sender exactly as it should appear as the return address, one part per line. Read the same way as recipient_address_block. This is where a returned envelope goes back to."},"sender_name":{"type":"string","description":"Name of the person sending the letter (printed as the return address and used for the envelope)."},"sender_company":{"type":"string","description":"Sender company or entity, if any."},"sender_address_line1":{"type":"string","description":"Sender street address."},"sender_address_line2":{"type":"string"},"sender_city":{"type":"string"},"sender_state":{"type":"string","description":"Two-letter U.S. state code."},"sender_postal_code":{"type":"string","description":"Five-digit ZIP code."},"recipient_address_block":{"type":"string","description":"The recipient exactly as addressed in the letter, one part per line, e.g. \"Acme Property Management LLC\\nAttn: Jane Doe\\n1234 Wilshire Blvd, Suite 500\\nLos Angeles, CA 90017\". Piloxa reads the name, company, street, suite, city, state and ZIP out of it. Use this when you have the address as written and do not want to split it up yourself; any field you also name explicitly wins over it."},"recipient_name":{"type":"string","description":"Name of the person or company receiving the letter."},"recipient_company":{"type":"string","description":"Company name, if the letter goes to an organization."},"address_line1":{"type":"string","description":"Street address of the recipient."},"address_line2":{"type":"string","description":"Suite, unit or floor."},"city":{"type":"string"},"state":{"type":"string","description":"Two-letter U.S. state code."},"postal_code":{"type":"string","description":"Five-digit ZIP code."},"service":{"type":"string","enum":["CERTIFIED","CERTIFIED_ERR","CERTIFIED_EVIDENCE","CERTIFIED_DEADLINE"],"description":"Pick by what rides on the letter. CERTIFIED_ERR ($15.97 for one page) is the DEFAULT for an ordinary letter: Certified Mail with the Electronic Return Receipt, the record of who signed, kept when USPS reports it back. CERTIFIED ($12.97) is Certified Mail with tracking but no record of who signed; use it only when the person asks for the cheapest way. CERTIFIED_EVIDENCE ($24.21) is CERTIFIED_ERR plus the Evidence Pack: a Certificate of Mailing, and the record kept for 7 years instead of one; use it when proof of exactly what was sent may be needed later in a dispute - a debt validation notice, a notice to cure, a proof of loss, a demand before suing."},"document_base64":{"type":"string","description":"The finished PDF, base64-encoded (standard or URL-safe alphabet), up to 4 MB decoded. Use ONLY when you have read the actual file bytes; a filename or an attachment reference is not a document. Mutually exclusive with letter_text and document_text. The file is kept exactly as sent."},"document_filename":{"type":"string","description":"With document_base64: the original file name, e.g. \"Demand letter.pdf\"."},"document_sha256":{"type":"string","description":"Optional with document_base64: the SHA-256 (hex) of the PDF bytes. If given and it does not match what arrived, the call is refused rather than preparing the wrong file."},"person_has_pdf":{"type":"boolean","description":"Only when the person already has a finished PDF that neither you nor they can give you the text of, and they will attach it on the review page themselves. Set true to prepare without letter_text, document_text or document_base64. Prefer document_text whenever you can read the document at all: it saves the person an upload."},"page_count":{"type":"integer","description":"Only with person_has_pdf: number of pages in the PDF the person will attach, used for the price estimate."},"document_description":{"type":"string","description":"What the document is, in a few words."},"evidence_pack":{"type":"boolean","description":"The same as passing service CERTIFIED_EVIDENCE: adds the Evidence Pack to a certified letter with the Electronic Return Receipt. One page is $24.21 in total instead of $15.97."}}}}}},"responses":{"201":{"description":"Prepared for review. Nothing mailed, nothing charged.","content":{"application/json":{"schema":{"type":"object","properties":{"approval_url":{"type":"string","description":"Link the person opens to review, pay and authorize."},"mailed":{"type":"boolean","description":"Always false here: this tool never mails."},"charged":{"type":"boolean","description":"Always false here: this tool never charges."},"service":{"type":"string","enum":["CERTIFIED","CERTIFIED_ERR","CERTIFIED_EVIDENCE","CERTIFIED_DEADLINE"]},"recommended_service":{"type":"string","description":"Present when the letter reads as a notice whose miss or refusal would cost a legal right: the service worth mentioning to the person."},"recommended_because":{"type":"array","items":{"type":"string"},"description":"What in the letter led to that recommendation."},"page_count":{"type":"integer"},"estimated_provider_cost_cents":{"type":"integer"},"estimated_service_fee_cents":{"type":"integer"},"estimated_total_cents":{"type":"integer"},"account_required":{"type":"boolean","description":"Always false: the person needs no account to open the link and read the letter, and none is created by this call."},"estimated_total":{"type":"string","description":"The same total, formatted for a person, e.g. \"$16.17\"."},"evidence_pack":{"type":"boolean","description":"True when the Evidence Pack was bought: a Certificate of Mailing is issued with the record and the record is kept for 7 years rather than one."},"document_kind":{"type":"string","enum":["letter_text","document_text","pdf_bytes","person_will_attach"],"description":"Which way the document arrived, and so what the person will see on the page."},"recipient":{"type":"object","description":"The recipient as Piloxa read it, including anything parsed out of recipient_address_block. Check it against the letter and say it back to the person."},"missing_for_mailing":{"type":"array","items":{"type":"string"},"description":"What is still needed before this can be mailed, in plain words. Empty when nothing is missing. Ask the person for these now."},"ready_to_mail":{"type":"boolean","description":"True when nothing is missing: the person only has to read it, pay and authorize."},"document_rendered":{"type":"boolean","description":"True when letter_text or document_text was laid out into the PDF the person will review; false otherwise."},"document_received":{"type":"boolean","description":"True when document_base64 arrived intact and is the PDF the person will review; false otherwise."},"upload_required":{"type":"boolean","description":"True when the person still has to attach the PDF on the review page."},"document_sha256":{"type":"string","description":"SHA-256 of the rendered PDF, when document_rendered is true."},"requires_human_approval":{"type":"boolean"},"message":{"type":"string","description":"A plain-language summary to relay to the person, ending with the review link."},"session":{"type":"string","description":"Pass this to getCertifiedLetterStatus later to ask what happened to the letters prepared with it."}},"required":["approval_url","mailed","charged","requires_human_approval"]}}}},"400":{"description":"The request was refused; nothing was prepared, mailed or charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, in words that can be read straight to the person, and how to fix the call."}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Too many requests from this address. Wait a few minutes.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, in words that can be read straight to the person, and how to fix the call."}},"required":["code","message"]}},"required":["error"]}}}}}},"get":{"operationId":"getCertifiedLetterStatus","summary":"Check what happened to a letter sent through Piloxa","description":"Read only. What USPS has reported about the letters prepared with this session: accepted, delivered or returned, the tracking number and the signature record. Piloxa asks the mail provider afresh on each call.","parameters":[{"name":"session","in":"query","required":true,"description":"The session value returned by prepareCertifiedLetter.","schema":{"type":"string"}},{"name":"reference","in":"query","required":false,"description":"Optional. The Piloxa reference from the letter’s email receipt, to ask about one letter instead of all of them. A reference from outside this conversation is not found, on purpose.","schema":{"type":"string"}}],"responses":{"200":{"description":"The letters and what USPS has reported.","content":{"application/json":{"schema":{"type":"object","properties":{"letters":{"type":"array","items":{"type":"object","properties":{"reference":{"type":"string"},"to":{"type":"string","description":"The recipient’s name. The full address is not returned here; it is on the record at piloxa.com."},"service":{"type":"string","enum":["CERTIFIED","CERTIFIED_ERR","CERTIFIED_EVIDENCE","CERTIFIED_DEADLINE"]},"status":{"type":"string","description":"One of: with the printer, accepted by USPS, delivered, returned to sender."},"usps_tracking_number":{"type":["string","null"]},"accepted_by_usps_at":{"type":["string","null"]},"delivered_at":{"type":["string","null"]},"return_receipt":{"type":"string","description":"What is known about the signature record, or why there is none."},"practice_run":{"type":"boolean","description":"True when nothing was really printed or mailed."},"checked_with_provider_at":{"type":["string","null"]},"record_url":{"type":"string","description":"Where the person signs in to read the whole record and download the evidence."}},"required":["reference","status"]}},"found":{"type":"integer"},"scope":{"type":"string","description":"Always says that only this conversation’s letters are visible here."},"mailed":{"type":"boolean","description":"Always false: this tool never mails."},"charged":{"type":"boolean","description":"Always false: this tool never charges."}},"required":["letters","found","scope","mailed","charged"]}}}},"400":{"description":"The request was refused; nothing was prepared, mailed or charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, in words that can be read straight to the person, and how to fix the call."}},"required":["code","message"]}},"required":["error"]}}}},"429":{"description":"Too many requests from this address. Wait a few minutes.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string","description":"What was wrong, in words that can be read straight to the person, and how to fix the call."}},"required":["code","message"]}},"required":["error"]}}}}}}}}}