Get a letter's status
get_letterRead a letter's state, timeline, tracking, proof_of_mailing, acceptance_expected_by, cancel_until, send_now, refund and next step. proof_of_mailing gives the USPS acceptance record; cite its local date as the mailing date. acceptance_expected_by gives the Eastern deadline while waiting, and is null after an individual-piece scan even if acceptance is missing. Relay next_step for the plain explanation. refund gives state, amount_cents and destination (card or balance). accepted means the processor accepted it or the balance was credited, not that the bank has posted it; manual means we will refund it by hand. Address checks usually finish in seconds. A pending address_status is retried each minute for up to a day; read again after a minute. A busy queue or partner delay can slow the check. Reading is free and changes nothing. first_usps_scan identifies the earliest individual-letter scan, not shipment receipt; only proof_of_mailing establishes acceptance. partner_checked_at is the last successful tracking poll, not the scan date. files_deleted_at means downloads are gone. Repeated adjacent checks carry observations and last_at; at stays the first check. Timestamps are UTC RFC 3339 with milliseconds; date-only fields retain their documented calendar dates. If the person mentioned a deadline, compare it with the delivery estimate and tell them plainly when the estimate falls after it. Use id with its API key, or the complete private letter_url from create_letter. 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": "get_letter"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Letter id; send the API key that created it in Authorization. | |
| letter_url | No | Complete private letter_url or approval_url, including its t token. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| to | Yes | ||
| from | Yes | ||
| mode | Yes | ||
| pages | Yes | ||
| quote | Yes | ||
| state | Yes | Persisted 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. | |
| origin | Yes | ||
| refund | Yes | Refund 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. | |
| service | Yes | ||
| send_now | Yes | Whether 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. | |
| timeline | Yes | ||
| next_step | Yes | ||
| created_at | Yes | UTC RFC 3339 timestamp with milliseconds, YYYY-MM-DDTHH:mm:ss.sssZ. | |
| letter_url | Yes | Keep 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_url | Yes | ||
| receipt_url | No | Private 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_note | Yes | ||
| address_note | Yes | The 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_url | No | Private 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_until | Yes | The 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_url | Yes | ||
| address_status | Yes | ||
| document_source | Yes | ||
| first_usps_scan | Yes | Earliest 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_number | Yes | ||
| address_as_given | Yes | ||
| files_deleted_at | Yes | UTC 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_mailing | Yes | The 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_at | Yes | UTC 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_by | Yes | Eastern 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. |