Skip to main content
Glama

Certified Mail Sender

Create a certified letter draft

create_letter
DestructiveIdempotent

Create a US domestic letter draft from exactly one of text, pdf_base64 or pdf_url. Creating a draft is free. Drafts cannot be edited. To change the text, an address or the service: create_letter with a new idempotency_key, give the person the new approval_url, then cancel_letter the old draft so the person cannot pay for the outdated draft. Tell the person the price from quote_letter before making the draft, unless they have already seen it. Unknown fields in the input, to or from are rejected with invalid_request; error.fix names each unknown field. Use organization for a company name, not company. For a return receipt, use service certified_err. An undeliverable address returns error.address_reason with a stable code, affected fields and USPS lookup URL; ask the person about that specific part. One page costs $9.04 for certified or $12.24 with an electronic Return Receipt; use quote_letter for the exact page count. Show approval_url to the person who will review and pay. For text, send the body from the greeting on; we add both addresses and the date. A different leading address block or date is refused with text_has_letterhead (422); remove the line named in the error. People who prefer to write or upload it themselves can use https://certifiedmailsender.com/send. Paid letters wait 30 minutes; send_now:true skips that hold only when the person asks. Screening still applies. Normally the person approves and pays; an auto-send key pays from its account balance. No refund once USPS accepts the letter, even if USPS can't deliver it. If the person mentioned a deadline, compare it with the delivery estimate and tell them plainly when the estimate falls after it. Test mode never mails. Example: {"to":{"name":"Jordan Lee","line1":"500 Market St","line2":"Suite 200","city":"Philadelphia","state":"PA","zip":"19106"},"from":{"name":"Sam Ortiz","line1":"12 Oak Ave","city":"Columbus","state":"OH","zip":"43215"},"service":"certified_err","text":"Dear Jordan,\n\n...","idempotency_key":""}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "to": "<to>",
      "from": "<from>",
      "service": "<service>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "create_letter"
  }
}

Input Schema

NameRequiredDescriptionDefault
toYesRecipient address, checked by our printing partner against USPS records. If undeliverable during creation, the request is refused with address_undeliverable (422) and no draft is created. Read error.address_reason for its stable code, affected fields, plain explanation and USPS lookup URL; ask the person the specific question rather than guessing variants.
fromYes
textNoThe letter body, from the greeting on. We add the sender's address, the date and the recipient's address. Complete matching leading blocks are removed; a different leading address block or date is refused with text_has_letterhead (422), naming the line to remove. Subject lines and addresses after the greeting or first prose are allowed. Provide exactly one of text, pdf_base64 or pdf_url.
pdf_urlNo
serviceYescertified sends USPS Certified Mail with USPS tracking. certified_err adds the electronic Return Receipt: a USPS PDF with the recipient's signature, once USPS provides it. Choose certified_err when the person wants proof of receipt.
send_nowNoChoose true only when the person asks to skip the 30-minute cancellation hold after payment. Payment and any required approval are still required (auto-send pays from balance without per-letter approval), and every screening check must pass before submission. The letter can be canceled only until it is sent to the printing partner; skipping leaves no guaranteed cancellation period.
pdf_base64No
idempotency_keyYesUse a new UUID for a new letter; reuse it with the same body on retries. Anonymous keys need at least 16 characters.

Output Schema

