Skip to main content
Glama

Certified Mail Sender

Cancel a letter

cancel_letter
Destructive

Cancel before submission to the printing partner and refund any payment in full. Read refund.state, refund.amount_cents and refund.destination in the result; do not claim a refund succeeded unless its state is accepted. Card refunds go back to the card paid with and usually show within 5 to 10 business days; the bank decides exactly when. Balance refunds return to the prepaid balance. Paid letters normally have a 30-minute hold. Canceling is free; a submitted letter cannot be canceled. Read the returned refund and next_step; cancellation does not mail anything. Use id with its API key, or the complete private letter_url. Example: {"letter_url":"https://certifiedmailsender.com/l/?t="}

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "cancel_letter"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoLetter id; send the API key that created it in Authorization.
letter_urlNoComplete private letter_url or approval_url, including its t token.

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.7/5.0
Behavior4/5

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

Goes well beyond destructiveHint=true by explaining what is destroyed (only unsent letters), that cancellation is free, the 30-minute hold window, refund destinations, and bank-driven 5-10 business day timing. One gap: it never states authorization scope for the letter_url token beyond 'complete private letter_url', and output interpretation is partly deferred to the output schema.

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

Conciseness4/5

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

Front-loaded with the core action and effect, and nearly every clause carries operational weight. It is slightly overloaded and mildly repetitive, telling the agent to read refund.state twice ('Read refund.state...' and 'Read the returned refund and next_step').

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 destructive, open-world mutation with an output schema, the description covers the preconditions, the irreversibility boundary, refund verification rules ('do not claim a refund succeeded unless its state is accepted'), and the non-effect on mailing. An agent has everything needed to call it and report results honestly.

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

Parameters5/5

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

Schema coverage is already 100%, but the description adds genuine meaning: the two parameters are alternatives (auth via id + API key, or a complete private letter_url carrying its t token), and it supplies a concrete example URL. That resolves the either/or choice the schema alone leaves implicit.

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?

States a specific verb and resource ('cancel' a 'letter') plus the operative constraint ('before submission to the printing partner') and the side effect ('refund any payment in full'). This is immediately distinguishable from create_letter, get_letter, quote_letter, send_letter_now and list_letters.

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?

Gives explicit when-can and when-cannot: cancellation is free and allowed during the normal 30-minute hold for paid letters, but 'a submitted letter cannot be canceled.' It also notes that no mailing occurs, so an agent knows not to combine it with a send path.

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