Mail Merge

Wordize Mail Merge for .NET allows you to automate personalized document creation. Automate mass mallings, invoice creation, letter generation.

Wordize allows users to automate the creation of personalized documents such as letters, invoices, or emails. It works by combining a template with data from sources like spreadsheets or databases, which is called Mail Merge. This saves time, reduces errors, and allows for efficient batch document generation.

How Mail Merge Works

Mail Merge is a process that combines a document template with data to create personalized documents in bulk. It works by inserting specific fields (e.g., names, addresses) into a template, which are then filled with data from a data source, generating multiple customized outputs.

Mail merge Process

Wordize allows users to use DataRow, DataTable, DataSet and array of values ​​as a data source.

Simple Mail Merge Operation

Simple Mail Merge creates personalized documents by merging a template with data. In the template, placeholders (called merge fields) represent dynamic content like names, addresses, or dates. During the merge process, these placeholders are replaced with the corresponding data from an external data source.

You can add one or more merge fields to your template and then run a simple mail merge operation. It is important to understand that the output documents will differ only in the specific values ​​in the merge fields.

Simple Mail merge

Example workflow:

  1. Prepare a template document with merge fields (e.g. <<Name>>, <<Address>>)
  2. Prepare data in the data source (DataRow, DataTable, DataSet, array of values)
  3. Execute the merge operation to produce individual documents with personalized information

To perform a simple merge operation, use one of the Execute methods:

  • Execute(string, string, string[], object[])
  • Execute(string, string, SaveFormat, string[], object[])
  • Execute(string, string, SaveFormat, MailMergeOptions, string[], object[])
  • Execute(Stream, Stream, SaveFormat, string[], object[])
  • Execute(Stream, Stream, SaveFormat, MailMergeOptions, string[], object[])
  • xecute(string, string, DataRow)
  • Execute(string, string, SaveFormat, DataRow)
  • Execute(string, string, SaveFormat, MailMergeOptions, DataRow)
  • Execute(Stream, Stream, SaveFormat, DataRow)
  • Execute(Stream, Stream, SaveFormat, MailMergeOptions, DataRow)
  • Execute(string, string, DataTable)
  • Execute(string, string, SaveFormat, DataTable)
  • Execute(string, string, SaveFormat, MailMergeOptions, DataTable)
  • Execute(Stream, Stream, SaveFormat, DataTable)
  • Execute(Stream, Stream, SaveFormat, MailMergeOptions, DataTable)

The following code example shows how to perform a mail merge operation using the Execute(string, string, string[], object[]) method:

string doc = MyDir + "MergeTemplate.doc";

string[] fieldNames = new string[] { "FirstName", "Location", "SpecialCharsInName()" };
string[] fieldValues = new string[] { "James Bond", "London", "Classified" };

MailMerger.Execute(doc, ArtifactsDir + "MailMerge.1.docx", fieldNames, fieldValues);

Mail Merge with Regions

Mail merge with regions is used when you need to insert dynamic content (such as tables with different numbers of rows or itemized lists of different lengths) for a specific area of ​​the document. In this case, merge regions are used instead of simple merge fields – they define sections that are repeated for each data record. This is useful for documents like invoices with multiple line items or reports with dynamic tables.

Mail merge with regions

Example workflow:

  1. Define the merge region in the template using start and end markers (e.g., <<TableStart:Items>> and <<TableEnd:Items>>)
  2. Connect the template to a structured data source with nested records
  3. Perform the merge operation

This advanced method provides greater flexibility to handle complex scenarios with multiple data records.

To perform mail merge with regions operation, use one of the ExecuteWithRegions methods:

  • ExecuteWithRegions(string, string, DataTable)
  • ExecuteWithRegions(string, string, SaveFormat, DataTable)
  • ExecuteWithRegions(string, string, SaveFormat, MailMergeOptions, DataTable)
  • ExecuteWithRegions(Stream, Stream, SaveFormat, DataTable)
  • ExecuteWithRegions(Stream, Stream, SaveFormat, MailMergeOptions, DataTable)
  • ExecuteWithRegions(string, string, DataSet)
  • ExecuteWithRegions(string, string, SaveFormat, DataSet)
  • ExecuteWithRegions(string, string, SaveFormat, MailMergeOptions, DataSet)
  • ExecuteWithRegions(Stream, Stream, SaveFormat, DataSet)
  • ExecuteWithRegions(Stream, Stream, SaveFormat, MailMergeOptions, DataSet)

The following code example shows how to perform a mail merge operation using the ExecuteWithRegions(string, string, DataTable) method:

string doc = MyDir + "MergeRegionsTemplate.docx";

