Create a Letter Draft
create_draftCreate a draft of a physical letter to be printed on paper and mailed through USPS, and return its draft_id, page count and total price. A letter is at most 6 printed pages, at the same price whatever its length: up to 3 pages print one-sided, 4 to 6 print on both sides. Write the body to fit, or split a longer document into two letters, because a body that renders to 7 or more pages is refused rather than trimmed. This is NOT email, fax or text message — nothing reaches the recipient electronically, and the only way this letter arrives is on paper in an envelope. The body is plain text or Markdown. The draft freezes the content and the price for 24 hours and costs nothing; no paper is printed and no postage is bought until send_letter is called. US domestic addresses only. Call preview_draft next so the user can see the letter and the total.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Who the letter is mailed to. | |
| tier | No | Defaults to standard. Call get_pricing first and pass a tier it lists: standard is a plain First-Class letter. certified, certified_err, proof_of_mailing and registered are other products the current price card may not sell, and a tier it does not sell is refused, not substituted — so do not describe one to the user until get_pricing has listed it. | |
| colour | No | Omit this. The current price card prints every letter black & white, so passing true is refused rather than billed — call get_pricing for what it does sell. The field remains because letters priced on an older card carry it. | |
| body_file | No | A file the user attached, as the host delivers it. Not accepted yet — create_draft refuses an attachment and asks for the letter as body_markdown text. | |
| body_markdown | Yes | The text of the letter, as plain text or Markdown. It must render to 6 printed pages or fewer — roughly 2,400 words of body text. | |
| from_address_id | No | Omit this. The account's own verified return address is used by default; only pass an id the account holder gave you. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | The next call to make. Read it before answering the user. | |
| tier | Yes | The product this draft is priced as, as passed to create_draft or update_draft. | |
| quote | Yes | A priced letter. State total.display to the user before sending, and pass total.amount_cents as confirm_total_cents. | |
| draft_id | Yes | Pass this to preview_draft, update_draft and send_letter. | |
| expires_at | Yes | ISO 8601 instant the draft is deleted. Nothing is charged if it expires. | |
| page_count | Yes | Printed pages, as counted by the renderer. Never more than 6 — a longer body is refused. | |
| tier_title | Yes | What the price card in force calls that product, such as Standard. Use this name when you tell the user what they are buying. | |
| sheet_count | Yes | Sheets of paper this letter is printed on: one page per sheet, one side each, up to 3 pages; a letter of 4 to 6 pages is printed on both sides, so it is never more than 3 sheets. | |
| included_pages | Yes | Printed pages the headline price covers. This draft is priced at that total up to this many pages. |