Preview mail merge
preview_mail_mergeRead-onlyIdempotent
Use this when the user wants to check a mail merge before printing: see how their spreadsheet (CSV or Excel) or list fills a letter, certificate or envelope template, which template fields like {{First Name}} have no matching column, which columns were matched by a similar name (first_name for First Name), and which records have empty values. Returns the first 3 merged records (or from preview_from) and a missing-field report; no files. Does not send email, print, or make labels. Do not use for Outlook or Gmail email merges.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date printed on letters and certificates and used for {{today}}, as YYYY-MM-DD, e.g. 2026-10-03. Defaults to today (US Eastern time); pass the user's local date when known. | |
| file | No | The spreadsheet with one row per recipient: Excel .xlsx, CSV or TSV, first row = column headers, e.g. donors.xlsx. | |
| names | No | Shortcut for a plain list of names (one column called Name), e.g. ["Ana Lopez", "Ben Okafor"]. Handy for certificates. | |
| sheet | No | For an .xlsx file: the sheet (tab) name to use, e.g. Donors. Defaults to the first sheet that has data. | |
| style | No | Certificates: design style: classic (navy double border), gold (cream with gold seal), modern (teal geometric), deco (burgundy art deco). Default classic. | |
| sender | No | Letters: your name/organization and address at the top. Envelopes: the return address. One line per entry, e.g. ["Riverbend Animal Shelter", "120 Elm St", "Springfield, IL 62701"]. | |
| closing | No | Letters: closing line, e.g. "With gratitude,". Defaults to "Sincerely," unless the template already ends with a closing. Use "" for none. | |
| records | No | Alternative to a file: the recipients typed as objects with the same keys, e.g. [{"First Name": "Ana", "Last Name": "Lopez", "Amount": 250}]. | |
| signers | No | Certificates: up to 3 signature lines, e.g. [{"name": "Alan Brooks", "title": "Principal"}]. | |
| subject | No | Letters: optional subject line printed as "Re: ...", may contain fields, e.g. "Your {{Year}} giving statement". | |
| csv_text | No | Alternative to a file: the list pasted as CSV or tab-separated text with a header row, e.g. "First Name,Last Name,City\nAna,Lopez,Austin". | |
| template | No | Letters: the letter text from the salutation to the last paragraph, with merge fields, e.g. "Dear {{First Name|Friend}},\n\nThank you for your gift of {{Amount:currency}} on {{Gift Date:date}}.{{#if Company}} Please thank everyone at {{Company}}.{{/if}}". Syntax: {{Field}}, {{Field|default}}, {{Field:format}} with formats currency, number, integer, ordinal, date, short_date, iso_date, upper, lower, title, first_word, last_word; {{#if Field}}...{{else}}...{{/if}}, {{#if Field = value}}, {{#if Gift > 0}} (also !=, <, >=, <=; numbers or dates), {{#unless Field}}...{{/unless}}; {{today}} is the document date. | |
| field_map | No | Optional explicit links from template fields to column names when names differ, e.g. {"Gift": "Donation Amount (USD)"}. | |
| has_header | No | Set false if the first row of the file is data, not column names (columns are then called Column A, Column B, ...). Default true. | |
| usps_style | No | Envelopes: print the delivery address in USPS style (uppercase, no periods or commas). Default false. | |
| organization | No | Certificates: issuing organization printed at the top, e.g. Lincoln Elementary School. | |
| preview_from | No | Record number to start the preview at, e.g. 1 (default) or 25 to check later rows. | |
| body_template | No | Certificates: the line under the name, may contain fields, e.g. "for completing {{Course}} ({{Hours}} hours) on {{Completed:date}}". | |
| document_type | Yes | What to merge into: letter (US business letter, one per row), certificate (landscape award/completion/participation certificate, one per row), or envelope (#10 envelope with recipient and return address). Example: letter. | |
| envelope_size | No | Envelopes: "10" for a #10 business envelope 4-1/8 x 9-1/2 in (default) or "a7" for a 5-1/4 x 7-1/4 in invitation envelope. | |
| missing_values | No | What to do when a record has an empty value for a field with no default: leave_blank (default), skip_record (leave that record out), or placeholder (print [Field Name] for proofreading). | |
| presented_line | No | Certificates: the line above the name. Default "This certificate is proudly presented to" ("This certifies that" for completion). | |
| signature_name | No | Letters: name printed under the closing, e.g. Maria Chen. | |
| include_address | No | Letters: print the recipient address block above the salutation. Default true when the sheet has address columns. | |
| signature_title | No | Letters: title under the signature name, e.g. Executive Director. | |
| address_template | No | Optional recipient address block (letters: inside address; envelopes: delivery address), one line per row, e.g. "{{First Name}} {{Last Name}}\n{{Street}}\n{{City}}, {{State}} {{ZIP}}". Defaults to one built from the name, company and address columns. | |
| certificate_kind | No | Certificates: sets the default title and wording, e.g. completion -> "Certificate of Completion". Default achievement. | |
| certificate_title | No | Certificates: custom title, e.g. "Certificate of Appreciation" or "Volunteer of the Year". | |
| recipient_template | No | Certificates: the name line, e.g. "{{First Name}} {{Last Name}}". Defaults to the Name column (or First + Last). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| batch | Yes | ||
| paper | Yes | ||
| style | Yes | ||
| counts | Yes | ||
| fields | Yes | ||
| source | Yes | ||
| missing | Yes | ||
| preview | Yes | ||
| summary | Yes | ||
| warnings | Yes | ||
| downloads | Yes | ||
| document_type | Yes | ||
| missing_total | Yes | ||
| unmatched_fields | Yes | ||
| needs_confirmation | Yes |