DataTable dataTable = new DataTable("MyTable");
dataTable.Columns.Add("FirstName");
dataTable.Columns.Add("LastName");
dataTable.Rows.Add(new object[] { "John", "Doe" });
dataTable.Rows.Add(new object[] { "", "" });
dataTable.Rows.Add(new object[] { "Jane", "Doe" });

MailMerger.ExecuteWithRegions(doc, ArtifactsDir + "MailMergeWithRegionsDataTable.1.docx", dataTable);

Mail Merge Options

Mail Merge options allow you to customize the behavior of the mail merge process, controlling how data is processed, formatted, and displayed in the final document. These options provide flexibility for advanced scenarios and fine-tuning output.

Wordize supports the following MailMergeOptions:

  • CleanupOptions – specifies what items should be removed during mail merge
  • CleanupParagraphsWithPunctuationMarks – indicate whether paragraphs with punctuation marks are considered as empty and should be removed if the RemoveEmptyParagraphs option is specified
  • MergeDuplicateRegions – indicates whether all of the document mail merge regions with the name of a data source should be merged while executing mail merge with regions against the data source or just the first one
  • MergeWholeDocument – indicates whether fields in a whole document are updated while executing mail merge with regions
  • PreserveUnusedTags – indicates whether the unused tags should be preserved
  • RegionEndTag – specifies a mail merge region end tag
  • RegionStartTag – specifies a mail merge region start tag
  • RestartListsAtEachSection – indicates whether lists are restarted at each section after executing mail merge
  • RetainFirstSectionStart – indicates whether the section start of the first document section and its copies for subsequent data source rows are retained during mail merge or updated according to MS Word behavior
  • TrimWhitespaces – indicates whether trailing and leading whitespaces are trimmed from mail merge values
  • UnconditionalMergeFieldsAndRegions – indicates whether merge fields and merge regions are merged regardless of the parent IF field’s condition
  • UseNonMergeFields – when true, specifies that in addition to MERGEFIELD fields, mail merge is performed into some other types of fields and also into “{{fieldName}}” tags
  • UseWholeParagraphAsRegion – indicates whether a whole paragraph with TableStart or TableEnd field or a particular range between TableStart and TableEnd fields should be included into mail merge region

The following code example shows how to perform a mail merge operation using the TrimWhitespaces option and the Execute(string, string, SaveFormat, MailMergeOptions, string[], object[]) method:

string doc = MyDir + "MergeTemplate.doc";

string[] fieldNames = new string[] { "FirstName", "Location", "SpecialCharsInName()" };
string[] fieldValues = new string[] { "James Bond", "London", "Classified" };

MailMergeOptions mailMergeOptions = new MailMergeOptions();
mailMergeOptions.TrimWhitespaces = true;
MailMerger.Execute(doc, ArtifactsDir + "MailMerge.3.docx", SaveFormat.Docx, mailMergeOptions, fieldNames, fieldValues);

Mail Merge Clenup Option

Mail Merge cleanup options are used to control how the document is cleaned after the merge process. They help remove unused fields, empty paragraphs, and other leftover placeholders, ensuring clean output. These options are especially useful when some merge fields may not have corresponding data.

Wordize supports the following MailMergeCleanupOptions:

  • None – to specify a default value
  • RemoveEmptyParagraphs – to specify whether paragraphs containing mail merge fields with no data should be removed from the document
  • RemoveUnusedRegions – to specify whether unused mail merge regions should be removed from the document
  • RemoveUnusedFields – to specify whether unused merge fields should be removed from the document
  • RemoveContainingFields – to specify whether fields that contain merge fields should be removed from the document if the nested merge fields are removed
  • RemoveStaticFields – to specify whether static fields should be removed from the document
  • RemoveEmptyTableRows – to specify whether empty rows containing mail merge regions should be removed from the document
  • RemoveEmptyTables – to specify whether to remove from the document tables containing mail merge regions that were removed using either the RemoveUnusedRegions or the RemoveEmptyTableRows option

The following code example shows how to use MailMergeCleanupOptions:

string doc = MyDir + "MergeTemplate.doc";

string[] fieldNames = new string[] { "FirstName", "Location", "SpecialCharsInName()" };
string[] fieldValues = new string[] { "James Bond", "London", "Classified" };

MailMergeOptions mailMergeOptions = new MailMergeOptions();
mailMergeOptions.MailMergeCleanupOptions = MailMergeCleanupOptions.RemoveEmptyParagraphs;
MailMerger.Execute(doc, ArtifactsDir + "MailMerge.3.docx", SaveFormat.Docx, mailMergeOptions, fieldNames, fieldValues);