WolfSDKWolfXLWolfPPTWolfDocxWolfRender

WolfDocx - mail merge

Word mail merge in Python: fill MERGEFIELD templates and repeating table rows

Use WolfDocx mail merge when the template is an existing Word document built with MERGEFIELD fields, the way Word's own mail merge works. It writes one .docx per record, fills fields inside paragraphs, table cells, headers, and footers, repeats table rows and blocks for nested lists such as line items, and publishes the whole batch or nothing. Choose it over docxtpl when the template must stay a normal Word mail-merge document instead of being rewritten with Jinja2 tags, and over docx-mailmerge when you need repeating regions, nested tables, conditional fields, or a refusal instead of a quietly wrong letter.

Data: one record per output document

Each record has an id, which names its output file, and a values map. A list of objects fills a repeating region: in the template, put MERGEFIELD TableStart:Fees in the first cell of a table row and MERGEFIELD TableEnd:Fees in its last cell, and the row repeats once per fee. Regions can nest, for example orders that each hold a table of line items. CSV data with an id column and XML data are also accepted.

{
  "records": [
    {
      "id": "acme-2026-031",
      "values": {
        "ClientName": "Acme Corp",
        "EffectiveDate": "2026-11-01",
        "Fees": [
          {"Service": "Implementation", "Amount": "12,000"},
          {"Service": "Support", "Amount": "3,000"}
        ]
      }
    }
  ]
}

Merge the batch

import hashlib

from wolfdocx.mail_merge import merge_documents, parse_mail_merge_request


def sha256(path: str) -> str:
    return hashlib.sha256(open(path, "rb").read()).hexdigest()


report = merge_documents(parse_mail_merge_request({
    "source": "engagement_letter.docx",
    "source_sha256": sha256("engagement_letter.docx"),
    "output_dir": "letters",
    "data": {"path": "contracts.json", "sha256": sha256("contracts.json")},
}))
assert report.passed, report.code
print(report.counts)  # letters/acme-2026-031.docx, one file per record

Both the template and the data file are bound by their SHA-256, and both are checked again right before the batch is published. Every recipient is staged and re-read, then the output folder is created in one rename, so a run never leaves half a batch on disk.

wolfdocx author mail-merge-targets engagement_letter.docx   # list MERGEFIELD names and switches
wolfdocx author mail-merge request.json                      # the same request as JSON

Word field behavior it follows

  • Field switches for date pictures (\@), casing (\* Upper and the others), and text before or after a nonempty value (\b, \f).
  • NEXT, NEXTIF, SKIPIF, MERGEREC, MERGESEQ, and IF fields that test merge values.
  • ADDRESSBLOCK and GREETINGLINE through an explicit field mapping, plus QR and Code128 barcodes and images supplied by a callback.
  • Each field's run formatting stays as the template author set it.

Evidence and limits

  • The committed DOCX coverage census for mail merge and reporting lists 156 supported, 164 preserved, and 384 refused cases. See the cross-format coverage table.
  • A MERGEFIELD in a part WolfDocx does not merge, such as a comment, refuses the batch instead of shipping a stale value. Unsupported switches and malformed instructions are refused the same way.
  • A digitally signed template is refused, because any merge would invalidate the signature.
  • No throughput benchmark against docxtpl or docx-mailmerge has been published, so measure a representative batch before sizing a high-volume run.
  • For templates with literal placeholders instead of MERGEFIELDs, see fill a Word template table with rows.

Get WolfDocx

WolfDocx Commercial is an organization-scoped subscription. WolfDocx Community installs from public PyPI with pip install wolfdocx. WolfDocx Commercial installs from the authenticated WolfDocx package index with a per-purchase credential, issued on the checkout success page after payment and reissued through https://wolfxl.com/recover. There is no public free package.

Review the scoped before-and-after memo files in the reporting walkthrough, or ask about your document before purchasing if compatibility is uncertain.

See WolfDocx Commercial

Related tasks