create_batch_mail
Creates a batch mail draft from a template link and recipient list, skips malformed or duplicate rows, and returns exact pricing plus a proof before credits are charged.
Instructions
Create a batch draft from a template link and a recipient list; nothing is charged. template_url is a public https:// link to a PDF at the mail type's size, or to a PNG/JPG postcard graphic that is set on a page at that size (design 4×6 in at 300 dpi = 1200×1800 px). Recipients go inline (an array of {name, line1, line2, city, state, zip}; company accepted) or as recipients_url, a CSV link. Malformed rows and duplicates are skipped and listed, never charged. A one-page postcard gets an address side printed with the return address. The result carries the exact price, the first recipients and any image warnings; then call get_batch_mail_proof and give the person its proof_url, which opens in any browser for an hour, to see the template and a sample address label before confirm_batch_mail charges credits. Requires mailbox_md_version from get_mailbox_md. A key that requires approval saves the draft for the account owner to pay in the dashboard. Postcards from 1 recipient (a $2.00 small-batch fee under 10); letters, flyers and pamphlets from 10; up to 10,000.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| color | No | Color printing for letters, flyers and pamphlets, charged per color page (postcards are always full color). Default false. | |
| duplex | No | Print both sides of each sheet. Default false. | |
| job_name | Yes | A name the owner will recognise in the dashboard and in emails, e.g. "Spring open house postcards". | |
| mail_type | Yes | postcard_4x6, postcard_6x9, letter (1–3 pages, 6 with duplex), flyer (1 page), pamphlet_light (4–8 pages), pamphlet_heavy (9–16 pages). | |
| column_map | No | For recipients_url only, when the CSV headers are not recognised: field (name, line1, line2, city, state, zip) → the header text in the file. | |
| recipients | No | Inline recipients, up to 10,000 (postcards from 1, other types from 10). Skipped rows are reported by position (1 = first). Send this or recipients_url, not both. | |
| return_zip | No | Return ZIP code. | |
| return_city | No | Return city. | |
| return_name | No | Return name. Defaults to the account's saved return address. | |
| return_line1 | No | Return street address. Defaults to the account's saved return address. | |
| return_line2 | No | Return suite or unit. | |
| return_state | No | Return state, 2 letters. | |
| template_url | Yes | Public https:// link to the template (PDF, PNG or JPG, ≤10 MB). Signed cloud-storage links, CDN and GitHub raw URLs work; links that need a login, private hosts and IP addresses are refused. | |
| mailing_class | No | first_class (USPS First-Class Mail, 1–5 days, forwarded and returned; the default) or marketing_mail (USPS Marketing Mail, 3–10 days, 200+ recipients; not open until the facility's USPS permit is active). The class is USPS postage, not a description of the content: bills, statements and personal correspondence must go first_class. | |
| recipients_url | No | Public https:// link to a recipients CSV (columns name, address, address2, city, state, zip; ≤5 MB). Send this or recipients, not both. | |
| return_company | No | Return company line. | |
| mailbox_md_version | Yes | Your current MAILBOX.md version from get_mailbox_md. Required for agent keys. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes | The draft: batch (status draft, pricing, recipients summary, links.proof), recipients_preview, template (how it was taken), warnings and next_step. |