NameRequiredDescriptionDefault
idYes
toYes
fromYes
modeYes
pagesYes
quoteYes
stateYesPersisted lifecycle state, not proof of mailing. printed comes from a Printed tracking observation; USPS acceptance requires proof_of_mailing. Reads can skip intermediate states. Test letters stop at submitted and never print or mail.
originYes
refundYesRefund record for a canceled, rejected or failed letter; null when no refund is due. Use state and amount_cents to tell the person what happened to their payment. Card refunds usually show within 5 to 10 business days; the bank decides exactly when.
serviceYes
send_nowYesWhether someone chose to skip the 30-minute cancellation hold. This never skips required payment or screening; auto-send keys have no per-letter approval step.
timelineYes
next_stepYes
created_atYesUTC RFC 3339 timestamp with milliseconds, YYYY-MM-DDTHH:mm:ss.sssZ.
letter_urlYesKeep this complete private link, including its t token. An anonymous letter can be read and canceled only with that token; an id alone or an API key created later cannot open it. A letter created with an API key can also be read and canceled with that same key.
preview_urlYes
receipt_urlNoPrivate token link to the USPS electronic Return Receipt PDF. Present only for certified_err in receipt_ready while files are retained; omitted means no downloadable receipt is available here, not that delivery failed. Keep the t token; this receipt is private like the letter PDF.
review_noteYes
address_noteYesThe address partner’s raw note, not wording to relay to the person. Use next_step for the plain-language version to tell the person.
approval_urlNoPrivate review page with the expected mailing date and USPS delivery estimate (not guaranteed). If the person mentioned a deadline, compare it with the delivery estimate and tell them plainly when the estimate falls after it.
cancel_untilYesThe scheduled end of the 30-minute cancellation hold, as an ISO 8601 / UTC RFC 3339 timestamp with milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ); null for drafts or letters no longer cancellable. If skipped, this is when sending became eligible after payment. Cancellation remains possible until actual submission, even after this timestamp or during review; no extra cancellation period is guaranteed.
tracking_urlYes
address_statusYes
document_sourceYes
first_usps_scanYesEarliest recorded individual-letter USPS scan, including acceptance: at is UTC, date is the scan’s local YYYY-MM-DD date, scan is USPS’s wording. Excludes shipment acceptance-pending and printing-partner scans. Null means no individual-letter scan is recorded, not that the letter was never mailed. Only proof_of_mailing establishes an acceptance date.
tracking_numberYes
address_as_givenYes
files_deleted_atYesUTC time the letter files were deleted, or null. After deletion, preview_url is retained for compatibility but no longer downloads a file; receipt_url is omitted. Tracking and the record stay available at letter_url.
proof_of_mailingYesThe acceptance scan records when USPS accepted the letter; null until an acceptance scan is recorded. Assistants cite date as the mailing date. This is not a postmarked receipt or a legal-status determination.
partner_checked_atYesUTC time of the last successful live tracking poll recorded by this service, even if USPS supplied no new scans. Null means no successful poll time is recorded (including test or legacy letters). A read never polls the partner; this is not a delivery or mailing time or a freshness guarantee.
acceptance_expected_byYesEastern date (YYYY-MM-DD) by whose end the acceptance scan usually appears. Present from submission while no acceptance or individual-piece network/delivery scan is recorded and next_step gives this date. Null after an individual-piece scan even if acceptance is missing; proof_of_mailing remains null. Before it ends, tell the person when to contact support; after it ends, contact support now so we can check with the printing partner and USPS.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations by disclosing that creation is free, drafts are immutable, paid letters sit in a 30-minute hold, there is no refund once USPS accepts, test mode never mails, and auto-send keys pay from account balance. It also names concrete failure behaviors (invalid_request, address_undeliverable, text_has_letterhead with the line to remove). The only shortfall is that permission/auth requirements and rate limits are never mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence carries operational weight, but the paragraph is a single undifferentiated block that zigzags from error codes to pricing to return receipts to approval URLs to test mode. The letterhead rule and the text-body rule are duplicated almost verbatim in the input schema, costing space without adding meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a money-moving, address-screening, multi-step tool with nested objects and an output schema, the description covers the full loop: price disclosure before drafting, approval_url handoff, cancellation window, refund limits, error recovery, and test-mode behavior. Return-value details can be left to the output schema, which exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 63%, and the description compensates: it flags 'Use organization for a company name, not company', explains certified_err versus certified in user terms, clarifies that send_now skips only the hold and still requires payment/approval, and states the retry semantics of idempotency_key. The text/pdf_base64/pdf_url exclusivity is restated from the schema rather than added to, so it is not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource+scope: 'Create a US domestic letter draft from exactly one of text, pdf_base64 or pdf_url.' The mutually exclusive content source is stated up front, and the description repeatedly contrasts this tool with quote_letter, cancel_letter and the self-serve URL, so an agent can place it precisely among siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing rules: quote_letter first to show price 'unless they have already seen it'; to change anything, re-create with a new idempotency_key and cancel_letter the old draft; use certified_err when a return receipt is wanted; send_now:true only when the person asks; direct do-it-yourself users to the external URL. Both when-to-use and when-not-to-use are covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources