←Generate Document (Single)

Back to the main guide: all template types, node parameters, and output fields

Mail Merge

What this guide covers

This guide walks you through merging a classic Word mail-merge template in n8n using simple_mail_merge_template.docx and sample_mail_merge_data.json. The template uses Word MERGEFIELD placeholders (not <<[field]>> or mustache {{field}}). Data is a JSON array with one object per recipient. For Generate Document (Single), use one row in the array. Output can be PDF or Word.

Before You Start

Word mail-merge fields

The sample simple_mail_merge_template.docx was built with Word mail merge (Insert Merge Field). Field names are firstname, lastname, gender, and member. They must match JSON keys exactly.

JSON array data

Use sample_mail_merge_data.json (recommended), test.xml, or test.csv. Mail merge data is an array of objects. For one document, paste an array with a single object.

PDF4me credential in n8n

Create a PDF4me credential in n8n and paste your API key. The same key works across all PDF4me nodes in your instance.

→ Get your API key

Mail Merge vs PDF4me Word Template

Mail Merge is for Word documents created with classic mail-merge fields (MERGEFIELD). PDF4me Word Template uses <<[fieldName]>> LINQ syntax in a regular .docx. Pick the type that matches how your template was built. For many recipients in one API call, use Generate Documents (Multiple) instead.

Sample File Pack

Download all four files below. One Word mail-merge template plus three equivalent data formats.

simple_mail_merge_template.docx

Word mail-merge template (4 fields)

sample_mail_merge_data.json

JSON array with one recipient row (recommended)

test.xml

Same recipient data as XML

test.csv

Same recipient data as CSV (one row)

What's Inside the Sample Files

Merge fields in simple_mail_merge_template.docx

The sample is a simple membership letter with four classic Word merge fields:

Merge field name	Typical label in template	Sample value (sample_mail_merge_data.json)
firstname	Given name	John
lastname	Family name	Adams
gender	Gender	Female
member	Membership tier	Basic

How to inspect merge field names

In Microsoft Word, press Alt+F9 to toggle field codes. Mail-merge fields appear as { MERGEFIELD firstname } style codes. The name after MERGEFIELD must match your JSON key.

Field mapping across all data files

Merge field	JSON key (sample_mail_merge_data.json)	XML element (test.xml)	CSV column (test.csv)	Sample value
firstname	firstname	firstname	firstname	John
lastname	lastname	lastname	lastname	Adams
gender	gender	gender	gender	Female
member	member	member	member	Basic

Unlike PDF4me Word Template, there are no <<[field]>> tags. Unlike HTML, there is no mustache syntax. The engine binds JSON keys to Word MERGEFIELD names one to one.

The Workflow at a Glance

Manual Trigger  →  Read Binary File (simple_mail_merge_template.docx)  →  PDF4me Generate Document (Single)  →  (optional) Write Binary File

Step	n8n node	Purpose
1	Manual Trigger	Start the workflow on demand
2	Read Binary File	Loads simple_mail_merge_template.docx into binary property data
3	PDF4me → Generate Document (Single)	Merges template + JSON array, outputs PDF or Word
4	Write Binary File or Send Email (optional)	Saves or sends generated_document_output.pdf

Set Template File Type to Mail Merge. Choose PDF or Word for Output Type.

---

Step 1: Download and Place the Sample Files

1. Download simple_mail_merge_template.docx and sample_mail_merge_data.json from the Sample File Pack above.
2. Save the template somewhere n8n can read it (local path on self-hosted, or cloud storage for production triggers).
3. Optionally download test.xml or test.csv to test other data types.

---

Step 2: Create the n8n Workflow

1. In n8n, create a new workflow.
2. Add a Manual Trigger node.
3. Add a Read Binary File node after the trigger.
4. Add PDF4me → Generate Document (Single) after Read Binary File.
5. Connect your PDF4me credential.

HTML Code is not valid here

Template File Input Type: HTML Code only works when Template File Type is HTML. For Mail Merge, use Binary Data, Base64 String, or URL.

---

Step 3: Load the Word Template (Read Binary File)

Configure the Read Binary File node:

Field	Value
File Path	Full path to your downloaded simple_mail_merge_template.docx
Property Name	data (default; used as Template Binary Property in PDF4me)

Execute this node once and confirm the output item shows binary data with filename simple_mail_merge_template.docx.

---

Step 4: Configure PDF4me Generate Document (Single)

Core settings

Field	Value	Notes
Credential to connect with	Your PDF4me credential	Get API key
Resource	Generate
Generate Operations	Generate Document (Single)
Template File Type	Mail Merge	Classic Word MERGEFIELD template
Output Type	PDF or Word	PDF for sharing; Word if the recipient should edit the merged document

Template input (from Read Binary File)

Field	Value
Template File Input Type	Binary Data
Template Binary Property	data
Template File Name	simple_mail_merge_template.docx

Document data (paste JSON array from sample_mail_merge_data.json)

