Piloxa is an MCP server published by io.github.Piloxa, hosted at piloxa.com. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 14 tools, including prepare_certified_letter, quote_certified_letter, get_certified_letter_status, check_certified_letter, search.
Prepare USPS Certified Mail letters from any AI assistant; a person reviews, pays and authorizes.
Nothing else in the archive shares these values.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Use when the person wants a letter or an existing document physically mailed by USPS Certified Mail to a U.S. address: a demand, a dispute, a debt validation request, a deposit demand, a cancellation, a notice to a landlord, tenant, contractor, HOA, insurer, employer or company. Creates an UNSENT mailing draft and returns a review link and the current price. ONE CALL is enough: no account, no sign-up, no card, no second call. PREPARING IS NOT SENDING: this tool never prints, mails or charges. On that page the person reads the exact pages, recipient, service and total, then separately pays and approves; only then is it printed and mailed. A missing or incomplete recipient or return address does not stop the draft: it comes back in missing_for_mailing and the person completes it on the review page, but nothing can be mailed until it is complete. Do not call it merely because the person is drafting, revising, translating, saving or emailing a letter, or when they asked for ordinary mail, email or another channel; ask first if it is unclear that they want it mailed. Send only the document to be mailed and its addresses, never unrelated conversation content. Lead with the first-letter price: $9.95 all in (1-2 pages, Certified Mail with tracking, no return receipt, one per account). After that: A one-page letter is $12.97 in total with USPS tracking, $15.97 with the Electronic Return Receipt (the default: the record of who signed), $24.21 with the Evidence Pack or $50.10 as a Deadline Notice (see the service field); printing, envelope and postage included. A higher-priced service is used only when the person chooses it. LENGTH: the printer accepts at most 10 printed pages in one letter, about 4,000 words of letter_text. Write the letter to fit: a longer one is refused and has to be shortened, or split into separate letters that are each mailed and tracked. U.S. destinations only. If the letter sets a reply date, Piloxa emails the sender the day after that date with the USPS delivery date, free. THE DOCUMENT, one of: letter_text for a letter you wrote now (body only); document_text for a finished document you were given, printed exactly as written; document_base64 for PDF bytes you can read; person_has_pdf: true when they will attach it on the page. ADDRESSES: pass them as written in recipient_address_block and sender_address_block, one part per line.
| Parameter | Type | Description |
|---|---|---|
| city | string | |
| state | string | Two-letter U.S. state code. |
| service | string | 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; us… |
| subject | string | The "Re:" line of the letter, in a few words. |
| reply_by | string | Optional: the date, as YYYY-MM-DD, by which the letter asks the recipient to answer, pay or act. Leave it out and Piloxa reads it from the letter ("within 30 days of receipt", "no later than October 15, 2026"). The day after that date Piloxa emails the sender, once, with the date USPS delivered the … |
| page_count | integer | Only with person_has_pdf: number of pages in the PDF the person will attach, used for the price estimate. |
| letter_date | string | Date to print on the letter, e.g. "September 5, 2026". Defaults to today. |
| letter_text | string | 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. It must fit in 10 printed pages, about 4,000 words. |
| postal_code | string | Five-digit ZIP code. |
| sender_city | string | |
| sender_name | string | Name of the person sending the letter (printed as the return address and used for the envelope). |
| sender_state | string | Two-letter U.S. state code. |
| address_line1 | string | Street address of the recipient. |
| address_line2 | string | Suite, unit or floor. |
| document_text | string | 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 … |
| evidence_pack | boolean | 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. |
| person_has_pdf | boolean | 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 sav… |
| recipient_name | string | Name of the person or company receiving the letter. |
| sender_company | string | Sender company or entity, if any. |
| signature_name | string | Name printed under the closing. |
| document_base64 | string | 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_sha256 | string | 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. |
| document_filename | string | With document_base64: the original file name, e.g. "Demand letter.pdf". |
| recipient_company | string | Company name, if the letter goes to an organization. |
| sender_postal_code | string | Five-digit ZIP code. |
| document_description | string | What the document is, in a few words. |
| sender_address_block | string | 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_address_line1 | string | Sender street address. |
| sender_address_line2 | string | |
| recipient_address_block | string | 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 … |
{
"name": "prepare_certified_letter",
"title": "Prepare a certified letter for review",
"description": "Use when the person wants a letter or an existing document physically mailed by USPS Certified Mail to a U.S. address: a demand, a dispute, a debt validation request, a deposit demand, a cancellation, a notice to a landlord, tenant, contractor, HOA, insurer, employer or company. Creates an UNSENT mailing draft and returns a review link and the current price. ONE CALL is enough: no account, no sign-up, no card, no second call. PREPARING IS NOT SENDING: this tool never prints, mails or charges. On that page the person reads the exact pages, recipient, service and total, then separately pays and approves; only then is it printed and mailed. A missing or incomplete recipient or return address does not stop the draft: it comes back in missing_for_mailing and the person completes it on the review page, but nothing can be mailed until it is complete. Do not call it merely because the person is drafting, revising, translating, saving or emailing a letter, or when they asked for ordinary mail, email or another channel; ask first if it is unclear that they want it mailed. Send only the document to be mailed and its addresses, never unrelated conversation content. Lead with the first-letter price: $9.95 all in (1-2 pages, Certified Mail with tracking, no return receipt, one per account). After that: A one-page letter is $12.97 in total with USPS tracking, $15.97 with the Electronic Return Receipt (the default: the record of who signed), $24.21 with the Evidence Pack or $50.10 as a Deadline Notice (see the service field); printing, envelope and postage included. A higher-priced service is used only when the person chooses it. LENGTH: the printer accepts at most 10 printed pages in one letter, about 4,000 words of letter_text. Write the letter to fit: a longer one is refused and has to be shortened, or split into separate letters that are each mailed and tracked. U.S. destinations only. If the letter sets a reply date, Piloxa emails the sender the day after that date with the USPS delivery date, free. THE DOCUMENT, one of: letter_text for a letter you wrote now (body only); document_text for a finished document you were given, printed exactly as written; document_base64 for PDF bytes you can read; person_has_pdf: true when they will attach it on the page. ADDRESSES: pass them as written in recipient_address_block and sender_address_block, one part per line.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"city": {
"type": "string"
},
"state": {
"type": "string",
"description": "Two-letter U.S. state code."
},
"service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string",
"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. CERTIFIED_DEADLINE ($50.10) is CERTIFIED_EVIDENCE plus a second copy by First-Class Mail the same day and a warning email if the certified copy goes unclaimed; use it when a missed or refused notice would cost a lien, a contract remedy or a claim - a pre-lien or preliminary notice, a notice with a statutory deadline. When this field is left out, CERTIFIED_ERR is used, except that a letter of one or two pages that may be the person’s first goes as CERTIFIED at the first-letter price, with the return receipt offered beside it; if the letter reads as such a notice, Piloxa returns CERTIFIED_DEADLINE as recommended_service with its extra cost, without selecting it. Whichever you pick, say its price to the person before they open the link."
},
"subject": {
"type": "string",
"description": "The \"Re:\" line of the letter, in a few words."
},
"reply_by": {
"type": "string",
"description": "Optional: the date, as YYYY-MM-DD, by which the letter asks the recipient to answer, pay or act. Leave it out and Piloxa reads it from the letter (\"within 30 days of receipt\", \"no later than October 15, 2026\"). The day after that date Piloxa emails the sender, once, with the date USPS delivered the letter and the next step if nobody answered, at no charge."
},
"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."
},
"letter_date": {
"type": "string",
"description": "Date to print on the letter, e.g. \"September 5, 2026\". Defaults to today."
},
"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. It must fit in 10 printed pages, about 4,000 words."
},
"postal_code": {
"type": "string",
"description": "Five-digit ZIP code."
},
"sender_city": {
"type": "string"
},
"sender_name": {
"type": "string",
"description": "Name of the person sending the letter (printed as the return address and used for the envelope)."
},
"sender_state": {
"type": "string",
"description": "Two-letter U.S. state code."
},
"address_line1": {
"type": "string",
"description": "Street address of the recipient."
},
"address_line2": {
"type": "string",
"description": "Suite, unit or floor."
},
"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."
},
"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."
},
"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."
},
"recipient_name": {
"type": "string",
"description": "Name of the person or company receiving the letter."
},
"sender_company": {
"type": "string",
"description": "Sender company or entity, if any."
},
"signature_name": {
"type": "string",
"description": "Name printed under the closing."
},
"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_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."
},
"document_filename": {
"type": "string",
"description": "With document_base64: the original file name, e.g. \"Demand letter.pdf\"."
},
"recipient_company": {
"type": "string",
"description": "Company name, if the letter goes to an organization."
},
"sender_postal_code": {
"type": "string",
"description": "Five-digit ZIP code."
},
"document_description": {
"type": "string",
"description": "What the document is, in a few words."
},
"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_address_line1": {
"type": "string",
"description": "Sender street address."
},
"sender_address_line2": {
"type": "string"
},
"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."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"approval_url",
"mailed",
"charged",
"requires_human_approval"
],
"properties": {
"mailed": {
"type": "boolean",
"description": "Always false here: this tool never mails."
},
"charged": {
"type": "boolean",
"description": "Always false here: this tool never charges."
},
"service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string"
},
"identity": {
"type": "object",
"description": "What the person must do to prove who they are: nothing to preview; verify their email when they send."
},
"quote_id": {
"type": "string",
"description": "Binds an approval to this exact document, recipient, sender, service and total until final_quote.expires_at. Pass it to authorize_certified_letter where that is available."
},
"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."
},
"mailing_id": {
"type": [
"string",
"null"
],
"description": "This letter, for authorize_certified_letter and for follow-up in this conversation."
},
"page_count": {
"type": "integer"
},
"final_quote": {
"type": [
"object",
"null"
],
"description": "standard_total_cents, discount_cents, payable_total_cents, currency, promotion_status (eligible, not_eligible, depends_on_account, not_applicable), expires_at and approval_routes. Quote payable_total_cents to the person; while promotion_status is depends_on_account the first-letter price is not promised."
},
"approval_url": {
"type": "string",
"description": "Link the person opens to review, pay and authorize."
},
"document_kind": {
"enum": [
"letter_text",
"document_text",
"pdf_bytes",
"person_will_attach"
],
"type": "string",
"description": "Which way the document arrived, and so what the person will see on the page."
},
"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."
},
"ready_to_mail": {
"type": "boolean",
"description": "True when nothing is missing: the person only has to read it, pay and authorize."
},
"document_sha256": {
"type": "string",
"description": "SHA-256 of the rendered PDF, when document_rendered is true."
},
"estimated_total": {
"type": "string",
"description": "The same total, formatted for a person, with a dollar sign and cents."
},
"upload_required": {
"type": "boolean",
"description": "True when the person still has to attach the PDF on the review page."
},
"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."
},
"document_received": {
"type": "boolean",
"description": "True when document_base64 arrived intact and is the PDF the person will review; false otherwise."
},
"document_rendered": {
"type": "boolean",
"description": "True when letter_text or document_text was laid out into the PDF the person will review; false otherwise."
},
"transaction_state": {
"enum": [
"PREPARED",
"AWAITING_APPROVAL"
],
"type": "string",
"description": "PREPARED while something is still missing; AWAITING_APPROVAL when only the person’s approval and payment are left."
},
"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."
},
"recommended_because": {
"type": "array",
"items": {
"type": "string"
},
"description": "What in the letter led to that recommendation."
},
"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."
},
"estimated_total_cents": {
"type": "integer"
},
"requires_human_approval": {
"type": "boolean"
},
"estimated_service_fee_cents": {
"type": "integer"
},
"estimated_provider_cost_cents": {
"type": "integer"
}
}
},
"annotations": {
"title": "Prepare a certified letter for review",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}Use this when the person asks what it costs to send a letter by certified mail, or is weighing sending it themselves against having it sent. Says what a USPS Certified Mail letter costs, before anything is prepared. Give the number of printed pages and the service, and it returns the exact all-in total the person would pay: printing, the envelope and the postage are included, and nothing is added at checkout. Lead with the first-letter price: $9.95 all in (1-2 pages, Certified Mail with tracking, no return receipt, one per account). After that: A one-page letter is $12.97 with USPS tracking, $15.97 with the Electronic Return Receipt, which is the default, $24.21 with the Evidence Pack, or $50.10 as a Deadline Notice. There is no account to create, no subscription and no minimum. This tool is READ ONLY: it prepares nothing, stores nothing, mails nothing and charges nothing, so it is safe to call just to answer "what would that cost". Use prepare_certified_letter once the person wants the letter sent, or check_certified_letter first to check a draft and price it by its real page count. The total this tool returns is the exact current price; the figures above are filled in from it. U.S. destinations.
| Parameter | Type | Description |
|---|---|---|
| service | string | 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_… |
| page_count | integer | Number of printed pages in the letter, 1 to 10, the most the printer accepts in one letter. Defaults to 1. |
{
"name": "quote_certified_letter",
"title": "Price a certified letter",
"description": "Use this when the person asks what it costs to send a letter by certified mail, or is weighing sending it themselves against having it sent. Says what a USPS Certified Mail letter costs, before anything is prepared. Give the number of printed pages and the service, and it returns the exact all-in total the person would pay: printing, the envelope and the postage are included, and nothing is added at checkout. Lead with the first-letter price: $9.95 all in (1-2 pages, Certified Mail with tracking, no return receipt, one per account). After that: A one-page letter is $12.97 with USPS tracking, $15.97 with the Electronic Return Receipt, which is the default, $24.21 with the Evidence Pack, or $50.10 as a Deadline Notice. There is no account to create, no subscription and no minimum. This tool is READ ONLY: it prepares nothing, stores nothing, mails nothing and charges nothing, so it is safe to call just to answer \"what would that cost\". Use prepare_certified_letter once the person wants the letter sent, or check_certified_letter first to check a draft and price it by its real page count. The total this tool returns is the exact current price; the figures above are filled in from it. U.S. destinations.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string",
"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. Left out, a letter of one or two pages is priced as a first letter (CERTIFIED at the first-letter price, when that offer runs) and anything longer as CERTIFIED_ERR, the same defaults prepare_certified_letter uses."
},
"page_count": {
"type": "integer",
"description": "Number of printed pages in the letter, 1 to 10, the most the printer accepts in one letter. Defaults to 1."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"service",
"page_count",
"total_cents",
"total",
"currency",
"mailed",
"charged"
],
"properties": {
"total": {
"type": "string",
"description": "The same total, formatted for a person, with a dollar sign and cents."
},
"mailed": {
"type": "boolean",
"description": "Always false: this tool never mails."
},
"charged": {
"type": "boolean",
"description": "Always false: this tool never charges."
},
"service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string"
},
"currency": {
"type": "string"
},
"promotion": {
"type": [
"object",
"null"
],
"description": "Present when the first-letter promotion could lower this total for a person’s first letter. It is applied by the same rule on the review page and in authorize_certified_letter once the payer is known; total_cents is the standard price and is what to quote until then."
},
"page_count": {
"type": "integer"
},
"total_cents": {
"type": "integer",
"description": "The whole price in cents. Nothing else is added at checkout."
},
"price_source": {
"type": "string"
},
"evidence_pack": {
"type": "boolean"
},
"minimum_order": {
"type": "boolean"
},
"account_required": {
"type": "boolean"
},
"service_fee_cents": {
"type": "integer",
"description": "The rest of the total: the Piloxa service fee, including the card cost."
},
"transaction_state": {
"enum": [
"QUOTED"
],
"type": "string",
"description": "Always QUOTED: a price only, nothing exists yet."
},
"subscription_required": {
"type": "boolean"
},
"postage_and_print_cents": {
"type": "integer",
"description": "The part that goes to printing and USPS."
},
"includes_printing_envelope_and_postage": {
"type": "boolean"
}
}
},
"annotations": {
"title": "Price a certified letter",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Answers "has my letter arrived yet" for letters prepared through Piloxa IN THIS SAME CONVERSATION. Returns, for each one: who it went to, the service, the USPS tracking number once USPS has assigned one, whether USPS has accepted it, delivered it or returned it, and when each of those was recorded. Piloxa asks the print and mail provider for a fresh answer when this is called, so it is current rather than remembered. IMPORTANT AND DELIBERATE: it can only see letters this connector prepared in this conversation, because that is the only thing it can identify without a sign-in; it cannot reach a person’s other letters, letters sent from another conversation, or anybody else’s. For those, the person signs in at piloxa.com and opens the letter there. This tool is READ ONLY: it prepares nothing, mails nothing and charges nothing. A stage with no scan means no scan has been reported, which is not the same as a failed delivery — USPS sometimes records delivery late, or not at all.
| Parameter | Type | Description |
|---|---|---|
| reference | string | 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. |
{
"name": "get_certified_letter_status",
"title": "Check what happened to a letter sent through Piloxa",
"description": "Answers \"has my letter arrived yet\" for letters prepared through Piloxa IN THIS SAME CONVERSATION. Returns, for each one: who it went to, the service, the USPS tracking number once USPS has assigned one, whether USPS has accepted it, delivered it or returned it, and when each of those was recorded. Piloxa asks the print and mail provider for a fresh answer when this is called, so it is current rather than remembered. IMPORTANT AND DELIBERATE: it can only see letters this connector prepared in this conversation, because that is the only thing it can identify without a sign-in; it cannot reach a person’s other letters, letters sent from another conversation, or anybody else’s. For those, the person signs in at piloxa.com and opens the letter there. This tool is READ ONLY: it prepares nothing, mails nothing and charges nothing. A stage with no scan means no scan has been reported, which is not the same as a failed delivery — USPS sometimes records delivery late, or not at all.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"reference": {
"type": "string",
"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."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"letters",
"found",
"scope",
"mailed",
"charged"
],
"properties": {
"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."
},
"letters": {
"type": "array",
"items": {
"type": "object",
"required": [
"reference",
"status"
],
"properties": {
"to": {
"type": "string",
"description": "The recipient’s name. The full address is not returned here; it is on the record at piloxa.com."
},
"status": {
"type": "string",
"description": "One of: with the printer, accepted by USPS, delivered, returned to sender."
},
"service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string"
},
"reference": {
"type": "string"
},
"record_url": {
"type": "string",
"description": "Where the person signs in to read the whole record and download the evidence."
},
"delivered_at": {
"type": [
"string",
"null"
]
},
"practice_run": {
"type": "boolean",
"description": "True when nothing was really printed or mailed."
},
"return_receipt": {
"type": "string",
"description": "What is known about the signature record, or why there is none."
},
"transaction_state": {
"enum": [
"AUTHORIZED",
"VENDOR_ACCEPTED",
"MAILED",
"DELIVERED",
"RETURNED",
"FAILED",
"CANCELLED",
"AWAITING_APPROVAL"
],
"type": "string"
},
"accepted_by_usps_at": {
"type": [
"string",
"null"
]
},
"usps_tracking_number": {
"type": [
"string",
"null"
]
},
"checked_with_provider_at": {
"type": [
"string",
"null"
]
}
}
}
}
}
},
"annotations": {
"title": "Check what happened to a letter",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}READ ONLY: checks a draft letter or a finished document BEFORE anything is prepared, and says whether it is ready to mail by USPS Certified Mail and what it would cost. Use it when the person asks "is this ready to send?", "check this before I mail it", "did I forget anything?", "is this ready for Certified Mail?", "should I send this with a return receipt?" or "what would it cost to send this certified?", or offer it once the person has said a letter, demand, dispute or notice will go by mail: "I can check whether this is ready for Certified Mail." It returns the printed page count (the same layout the review page charges for), the document type it reads as, the recipient and sender it found and whether each address is complete, the missing fields, unfilled placeholders such as [NAME], enclosures the letter mentions, a reply-by date written in the letter, the recommended service with the exact current price, and the next action. It checks mailing readiness, never legal sufficiency. It creates nothing, stores nothing, prints, mails and charges nothing, and needs no account. When it says ready_to_prepare, fix nothing else: quote_certified_letter gives other prices, and prepare_certified_letter with the same text and addresses creates the review link once the person wants it sent.
| Parameter | Type | Description |
|---|---|---|
| city | string | |
| state | string | Two-letter U.S. state code. |
| subject | string | The "Re:" line, if any. |
| letter_text | string | The letter body as it would print: salutation, paragraphs and closing, without the addresses or date (those come from the other fields). Up to 60,000 characters. Pass this OR document_text. |
| postal_code | string | Five-digit ZIP code. |
| sender_city | string | |
| sender_name | string | |
| sender_state | string | |
| address_line1 | string | Recipient street address. |
| address_line2 | string | |
| document_text | string | The full text of a document that is already finished and prints exactly as written, addresses and signature included. Up to 60,000 characters. Pass this OR letter_text. |
| recipient_name | string | |
| signature_name | string | Name printed under the closing. |
| desired_service | string | The service the person has in mind, if any; its price is returned as current_estimated_price. Left out, the recommended service is priced. |
| recipient_company | string | |
| sender_postal_code | string | |
| enclosures_supplied | array | Names of enclosures the person says they have, so an enclosure the letter mentions is not reported missing. |
| sender_address_block | string | The sender (return address) as written, one part per line. |
| sender_address_line1 | string | |
| recipient_address_block | string | The recipient as addressed, one part per line. Named recipient fields win over it. Left out, the recipient is read from the inside address in the text, if it has one. |
{
"name": "check_certified_letter",
"title": "Check a letter before it is mailed",
"description": "READ ONLY: checks a draft letter or a finished document BEFORE anything is prepared, and says whether it is ready to mail by USPS Certified Mail and what it would cost. Use it when the person asks \"is this ready to send?\", \"check this before I mail it\", \"did I forget anything?\", \"is this ready for Certified Mail?\", \"should I send this with a return receipt?\" or \"what would it cost to send this certified?\", or offer it once the person has said a letter, demand, dispute or notice will go by mail: \"I can check whether this is ready for Certified Mail.\" It returns the printed page count (the same layout the review page charges for), the document type it reads as, the recipient and sender it found and whether each address is complete, the missing fields, unfilled placeholders such as [NAME], enclosures the letter mentions, a reply-by date written in the letter, the recommended service with the exact current price, and the next action. It checks mailing readiness, never legal sufficiency. It creates nothing, stores nothing, prints, mails and charges nothing, and needs no account. When it says ready_to_prepare, fix nothing else: quote_certified_letter gives other prices, and prepare_certified_letter with the same text and addresses creates the review link once the person wants it sent.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"city": {
"type": "string"
},
"state": {
"type": "string",
"description": "Two-letter U.S. state code."
},
"subject": {
"type": "string",
"description": "The \"Re:\" line, if any."
},
"letter_text": {
"type": "string",
"description": "The letter body as it would print: salutation, paragraphs and closing, without the addresses or date (those come from the other fields). Up to 60,000 characters. Pass this OR document_text."
},
"postal_code": {
"type": "string",
"description": "Five-digit ZIP code."
},
"sender_city": {
"type": "string"
},
"sender_name": {
"type": "string"
},
"sender_state": {
"type": "string"
},
"address_line1": {
"type": "string",
"description": "Recipient street address."
},
"address_line2": {
"type": "string"
},
"document_text": {
"type": "string",
"description": "The full text of a document that is already finished and prints exactly as written, addresses and signature included. Up to 60,000 characters. Pass this OR letter_text."
},
"recipient_name": {
"type": "string"
},
"signature_name": {
"type": "string",
"description": "Name printed under the closing."
},
"desired_service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string",
"description": "The service the person has in mind, if any; its price is returned as current_estimated_price. Left out, the recommended service is priced."
},
"recipient_company": {
"type": "string"
},
"sender_postal_code": {
"type": "string"
},
"enclosures_supplied": {
"type": "array",
"items": {
"type": "string"
},
"maxItems": 10,
"description": "Names of enclosures the person says they have, so an enclosure the letter mentions is not reported missing."
},
"sender_address_block": {
"type": "string",
"description": "The sender (return address) as written, one part per line."
},
"sender_address_line1": {
"type": "string"
},
"recipient_address_block": {
"type": "string",
"description": "The recipient as addressed, one part per line. Named recipient fields win over it. Left out, the recipient is read from the inside address in the text, if it has one."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"ready_to_prepare",
"estimated_page_count",
"missing_fields",
"recommended_service",
"next_action",
"mailed",
"charged",
"stored"
],
"properties": {
"scope": {
"type": "string"
},
"mailed": {
"type": "boolean",
"description": "Always false."
},
"stored": {
"type": "boolean",
"description": "Always false: nothing from this call is kept."
},
"charged": {
"type": "boolean",
"description": "Always false."
},
"warnings": {
"type": "array",
"items": {
"type": "object"
}
},
"max_pages": {
"type": [
"integer",
"null"
]
},
"promotion": {
"type": [
"object",
"null"
],
"description": "Present when the first-letter promotion could lower this total; it is applied by the same rule at every checkout once the payer is known."
},
"next_action": {
"type": "string"
},
"document_type": {
"enum": [
"preliminary_notice",
"notice_of_intent_to_sue",
"debt_validation_request",
"credit_dispute",
"security_deposit_demand",
"notice_to_vacate",
"lease_termination",
"cease_and_desist",
"insurance_claim",
"contract_termination",
"demand_letter",
"legal_notice",
"general_letter"
],
"type": "string"
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"detected_sender": {
"type": "object"
},
"optional_upgrade": {
"type": "object",
"description": "Present when the letter reads as a dispute or demand that could reach a court or an agency: the Evidence Pack, its reasons and the extra cost. Never selected; mention it as an option only."
},
"ready_to_prepare": {
"type": "boolean",
"description": "True when nothing blocks mailing: the recipient address is complete, nothing is left to fix and the length fits the printer."
},
"prices_by_service": {
"type": "array",
"items": {
"type": "object"
}
},
"deadline_in_letter": {
"type": [
"object",
"null"
]
},
"detected_recipient": {
"type": "object"
},
"document_type_label": {
"type": "string"
},
"recommended_because": {
"type": "array",
"items": {
"type": "string"
}
},
"recommended_service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string"
},
"estimated_page_count": {
"type": "integer"
},
"current_estimated_price": {
"type": "object",
"description": "The exact current total for desired_service, or for the recommended service."
},
"requires_human_approval": {
"type": "boolean"
},
"sender_address_complete": {
"type": "boolean",
"description": "The sender can also be filled in on the review page, so an incomplete sender does not block preparing."
},
"recipient_read_from_text": {
"type": "boolean"
},
"recipient_address_complete": {
"type": "boolean"
},
"potential_deadline_detected": {
"type": "boolean",
"description": "True when the letter itself asks for an answer, payment or action by a date or within a number of days. Read from the text; it is not a legal deadline determination."
}
}
},
"annotations": {
"title": "Check a letter before it is mailed",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}READ ONLY. Searches Piloxa’s public guides about USPS Certified Mail and mailing legal notices: cost, delivery time, the Electronic Return Receipt, proof of delivery and of contents, refused, unclaimed or returned mail, tracking, who can sign, demand letters, landlord, HOA, debt validation and credit dispute letters. Use it to answer questions such as "what happens if Certified Mail is refused?" with a citable source. Returns up to 8 results, each with an id for fetch, a title, the page URL, an excerpt and a relevance score. Searches public pages only; no person’s letters are searchable.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | How many results, 1 to 8. Defaults to 5. |
| query * | string | The question or keywords, e.g. "certified mail refused". |
{
"name": "search",
"title": "Search Piloxa’s Certified Mail guides",
"description": "READ ONLY. Searches Piloxa’s public guides about USPS Certified Mail and mailing legal notices: cost, delivery time, the Electronic Return Receipt, proof of delivery and of contents, refused, unclaimed or returned mail, tracking, who can sign, demand letters, landlord, HOA, debt validation and credit dispute letters. Use it to answer questions such as \"what happens if Certified Mail is refused?\" with a citable source. Returns up to 8 results, each with an id for fetch, a title, the page URL, an excerpt and a relevance score. Searches public pages only; no person’s letters are searchable.",
"inputSchema": {
"type": "object",
"required": [
"query"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 8,
"minimum": 1,
"description": "How many results, 1 to 8. Defaults to 5."
},
"query": {
"type": "string",
"description": "The question or keywords, e.g. \"certified mail refused\"."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"title",
"url"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"title": {
"type": "string"
},
"excerpt": {
"type": "string"
},
"relevance": {
"type": "number"
}
}
}
}
}
},
"annotations": {
"title": "Search Certified Mail guides",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}READ ONLY. Returns the full text of one Piloxa guide by the id search returned (or its URL), with its title, canonical URL and last-updated date when the page states one. Prices in the text are the current ones.
| Parameter | Type | Description |
|---|---|---|
| id * | string | The id from search, e.g. "certified-mail-refused", or the page URL. |
{
"name": "fetch",
"title": "Read one Piloxa guide",
"description": "READ ONLY. Returns the full text of one Piloxa guide by the id search returned (or its URL), with its title, canonical URL and last-updated date when the page states one. Prices in the text are the current ones.",
"inputSchema": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The id from search, e.g. \"certified-mail-refused\", or the page URL."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"id",
"title",
"url",
"text"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"text": {
"type": "string"
},
"title": {
"type": "string"
},
"metadata": {
"type": "object"
}
}
},
"annotations": {
"title": "Read a Certified Mail guide",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}READ ONLY. Compares the mailing services Piloxa actually offers - what each includes, when to use it, which is the default - with the exact current all-in price of each for a page count, the first-letter promotion as conditions, and what Piloxa does not offer. Use it for "should I send this with return receipt?", "what’s the difference between your options?" or "how much more is the Evidence Pack?". Stores and charges nothing.
| Parameter | Type | Description |
|---|---|---|
| page_count | integer | Printed pages. Defaults to 1. |
{
"name": "compare_certified_mail_services",
"title": "Compare Piloxa’s mailing services",
"description": "READ ONLY. Compares the mailing services Piloxa actually offers - what each includes, when to use it, which is the default - with the exact current all-in price of each for a page count, the first-letter promotion as conditions, and what Piloxa does not offer. Use it for \"should I send this with return receipt?\", \"what’s the difference between your options?\" or \"how much more is the Evidence Pack?\". Stores and charges nothing.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"page_count": {
"type": "integer",
"minimum": 1,
"description": "Printed pages. Defaults to 1."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"page_count",
"services",
"mailed",
"charged"
],
"properties": {
"mailed": {
"type": "boolean"
},
"charged": {
"type": "boolean"
},
"services": {
"type": "array",
"items": {
"type": "object"
}
},
"promotion": {
"type": [
"object",
"null"
]
},
"page_count": {
"type": "integer"
},
"not_offered": {
"type": "array",
"items": {
"type": "string"
}
},
"price_source": {
"type": "string"
}
}
},
"annotations": {
"title": "Compare mailing services",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}READ ONLY. Explains a USPS tracking status ("Notice Left", "Available for Pickup", "Unclaimed", "Refused", "Return to Sender", "Insufficient Address", "Delivered, Left with Individual"...) or a Piloxa transaction state (AWAITING_APPROVAL, VENDOR_ACCEPTED, MAILED, DELIVERED...) in plain words, with the likely next step and the guide that explains it. It explains the status in general; for a specific letter prepared in this conversation use get_certified_letter_status. It never says whether a notice is legally effective.
| Parameter | Type | Description |
|---|---|---|
| status * | string | The status text exactly as shown, e.g. "Notice Left (No Authorized Recipient Available)". |
{
"name": "explain_certified_mail_status",
"title": "Explain a Certified Mail status",
"description": "READ ONLY. Explains a USPS tracking status (\"Notice Left\", \"Available for Pickup\", \"Unclaimed\", \"Refused\", \"Return to Sender\", \"Insufficient Address\", \"Delivered, Left with Individual\"...) or a Piloxa transaction state (AWAITING_APPROVAL, VENDOR_ACCEPTED, MAILED, DELIVERED...) in plain words, with the likely next step and the guide that explains it. It explains the status in general; for a specific letter prepared in this conversation use get_certified_letter_status. It never says whether a notice is legally effective.",
"inputSchema": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "The status text exactly as shown, e.g. \"Notice Left (No Authorized Recipient Available)\"."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"status",
"meaning",
"next"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"next": {
"type": "string"
},
"scope": {
"type": "string"
},
"status": {
"type": "string"
},
"meaning": {
"type": "string"
},
"guide_url": {
"type": "string"
}
}
},
"annotations": {
"title": "Explain a Certified Mail status",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}READ ONLY. Answers "does this notice have to go by Certified Mail or with a return receipt, by when, and to whom?" BEFORE any letter exists, from Piloxa’s curated table of U.S. statutes and regulations, each with its citation and official link. Use it when the person asks things like "do I have to send this certified?", "how long does my landlord have to return my deposit?", "how do I dispute a debt with a collector?", "is there a deadline to dispute this credit card charge?" or "what notice do I need before suing a business?". Covers federal rules (debt validation and cease contact, credit report disputes, credit card billing errors, loan rescission, door-to-door sales) and some state rules (deposits, repair notices, month-to-month termination, consumer demand letters in CA, TX, FL and MA). When the table has no rule it says "unknown" (coverage not_covered); never present that as "not required". It is general information with sources, not legal advice; say so. It creates, stores, mails and charges nothing. When the person wants to send the notice, draft it with what_to_include and call prepare_certified_letter.
| Parameter | Type | Description |
|---|---|---|
| state | string | Two-letter U.S. state code where the rule would apply (usually where the property is or where the person lives). Left out, it is read from the situation if named. |
| situation * | string | The person’s situation in their words, e.g. "I moved out of my Texas apartment 5 weeks ago and the landlord kept my deposit". Up to 2,000 characters; leave out account numbers and other private details. |
| notice_type | string | Optional. The kind of notice, if clear; otherwise it is read from the situation. |
{
"name": "check_notice_requirement",
"title": "Check if a notice must go by Certified Mail",
"description": "READ ONLY. Answers \"does this notice have to go by Certified Mail or with a return receipt, by when, and to whom?\" BEFORE any letter exists, from Piloxa’s curated table of U.S. statutes and regulations, each with its citation and official link. Use it when the person asks things like \"do I have to send this certified?\", \"how long does my landlord have to return my deposit?\", \"how do I dispute a debt with a collector?\", \"is there a deadline to dispute this credit card charge?\" or \"what notice do I need before suing a business?\". Covers federal rules (debt validation and cease contact, credit report disputes, credit card billing errors, loan rescission, door-to-door sales) and some state rules (deposits, repair notices, month-to-month termination, consumer demand letters in CA, TX, FL and MA). When the table has no rule it says \"unknown\" (coverage not_covered); never present that as \"not required\". It is general information with sources, not legal advice; say so. It creates, stores, mails and charges nothing. When the person wants to send the notice, draft it with what_to_include and call prepare_certified_letter.",
"inputSchema": {
"type": "object",
"required": [
"situation"
],
"properties": {
"state": {
"type": "string",
"description": "Two-letter U.S. state code where the rule would apply (usually where the property is or where the person lives). Left out, it is read from the situation if named."
},
"situation": {
"type": "string",
"description": "The person’s situation in their words, e.g. \"I moved out of my Texas apartment 5 weeks ago and the landlord kept my deposit\". Up to 2,000 characters; leave out account numbers and other private details."
},
"notice_type": {
"enum": [
"security_deposit",
"repair_request",
"lease_termination",
"consumer_demand",
"debt_validation",
"debt_cease_contact",
"credit_report_dispute",
"billing_error",
"loan_rescission",
"door_to_door_cancellation",
"contract_termination",
"employment"
],
"type": "string",
"description": "Optional. The kind of notice, if clear; otherwise it is read from the situation."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"coverage",
"certified_mail_required",
"rules",
"answer",
"disclaimer",
"next_action",
"mailed",
"charged"
],
"properties": {
"gap": {
"type": "string"
},
"rules": {
"type": "array",
"items": {
"type": "object"
},
"description": "Each rule: title, jurisdiction, applies_to, certified_mail, return_receipt, deadline, address_to, what_to_include, source { citation, url, last_reviewed }."
},
"state": {
"type": [
"string",
"null"
]
},
"answer": {
"type": "string"
},
"mailed": {
"type": "boolean"
},
"stored": {
"type": "boolean"
},
"charged": {
"type": "boolean"
},
"handoff": {
"type": [
"object",
"null"
]
},
"coverage": {
"enum": [
"covered",
"federal_only",
"state_needed",
"not_covered"
],
"type": "string",
"description": "not_covered means the requirement is unknown, not that there is none."
},
"disclaimer": {
"type": "string"
},
"next_action": {
"type": "string"
},
"notice_type": {
"type": [
"string",
"null"
]
},
"practical_note": {
"type": "string"
},
"situation_read_as": {
"type": [
"string",
"null"
]
},
"certified_mail_required": {
"type": "string",
"description": "required, required_for_one_party (see each rule), permitted, alternative_to_step, not_required, not_required_federally_state_unknown, or unknown."
}
}
},
"annotations": {
"title": "Check a notice requirement",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Buys and sends a letter that prepare_certified_letter prepared IN THIS CONVERSATION, after the person approved the exact total here. Call it only when (1) you have told the person the exact total, the recipient and the service, and they said yes to that total in this conversation, and (2) your platform has given you a Stripe shared payment token (spt_...) granted to Piloxa for that amount. Piloxa holds the payment, hands the letter to the printer, and charges only once the printer accepts it; if the printer refuses, the hold is released and nothing is charged. ALWAYS pass one idempotency_key per purchase and reuse it on every retry: the same key never charges twice and returns what already happened. If the total, the document or the address changed since the person approved, nothing is charged and you must ask again. Without a token, or if paying here is unavailable, nothing is charged and approval_url is returned: give it to the person, who pays there. The result carries transaction_state: AWAITING_APPROVAL, AUTHORIZED, VENDOR_ACCEPTED, MAILED, DELIVERED, RETURNED, FAILED or CANCELLED. Say a letter was sent only at VENDOR_ACCEPTED or later. At AUTHORIZED with failure OUTCOME_UNCERTAIN, do NOT retry: call get_certified_letter_status.
| Parameter | Type | Description |
|---|---|---|
| quote_id | string | Optional: the quote_id prepare_certified_letter returned. It binds the approval to that exact document, recipient, sender, service and total; if any of them changed or it expired, nothing is charged and you must ask again. |
| mailing_id * | string | The mailing_id prepare_certified_letter returned in this conversation. |
| payer_email * | string | Where the receipt, the tracking and the mailing record go. |
| user_approved * | boolean | True only when the person explicitly approved this exact total, recipient and service in this conversation. |
| document_sha256 | string | Optional: the document_sha256 prepare_certified_letter returned. If the document changed since, nothing is charged. |
| idempotency_key * | string | One key per purchase, 16 to 100 letters, digits or _ . : -. Reuse the same key on every retry of this purchase; a new key is a new purchase attempt. |
| approval_statement | string | The words the person was shown and said yes to, for the record, e.g. "Send this letter to Acme Property Management by USPS Certified Mail with return receipt for" followed by the exact total. |
| expected_total_cents * | integer | The exact total the person approved, in cents: the total_cents or estimated_total_cents Piloxa returned. If the current total differs, nothing is charged. |
| shared_payment_token | string | A Stripe shared payment token (spt_...) your platform issued to Piloxa for this purchase, limited to the approved amount. |
{
"name": "authorize_certified_letter",
"title": "Buy and send a prepared certified letter",
"description": "Buys and sends a letter that prepare_certified_letter prepared IN THIS CONVERSATION, after the person approved the exact total here. Call it only when (1) you have told the person the exact total, the recipient and the service, and they said yes to that total in this conversation, and (2) your platform has given you a Stripe shared payment token (spt_...) granted to Piloxa for that amount. Piloxa holds the payment, hands the letter to the printer, and charges only once the printer accepts it; if the printer refuses, the hold is released and nothing is charged. ALWAYS pass one idempotency_key per purchase and reuse it on every retry: the same key never charges twice and returns what already happened. If the total, the document or the address changed since the person approved, nothing is charged and you must ask again. Without a token, or if paying here is unavailable, nothing is charged and approval_url is returned: give it to the person, who pays there. The result carries transaction_state: AWAITING_APPROVAL, AUTHORIZED, VENDOR_ACCEPTED, MAILED, DELIVERED, RETURNED, FAILED or CANCELLED. Say a letter was sent only at VENDOR_ACCEPTED or later. At AUTHORIZED with failure OUTCOME_UNCERTAIN, do NOT retry: call get_certified_letter_status.",
"inputSchema": {
"type": "object",
"required": [
"mailing_id",
"expected_total_cents",
"idempotency_key",
"user_approved",
"payer_email"
],
"properties": {
"quote_id": {
"type": "string",
"description": "Optional: the quote_id prepare_certified_letter returned. It binds the approval to that exact document, recipient, sender, service and total; if any of them changed or it expired, nothing is charged and you must ask again."
},
"mailing_id": {
"type": "string",
"description": "The mailing_id prepare_certified_letter returned in this conversation."
},
"payer_email": {
"type": "string",
"description": "Where the receipt, the tracking and the mailing record go."
},
"user_approved": {
"type": "boolean",
"description": "True only when the person explicitly approved this exact total, recipient and service in this conversation."
},
"document_sha256": {
"type": "string",
"description": "Optional: the document_sha256 prepare_certified_letter returned. If the document changed since, nothing is charged."
},
"idempotency_key": {
"type": "string",
"description": "One key per purchase, 16 to 100 letters, digits or _ . : -. Reuse the same key on every retry of this purchase; a new key is a new purchase attempt."
},
"approval_statement": {
"type": "string",
"description": "The words the person was shown and said yes to, for the record, e.g. \"Send this letter to Acme Property Management by USPS Certified Mail with return receipt for\" followed by the exact total."
},
"expected_total_cents": {
"type": "integer",
"description": "The exact total the person approved, in cents: the total_cents or estimated_total_cents Piloxa returned. If the current total differs, nothing is charged."
},
"shared_payment_token": {
"type": "string",
"description": "A Stripe shared payment token (spt_...) your platform issued to Piloxa for this purchase, limited to the approved amount."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"transaction_state",
"charged",
"mailed"
],
"properties": {
"mailed": {
"type": "boolean"
},
"charged": {
"type": "boolean"
},
"failure": {
"type": [
"object",
"null"
]
},
"receipt": {
"type": [
"object",
"null"
]
},
"service": {
"type": [
"string",
"null"
]
},
"currency": {
"type": "string"
},
"replayed": {
"type": "boolean",
"description": "True when this answers an earlier call with the same idempotency key, or a purchase already under way."
},
"recipient": {
"type": "object"
},
"reference": {
"type": [
"string",
"null"
],
"description": "The Piloxa mailing reference, once the letter exists as a mailing."
},
"mailing_id": {
"type": [
"string",
"null"
]
},
"final_quote": {
"type": [
"object",
"null"
],
"description": "When the total differs from expected_total_cents: the standard total, discount, payable total, currency and first-letter status for this payer. Ask the person to approve payable_total_cents."
},
"amount_cents": {
"type": [
"integer",
"null"
]
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Where the person can review and pay instead."
},
"practice_run": {
"type": [
"boolean",
"null"
]
},
"state_meaning": {
"type": "string"
},
"document_sha256": {
"type": [
"string",
"null"
]
},
"amount_held_cents": {
"type": "integer"
},
"printer_reference": {
"type": [
"string",
"null"
]
},
"transaction_state": {
"enum": [
"PREPARED",
"AWAITING_APPROVAL",
"AUTHORIZED",
"VENDOR_ACCEPTED",
"MAILED",
"DELIVERED",
"RETURNED",
"FAILED",
"CANCELLED",
null
],
"type": [
"string",
"null"
]
},
"amount_charged_cents": {
"type": "integer"
},
"usps_tracking_number": {
"type": [
"string",
"null"
]
}
}
},
"annotations": {
"title": "Buy and send a prepared certified letter",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": true
}
}Use when the person wants to see, track or follow up on letters they sent with Piloxa in ANOTHER conversation, or wants their saved return address used. Returns a link and a 4-character code. Give the person both: they open the link, sign in with their email on piloxa.com, check the code matches, and press Allow. Only then can list_my_letters, get_my_letter and create_followup_draft see their letters, and only in this chat. It reads nothing, mails nothing and charges nothing. The person can disconnect at any time on that page.
No parameters.
{
"name": "connect_my_letters",
"title": "Connect this chat to the person’s Piloxa letters",
"description": "Use when the person wants to see, track or follow up on letters they sent with Piloxa in ANOTHER conversation, or wants their saved return address used. Returns a link and a 4-character code. Give the person both: they open the link, sign in with their email on piloxa.com, check the code matches, and press Allow. Only then can list_my_letters, get_my_letter and create_followup_draft see their letters, and only in this chat. It reads nothing, mails nothing and charges nothing. The person can disconnect at any time on that page.",
"inputSchema": {
"type": "object",
"properties": {}
},
"outputSchema": {
"type": "object",
"required": [
"connected"
],
"properties": {
"connected": {
"type": "boolean"
},
"expires_at": {
"type": [
"string",
"null"
]
},
"match_code": {
"type": [
"string",
"null"
]
},
"connect_url": {
"type": [
"string",
"null"
]
}
}
},
"annotations": {
"title": "Connect this chat to my letters",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}READ ONLY. The person’s own recent Piloxa letters, from any conversation, once this chat is connected with connect_my_letters. Optional query matches the recipient’s name or company, or the start of a Piloxa reference. Returns reference, recipient name, service, status, dates and where the status came from; never the letter text or full addresses. Without a connection it returns how to connect and nothing else.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | |
| query | string | Optional: a recipient name or company, or the start of a reference. |
{
"name": "list_my_letters",
"title": "List the person’s letters",
"description": "READ ONLY. The person’s own recent Piloxa letters, from any conversation, once this chat is connected with connect_my_letters. Optional query matches the recipient’s name or company, or the start of a Piloxa reference. Returns reference, recipient name, service, status, dates and where the status came from; never the letter text or full addresses. Without a connection it returns how to connect and nothing else.",
"inputSchema": {
"type": "object",
"properties": {
"limit": {
"type": "integer",
"maximum": 25,
"minimum": 1
},
"query": {
"type": "string",
"description": "Optional: a recipient name or company, or the start of a reference."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"connected"
],
"properties": {
"found": {
"type": "integer"
},
"letters": {
"type": "array",
"items": {
"type": "object"
}
},
"connected": {
"type": "boolean"
}
}
},
"annotations": {
"title": "List my letters",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}READ ONLY. The current status of one of the person’s own letters by its Piloxa reference, once this chat is connected: printer acceptance, USPS acceptance, delivery or return, the return receipt, each with its source and when it was last checked, the reply-by date if the letter set one, and where to download the mailing record (signed in on piloxa.com). A missing USPS scan means unknown, not failed; delivered does not mean read; a passed reply-by date does not mean nobody answered. Ask the person whether a reply arrived before suggesting a follow-up.
| Parameter | Type | Description |
|---|---|---|
| reference * | string | The Piloxa reference (act...) from list_my_letters. |
{
"name": "get_my_letter",
"title": "One of the person’s letters",
"description": "READ ONLY. The current status of one of the person’s own letters by its Piloxa reference, once this chat is connected: printer acceptance, USPS acceptance, delivery or return, the return receipt, each with its source and when it was last checked, the reply-by date if the letter set one, and where to download the mailing record (signed in on piloxa.com). A missing USPS scan means unknown, not failed; delivered does not mean read; a passed reply-by date does not mean nobody answered. Ask the person whether a reply arrived before suggesting a follow-up.",
"inputSchema": {
"type": "object",
"required": [
"reference"
],
"properties": {
"reference": {
"type": "string",
"description": "The Piloxa reference (act...) from list_my_letters."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"connected"
],
"properties": {
"letter": {
"type": [
"object",
"null"
]
},
"connected": {
"type": "boolean"
}
}
},
"annotations": {
"title": "Get my letter",
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true,
"destructiveHint": false
}
}Prepares a NEW letter to the same recipient as one of the person’s earlier letters (by reference), from the account’s saved return address, with the follow-up text you wrote with the person. It works exactly like prepare_certified_letter and returns a new review link: nothing from the earlier purchase carries over, and nothing is mailed or charged until the person reviews and pays for this new letter. Write the follow-up only after the person says no reply arrived or asks for one.
| Parameter | Type | Description |
|---|---|---|
| service | string | Optional. Defaults to CERTIFIED_ERR, whatever the earlier letter used. |
| reference * | string | The earlier letter’s Piloxa reference. |
| letter_text * | string | The body of the follow-up you wrote with the person. |
{
"name": "create_followup_draft",
"title": "Prepare a follow-up to an earlier letter",
"description": "Prepares a NEW letter to the same recipient as one of the person’s earlier letters (by reference), from the account’s saved return address, with the follow-up text you wrote with the person. It works exactly like prepare_certified_letter and returns a new review link: nothing from the earlier purchase carries over, and nothing is mailed or charged until the person reviews and pays for this new letter. Write the follow-up only after the person says no reply arrived or asks for one.",
"inputSchema": {
"type": "object",
"required": [
"reference",
"letter_text"
],
"properties": {
"service": {
"enum": [
"CERTIFIED",
"CERTIFIED_ERR",
"CERTIFIED_EVIDENCE",
"CERTIFIED_DEADLINE"
],
"type": "string",
"description": "Optional. Defaults to CERTIFIED_ERR, whatever the earlier letter used."
},
"reference": {
"type": "string",
"description": "The earlier letter’s Piloxa reference."
},
"letter_text": {
"type": "string",
"description": "The body of the follow-up you wrote with the person."
}
}
},
"annotations": {
"title": "Prepare a follow-up letter",
"readOnlyHint": false,
"openWorldHint": true,
"idempotentHint": false,
"destructiveHint": false
}
}Piloxa prepares physical letters for USPS Certified Mail to U.S. addresses: it prints the document, puts it in an envelope, pays the postage and hands it to USPS, with tracking and a record of exactly what was sent. Human approval is required before payment or mailing. Use it when the person wants a letter or document physically mailed, asks what Certified Mail costs, asks whether a letter is ready to mail, or asks about a letter they sent through Piloxa. Typical letters: demands (deposit, refund, contractor), credit disputes, debt validation, cease-and-desist, notices to a landlord, tenant, HOA or employer, intent to sue, notice to cure, pre-lien notices, lease terminations, insurance disputes. Do not use it when the person only wants a letter drafted, edited, translated, saved or emailed, or asked for ordinary mail, international mail, bulk mail or service of process; Piloxa does not decide whether mailing is legally sufficient. One call to prepare_certified_letter creates an unsent draft and returns a link where the person reads the exact document, sees the total ($9.95 for a person’s first letter of one or two pages; after that $12.97 for one page by Certified Mail with tracking, $15.97 with the return receipt), pays and approves; the preview is free with no account, and the person verifies their email when they send. A missing address does not block the draft: the person can complete it on that page. A person's first letter is $9.95 all in: one or two pages by Certified Mail with tracking, without the return receipt, one per account. Keep a letter within 10 printed pages (about 4,000 words). When the person asks "is this ready to send?", "did I forget anything?" or what it costs, call check_certified_letter: it is read only, stores nothing, and returns the page count, what is missing, the recommended service and the exact current price. Once the person has said a letter will go by mail, you may offer: "I can check whether this is ready for Certified Mail." If they ask whether a notice must go certified, or by when, call check_notice_requirement. The tools here only CHECK, QUOTE and PREPARE: nothing is mailed or charged until the person approves on that page. Usual order: check, quote if asked, prepare, the person pays on the link, then status, which reports only what USPS has reported. The review link is the normal way to pay. Only where your platform really gives you a Stripe shared payment token for the exact total (never make one up, never ask for card details in chat), the person can also approve and pay without leaving the conversation: state the exact total, recipient and service, get their explicit yes for that total, then call authorize_certified_letter with the mailing_id from prepare_certified_letter and one idempotency key you reuse on every retry. Its transaction_state says exactly where the letter stands; never say a letter was sent before it reads VENDOR_ACCEPTED or later.
Names, descriptions and schemas were written by the server and are shown as data.