Mail A Letter

Prepares a letter started with create_upload_link, once the customer has uploaded its PDF: sets the recipient, service and options. Preparing a letter again with its current revision COMPLETELY REPLACES the recipient, service and options (omitted service/return_envelope reset to first_class/false); letters started in the app or on the website cannot be prepared here. The PDF prints exactly as uploaded and is mailed with the recipient's address on the envelope. Seals a proof of exactly what will print and returns an authoritative quote, the current balance (balance_cents, unchanged: preparing reserves nothing) and the balance projected after the customer sends (projected_balance_after_send_cents), warnings, and the review link on mailaletter.com. The recipient is either {"contact_id": <int>} or a postal address such as {"name": "Jane Example", "address1": "123 Main St", "city": "Springfield", "state": "IL", "postal_code": "62701", "country": "US"}. This does not send anything and does not charge anything: only the account holder can send, by opening the review link, signing in to their Mail A Letter account, checking the proof and pressing Send (valid 24 hours). Use a new random idempotency_key per intended preparation and reuse it unchanged on retry.

prepare_letter

One letter: status, revision, pages, cost, service, tracking when present, the latest committed order, and the review link on mailaletter.com while a sealed review of the current draft is waiting for the customer to send it (null otherwise). A draft has no order yet, so letter.total_cents is null; draft_quote is the price sealed for its review, with the time the review link expires (null when there is no live review). Missing and inaccessible letters both return not_found.

get_letter

Service tiers and their destination rules, the supported destination countries (ISO-2), the meaning of each letter status, and the v1 limits and defaults. No prices: prices come from prepare_letter.

get_mailing_capabilities

Whether the customer has uploaded the PDF for a letter from create_upload_link: pending (not yet), ready (uploaded and printable; call prepare_letter), rejected (the PDF cannot be printed; reject_reason says why and the customer can upload a corrected file on the same link), expired (the link ran out before an upload; start a new letter), or prepared (the letter was already prepared; get_letter has its review link). Missing and inaccessible letters both return not_found.

get_upload

The customer's current MailBank credit balance in integer USD cents. Preparing a letter never reserves or spends it.

get_balance

Re-issues the upload links of a letter started with create_upload_link that has not been prepared yet: the same letter_id and revision, the website upload_url and a fresh direct_upload_url. Use it when you no longer have the direct_upload_url (or need the links again) instead of starting another letter. The links expire when the letter's upload window does, 24 hours after create_upload_link; renewing never extends it, and after it ends you must start a new letter. Earlier links for the letter keep working until the same time. A PUT to direct_upload_url (or an upload on upload_url) replaces the letter's current PDF, whether pending, rejected or ready, up to a per-letter upload limit; once prepare_letter has run, the PDF can no longer change and this tool answers conflict. Treat direct_upload_url as a secret: never show it to anyone. Renewing sends and charges nothing.

renew_upload_link

The customer's letters newest-first by creation id, with status, recipient name, service and total (no addresses or text). Optional status filter and limit (1-50, default 20). Pass next_cursor back unchanged to continue; a cursor lives 24 hours. Rows reflect current values, not a snapshot.

list_letters

Starts a new letter and returns its letter_id, revision and an upload link on mailaletter.com. Give the customer the link: they sign in there and upload the PDF to mail (US Letter pages, unencrypted, up to 120 pages and 20 MB). Ask for a PDF that complies with PDF/A-1a (ISO 19005-1) if they can; a regular PDF is also accepted. If you can make HTTPS requests and have the customer's PDF yourself (for example a file attached to this conversation), you may instead PUT its raw bytes to direct_upload_url with Content-Type: application/pdf; the JSON answer says ready or why it was rejected. Send the PDF's file name too, so the customer sees it under its own name rather than letter.pdf: add the header Content-Disposition: attachment; filename="<name>.pdf" (or append ?filename=<URL-encoded name>.pdf to direct_upload_url), e.g. curl -X PUT -H "Content-Type: application/pdf" -H 'Content-Disposition: attachment; filename="my-letter.pdf"' --data-binary @my-letter.pdf "<direct_upload_url>". Treat direct_upload_url as a secret: never show it to anyone. When the PDF is uploaded, call prepare_letter with the letter_id and revision (get_upload shows whether it arrived). Both links are valid 24 hours; if you no longer have them, renew_upload_link re-issues them for the same letter. Uploading sends and charges nothing.

create_upload_link