Field	Value
Document Data Input Type	Text
Document Data Type	JSON
Document Data Text	Paste the full contents of sample_mail_merge_data.json (see block below)

[
  {
    "firstname": "John",
    "lastname": "Adams",
    "gender": "Female",
    "member": "Basic"
  }
]

JSON must be an array

Mail merge data is a JSON array, even for a single recipient. One object in the array produces one merged document with Generate Document (Single).

Output options

Field	Value
Keep PDF Editable	Off (default) when Output Type is PDF
Binary Data Output Name	data (default)

---

Step 5: Execute and Verify the Output

1. Click Execute workflow.
2. Open the PDF4me node output. Under Binary, open property data (generated_document_output.pdf or .docx).
3. Confirm all four merge fields are populated:
   • firstname → John
   • lastname → Adams
   • gender → Female
   • member → Basic

If a field is blank, compare your JSON keys with the MERGEFIELD names in the Word template (Alt+F9 in Word).

---

Step 6: Save or Send the Output (Optional)

Write Binary File:

Field	Value
File Name	mail-merge-output.pdf
Data Property Name	data
Output Path	Target folder on your n8n host

Send Email: attach the binary data from PDF4me as the PDF or Word attachment.

---

Alternative Data Formats

Option A: JSON file as binary (sample_mail_merge_data.json)

1. Add Read Binary File for sample_mail_merge_data.json (use a Merge node if template and data share the workflow item).
2. Set Document Data Input Type to Binary Data, Document Data Type to JSON, Document Binary Property to your data field, Document Data File Name to sample_mail_merge_data.json.

Binary property name collision

If both template and data use property data, one overwrites the other. Use separate names (e.g. template and mergeData) or merge items from two Read Binary File nodes.

Option B: XML (test.xml)

Set Document Data Type to XML and paste:

<?xml version="1.0" encoding="UTF-8"?>
<Person>
    <firstname>John</firstname>
    <lastname>Adams</lastname>
    <gender>Female</gender>
    <member>Basic</member>
</Person>

Element names match the merge field names and JSON keys.

Option C: CSV (test.csv)

Set Document Data Type to CSV and paste (header row + one data row):

firstname,lastname,gender,member
"John","Adams","Female","Basic"

Column headers match the merge field names directly.

---

Alternative Template Input: URL

Host simple_mail_merge_template.docx at a public HTTPS URL, then set:

Field	Value
Template File Input Type	URL
Template File URL	Public link to simple_mail_merge_template.docx
Template File Name	simple_mail_merge_template.docx

No Read Binary File node is required. Data can still be pasted as Document Data Text or loaded from a URL.

---

Production Workflow Patterns

Common ways to run mail merge in productionOnce the sample test works, replace the Manual Trigger with these patterns.

Google Sheets row to letter

1. Sheets trigger on new row.
2. Code or Set node wraps the row in a JSON array: [{"firstname": "...", ...}].
3. PDF4me Mail Merge with fixed simple_mail_merge_template.docx.
4. Email the merged PDF to the recipient.

Webhook registration form

1. Webhook receives form payload.
2. Map body fields to merge keys (firstname, lastname, etc.).
3. Build a one-item JSON array for Document Data Text.
4. Store or email the output PDF.

Bulk merge (many recipients)

1. Export contacts as a JSON array (one object per person).
2. Switch to Generate Documents (Multiple) for one PDF per row.
3. Keep Generate Document (Single) when you only need one merged file per run.

Frequently Asked Questions

How is Mail Merge different from PDF4me Word Template?+

Mail Merge uses classic Word MERGEFIELD placeholders created in Word mail merge. PDF4me Word Template uses <<[fieldName]>> LINQ syntax in a regular .docx. Pick the type that matches how your template was authored. Data for Mail Merge is typically a JSON array.

Why must JSON be an array?+

Mail merge is designed for one or more recipient rows. Generate Document (Single) uses the first row when you pass one object in the array. Generate Documents (Multiple) processes every row and returns multiple output files.

Why is a merge field blank?+

JSON keys must match MERGEFIELD names exactly, including case. firstname works; FirstName or first_name usually does not. Toggle field codes in Word (Alt+F9) to read the internal name.

PDF or Word output?+

Choose PDF for emailing, archiving, or printing. Choose Word when the recipient needs to edit the merged document after generation. Both work with the same template and JSON array.

JSON vs XML vs CSV: which should I use?+

JSON arrays are the most natural fit for mail merge in n8n. XML and CSV in the sample pack carry the same four values for a single recipient. All formats map one value per merge field name.

Related Guides

• Generate Document (Single) overview: all parameters, output fields, and template types
• PDF4me Word Template: <<[fieldName]>> syntax instead of MERGEFIELD
• Generate Documents (Multiple): one output file per row in your JSON array
• Mail merge workflow blog: end-to-end pattern in Make

Back to overviewGenerate Documents (Multiple)