{"openapi":"3.1.0","info":{"title":"Certified Mail Sender API","version":"1.0.0","description":"Create a draft, send approval_url to the person, and follow its status after they approve and pay. Payment and screening are required. An auto-send key pays from prepaid balance without per-letter approval once the address is confirmed, including USPS corrections. Paid letters wait 30 minutes before submission to the printer unless send_now is true or sendLetterNow is called. Every letter must pass screening. Certified Mail Sender is operated by Legitimate LLC and is not affiliated with, endorsed by or sponsored by the United States Postal Service. USPS and Certified Mail are trademarks of the United States Postal Service. Read get_letter (REST: GET /v1/letters/{id}) for next_step and timeline. first_usps_scan is the earliest individual-letter USPS scan (at, local date, scan); shipment receipt is excluded. Only proof_of_mailing establishes acceptance. partner_checked_at is the last successful live tracking poll, not a scan time; null means no recorded poll, including legacy/test letters. files_deleted_at means files are gone; preview_url is retained but unavailable. timeline.observations and timeline.last_at summarize adjacent identical checks; at stays the first time. Scans/transitions stay separate. All timestamp fields use UTC RFC 3339 with milliseconds; date-only scan dates stay local, acceptance_expected_by is Eastern. receipt_url appears only in receipt_ready for certified_err with files retained; absence means no receipt download, not failed delivery. acceptance_expected_by is null before submission, after acceptance/individual scan, or file deletion; null is not proof. States: draft, paid, screening, review, submitted, printed, mailed, in_transit, delivered, receipt_ready, canceled, failed, returned, refunded. printed comes from a Printed tracking observation, not USPS acceptance; reads may skip states. Test letters never print/mail and stop at submitted. quote.partner_cost_cents is public printing/postage cost; total_cents adds the itemized 10% fee, before applicable Stripe sales tax. Trusted auto-send keys pay from balance after address confirmation, including USPS corrections; screening/hold still apply."},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Quote":{"type":"object","properties":{"service":{"type":"string","enum":["certified","certified_err"]},"pages":{"type":"integer","minimum":1,"maximum":10},"line_items":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["postage","printing","service_fee"]},"label":{"type":"string"},"amount_cents":{"type":"integer","minimum":0}},"required":["code","label","amount_cents"]}},"total_cents":{"type":"integer","minimum":0},"partner_cost_cents":{"type":"integer","minimum":0,"description":"Public printing-and-postage cost in USD cents. The itemized price adds a 10% service fee; total_cents is before any Stripe sales tax."},"currency":{"type":"string","enum":["usd"]}},"required":["service","pages","line_items","total_cents","partner_cost_cents","currency"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fix":{"type":"string"},"address_reason":{"type":"object","properties":{"code":{"type":"string","enum":["unit_required","street_number_unconfirmed","street_not_found","city_zip_mismatch","mailbox_unconfirmed","address_unconfirmed"]},"fields":{"type":"array","items":{"type":"string"}},"message":{"type":"string"},"partner_message":{"type":"string"},"lookup_url":{"type":"string"}},"required":["code","fields","message","partner_message","lookup_url"],"description":"Present for address_undeliverable. Stable reason code and implicated recipient fields (empty when the verdict names no specific field), plain explanation, original partner verdict and USPS lookup URL. For street_not_found only to.line1 is implicated; the lookup opens a blank address search for another street spelling. No draft was created; ask the person about these fields."}},"required":["code","message","fix"]}},"required":["error"]},"QuoteRequest":{"type":"object","properties":{"service":{"type":"string","enum":["certified","certified_err"]},"pages":{"type":"integer","minimum":1,"maximum":10,"description":"Page count from 1 to 10. Provide exactly one of pages or pdf_base64; omit pages when providing a PDF."},"pdf_base64":{"type":"string","description":"A base64-encoded PDF whose pages we count for the quote. Provide exactly one of pages or pdf_base64; omit pages when providing a PDF. Neither field takes precedence: sending both is rejected, even if the counts agree."}},"required":["service"],"additionalProperties":false,"description":"Unknown fields are rejected with invalid_request (422), naming each unknown field and the accepted fields in error.fix. For a return receipt, use service certified_err. Provide exactly one of pages or pdf_base64. With pdf_base64, we count the PDF's pages. Sending both or neither is rejected with invalid_request (422); neither field takes precedence, even if the counts agree."},"LetterView":{"type":"object","properties":{"origin":{"type":"string","enum":["web","api","mcp","unknown"]},"id":{"type":"string"},"mode":{"type":"string","enum":["test","live"]},"state":{"type":"string","enum":["draft","paid","screening","review","submitted","printed","mailed","in_transit","delivered","receipt_ready","canceled","failed","returned","refunded"],"description":"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."},"service":{"type":"string","enum":["certified","certified_err"]},"pages":{"type":"integer"},"from":{"$ref":"#/components/schemas/PostalAddress"},"to":{"$ref":"#/components/schemas/PostalAddress"},"quote":{"$ref":"#/components/schemas/Quote"},"address_status":{"type":"string","enum":["pending","deliverable","corrected","undeliverable"]},"address_as_given":{"allOf":[{"$ref":"#/components/schemas/PostalAddress"},{"type":["object","null"]}]},"document_source":{"type":["string","null"],"enum":["text","pdf",null]},"review_note":{"type":["string","null"]},"cancel_until":{"type":["string","null"],"description":"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."},"send_now":{"type":"boolean","description":"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."},"refund":{"type":["object","null"],"properties":{"state":{"type":"string","enum":["accepted","manual","pending","not_charged"],"description":"accepted means the card processor accepted the refund or the prepaid balance was credited; it does not mean a card refund has posted at the bank. manual means we will refund it by hand; pending means acceptance is not yet recorded. not_charged means no money moved."},"amount_cents":{"type":"integer","minimum":0,"description":"Full refund amount in USD cents, including sales tax for a card payment; zero when nothing was charged."},"destination":{"type":["string","null"],"enum":["card","balance",null],"description":"The card paid with or the prepaid balance paid from; null when nothing was charged."}},"required":["state","amount_cents","destination"],"description":"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."},"address_note":{"type":["string","null"],"description":"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":{"type":"string","description":"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."},"preview_url":{"type":"string"},"receipt_url":{"type":"string","description":"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."},"letter_url":{"type":"string","description":"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."},"tracking_number":{"type":["string","null"]},"tracking_url":{"type":["string","null"]},"proof_of_mailing":{"type":["object","null"],"properties":{"at":{"type":"string","description":"USPS acceptance scan time, in UTC RFC 3339 format with milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ)."},"date":{"type":"string","description":"The scan’s local date (YYYY-MM-DD), as USPS Tracking shows it. Cite this as the mailing date."},"scan":{"type":"string","description":"USPS’s acceptance scan text."}},"required":["at","date","scan"],"description":"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."},"acceptance_expected_by":{"type":["string","null"],"description":"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."},"first_usps_scan":{"type":["object","null"],"properties":{"at":{"type":"string","description":"UTC RFC 3339 timestamp with milliseconds, YYYY-MM-DDTHH:mm:ss.sssZ."},"date":{"type":"string","description":"Local scan calendar date (YYYY-MM-DD)."},"scan":{"type":"string"}},"required":["at","date","scan"],"description":"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."},"partner_checked_at":{"type":["string","null"],"description":"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."},"files_deleted_at":{"type":["string","null"],"description":"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."},"timeline":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","description":"When the event happened, in UTC RFC 3339 format with milliseconds (YYYY-MM-DDTHH:mm:ss.sssZ). For USPS tracking scans, this is USPS’s scan time, not the time we recorded it."},"state":{"type":["string","null"],"enum":["draft","paid","screening","review","submitted","printed","mailed","in_transit","delivered","receipt_ready","canceled","failed","returned","refunded",null],"description":"When an acceptance scan exists, the USPS mailed tag belongs to that scan. A legacy mailed tag alone is not proof of mailing; read proof_of_mailing."},"source":{"type":"string","description":"Who reported it. partner includes the printing partner’s Printed and Provided to postal processing facility scans; other USPS scans remain usps."},"note":{"type":"string","description":"Event wording. Printing partner job statuses are observations at the check time; handed to USPS is not a USPS acceptance scan."},"observations":{"type":"integer","minimum":2,"description":"Count of adjacent identical printing-partner status checks collapsed into this row; omitted for a single observation. No USPS scans or state transitions are collapsed."},"last_at":{"type":"string","description":"UTC time of the last observation in a collapsed status-check row; omitted for one observation. at remains the first observation time, not a mailing time."}},"required":["at","state","source","note"]}},"next_step":{"type":"string"},"created_at":{"type":"string","description":"UTC RFC 3339 timestamp with milliseconds, YYYY-MM-DDTHH:mm:ss.sssZ."}},"required":["origin","id","mode","state","service","pages","from","to","quote","address_status","address_as_given","document_source","review_note","cancel_until","send_now","refund","address_note","preview_url","letter_url","tracking_number","tracking_url","proof_of_mailing","acceptance_expected_by","first_usps_scan","partner_checked_at","files_deleted_at","timeline","next_step","created_at"]},"PostalAddress":{"type":"object","properties":{"name":{"type":"string","maxLength":40,"default":"","description":"Person's full name. Omit or leave empty when sending to an organization only; either name or organization must contain nonblank text."},"organization":{"type":"string","minLength":1,"description":"Organization or company name. For an organization-only address, provide this and omit name. When both names are the same, we print the organization once."},"line1":{"type":"string","minLength":1,"maxLength":64},"line2":{"type":"string","minLength":1,"maxLength":64},"city":{"type":"string","minLength":1},"state":{"type":"string","pattern":"^[A-Z]{2}$"},"zip":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"}},"required":["line1","city","state","zip"],"additionalProperties":false,"description":"Unknown address fields are rejected with invalid_request (422). Use organization for a company name, not company."},"CreateLetter":{"type":"object","properties":{"to":{"allOf":[{"$ref":"#/components/schemas/PostalAddress"},{"description":"Recipient 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."}]},"from":{"$ref":"#/components/schemas/PostalAddress"},"service":{"type":"string","enum":["certified","certified_err"],"description":"certified 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."},"text":{"type":"string","maxLength":60000,"description":"The 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."},"send_now":{"type":"boolean","description":"Choose 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_base64":{"type":"string"},"pdf_url":{"type":"string"}},"required":["to","from","service"],"additionalProperties":false,"description":"Unknown fields in the body, to or from are rejected with invalid_request (422), naming each unknown field and its repair in error.fix. Use organization for a company name. For a return receipt, use service certified_err. Provide exactly one of text, pdf_base64 or pdf_url. Only US domestic letters are supported. An undeliverable recipient address is refused during creation with address_undeliverable (422); no draft is created. A different leading address block or date in text is refused with text_has_letterhead (422); send the body from the greeting on. Address checks usually finish in seconds. A slow check returns a saved pending draft, retried each minute for up to a day; read again after a minute. A busy queue or partner delay can slow the check. Payment waits for address confirmation. An auto-send key then pays from balance without per-letter approval, including after a USPS correction. People can also write or upload a letter at /send."}},"parameters":{}},"paths":{"/v1/quotes":{"post":{"operationId":"createQuote","security":[{"bearerAuth":[]},{}],"summary":"Get an itemized quote without creating or mailing a letter.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"The price in integer US cents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Malformed JSON or missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The letter is not visible to these credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the current letter or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Correct the fields named in error.fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An internal error prevented the request from completing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The printing partner or payment service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested service is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/letters":{"post":{"operationId":"createLetter","security":[{"bearerAuth":[]},{}],"summary":"Create a free draft for approval and payment. An auto-send key instead pays from its account balance; screening and the cancellation hold still apply.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Unique for a new letter; reuse with the identical request on retries. Anonymous keys need at least 16 characters."},"required":true,"description":"Unique for a new letter; reuse with the identical request on retries. Anonymous keys need at least 16 characters.","name":"Idempotency-Key","in":"header"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateLetter"}}}},"responses":{"200":{"description":"The existing letter for an identical idempotent request. Keep letter_url including its t token for reading and cancellation. An anonymous letter requires that token; an id alone or an API key created later cannot open it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterView"}}}},"201":{"description":"A new draft and its private approval link. Keep letter_url 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. For a letter created with an API key, that same key also authorizes reading and cancellation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterView"}}}},"400":{"description":"Malformed JSON or missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The letter is not visible to these credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the current letter or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Correct the fields named in error.fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An internal error prevented the request from completing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The printing partner or payment service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested service is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listLetters","security":[{"bearerAuth":[]}],"summary":"List letters created with this API key, newest first.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"A page of this key's letters; pass next_cursor to read the next page.","content":{"application/json":{"schema":{"type":"object","properties":{"letters":{"type":"array","items":{"$ref":"#/components/schemas/LetterView"}},"next_cursor":{"type":["string","null"]}},"required":["letters","next_cursor"]}}}},"400":{"description":"Malformed JSON or missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The letter is not visible to these credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the current letter or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Correct the fields named in error.fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An internal error prevented the request from completing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The printing partner or payment service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested service is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/letters/{id}":{"get":{"operationId":"getLetter","security":[{"bearerAuth":[]},{}],"summary":"Read a letter using its API key or the private t token from letter_url.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"The private t token from letter_url. Required to read or cancel an anonymous letter: keep letter_url, because an id alone or an API key created later cannot open it. For a letter created with an API key, use this token or that same creating key."},"required":false,"description":"The private t token from letter_url. Required to read or cancel an anonymous letter: keep letter_url, because an id alone or an API key created later cannot open it. For a letter created with an API key, use this token or that same creating key.","name":"t","in":"query"}],"responses":{"200":{"description":"The letter, timeline and next step.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterView"}}}},"400":{"description":"Malformed JSON or missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The letter is not visible to these credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the current letter or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Correct the fields named in error.fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An internal error prevented the request from completing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The printing partner or payment service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested service is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/letters/{id}/cancel":{"post":{"operationId":"cancelLetter","security":[{"bearerAuth":[]},{}],"summary":"Cancel before submission to the printer and refund any payment, using the API key or private t token.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"The private t token from letter_url. Required to read or cancel an anonymous letter: keep letter_url, because an id alone or an API key created later cannot open it. For a letter created with an API key, use this token or that same creating key."},"required":false,"description":"The private t token from letter_url. Required to read or cancel an anonymous letter: keep letter_url, because an id alone or an API key created later cannot open it. For a letter created with an API key, use this token or that same creating key.","name":"t","in":"query"}],"responses":{"200":{"description":"The canceled letter and refund status in its timeline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterView"}}}},"400":{"description":"Malformed JSON or missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The letter is not visible to these credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the current letter or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Correct the fields named in error.fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An internal error prevented the request from completing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The printing partner or payment service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested service is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/letters/{id}/send-now":{"post":{"operationId":"sendLetterNow","security":[{"bearerAuth":[]},{}],"summary":"Skip the paid letter's 30-minute cancellation hold; screening must still pass.","description":"Use the creating API key or private t token from letter_url. Idempotent while paid, screening or held for review; refused for a draft, submitted or canceled letter. This does not submit immediately or bypass checks. After skipping, cancellation is possible only until submission, with no guaranteed cancellation period.","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","description":"The private t token from letter_url. Required to read or cancel an anonymous letter: keep letter_url, because an id alone or an API key created later cannot open it. For a letter created with an API key, use this token or that same creating key."},"required":false,"description":"The private t token from letter_url. Required to read or cancel an anonymous letter: keep letter_url, because an id alone or an API key created later cannot open it. For a letter created with an API key, use this token or that same creating key.","name":"t","in":"query"}],"responses":{"200":{"description":"The letter with send_now true and its current cancellation deadline.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterView"}}}},"400":{"description":"Malformed JSON or missing idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"The letter is not visible to these credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The request conflicts with the current letter or idempotency key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Correct the fields named in error.fix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"An internal error prevented the request from completing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The printing partner or payment service could not complete the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The requested service is not configured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{}}