Create letter draft
create_letterUse this when the user has an uploaded PDF (document_id, or upload_id from create_upload_link) and a recipient address and wants it posted by ordinary or registered mail; registered mail is international registered mail with tracking and signature on delivery; "certified" letters, Einschreiben, lettre recommandée and carta certificada mean this here (not a US certified-mail product). Creates a draft with the exact total in the user's currency. Nothing is sent or charged; call send_letter only after the user confirms. Every envelope carries our company return address, so the user's own address belongs in the document. The account's first letter needs the user's sender details, their REAL full name (no alias, nickname or pseudonym) and postal address: pass them as sender; without them (and none saved before) the call fails with SENDER_DETAILS_REQUIRED. Once the account has them, the saved details are used (sender_details "on_file"; "kept" when a different sender was passed, which is not saved): the user changes them in Settings → Your details. A US Letter PDF to a recipient outside the US, Canada and US territories needs the user's paper choice (paper_size, same price): without it the draft says paper_choice_required. Needs the user's account.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | "bw" = black and white, "color" = colour printing (costs more per page). Default "bw". | bw |
| duplex | No | true = print on both sides of the paper (fewer sheets, so a lighter letter); false = one side only. Default false. | |
| sender | No | The user's own sender details: their REAL full name (first and last name, not an alias, nickname or pseudonym) and postal address, any country. Optional: needed only while the account has no sender details yet; they are then checked and saved to the account. Once the account has them, the saved details are used and this is not saved (the user changes them in Settings → Your details). | |
| envelope | No | "DL" (220×110 mm, letter folded twice), "C5" (229×162 mm, folded once) or "C4" (324×229 mm, flat). Omit to use the smallest envelope that holds the sheets (recommended); one too small for the page count is refused. | |
| recipient | Yes | Recipient's postal address, printed on the envelope. Ask the user for missing fields. | |
| upload_id | No | upload_id from create_upload_link, once the user has uploaded the PDF on that page. Pass document_id or upload_id. | |
| paper_size | No | Only for a US Letter PDF to a recipient outside US, CA, PR, VI, GU, AS, MP (the US, Canada and US territories): "a4" = shrink to A4 (recommended), "us_letter" = keep US Letter. Ask the user; same price. Ignored otherwise (A4 PDFs print on A4, US Letter PDFs to those countries on US Letter). No default: omit until the user has chosen. | |
| registered | No | true = registered mail: tracking number and signature on delivery, for an extra fee (also what "certified" letters, Einschreiben, lettre recommandée and carta certificada mean here; not a US certified-mail product). false = ordinary mail. Default false. | |
| document_id | No | The PDF to post: document_id from upload_document or compose_letter, e.g. doc_2h7k9m4q8x1v3c6b0n5p. Pass document_id or upload_id. |