# Mail Merge MS Word Office Open XML (DOCX) Templates in C# > TX Text Control's MailMerge engine allows you to perform MS Word compatible mail merge processes in .NET based applications. This article gives an overview of the basic functionality and shows how to merge JSON data into templates. - **Author:** Bjoern Meyer - **Published:** 2022-05-05 - **Modified:** 2025-11-16 - **Description:** TX Text Control's MailMerge engine allows you to perform MS Word compatible mail merge processes in .NET based applications. This article gives an overview of the basic functionality and shows how to merge JSON data into templates. - **4 min read** (735 words) - **Tags:** - ASP.NET - Json - MailMerge - Windows Forms - WPF - **Web URL:** https://www.textcontrol.com/blog/2022/05/05/mail-merge-ms-word-templates-in-csharp/ - **LLMs URL:** https://www.textcontrol.com/blog/2022/05/05/mail-merge-ms-word-templates-in-csharp/llms.txt - **LLMs-Full URL:** https://www.textcontrol.com/blog/2022/05/05/mail-merge-ms-word-templates-in-csharp/llms-full.txt --- Using TX Text Control, merging data into MS Word compatible templates can be effortlessly done in 3 simple steps. - Loading a template - Merging with data - Exporting the document ### Loading a Template The MailMerge class merges the data from various data sources into documents. It can be connected to any Text Control (TXTextControl.ServerTextControl, TXTextControl.TextControl and TXTextControl.WPF.TextControl. The document that is loaded into the connected *Text Control* is automatically used as the mail merge template. The following code shows how to create a *Mailmerge* instance and how to connect it to a *ServerTextControl*: ``` using (MailMerge mailMerge = new MailMerge()) { mailMerge.TextComponent = textControl1; } ``` In the next code snippet an Office Open XML (DOCX) template is loaded into a new *ServerTextControl* instance that is then connected to *MailMerge*: ``` TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() { ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord }; using (TXTextControl.ServerTextControl serverTextControl = new TXTextControl.ServerTextControl()) { serverTextControl.Create(); serverTextControl.Load("template.docx", TXTextControl.StreamType.WordprocessingML, ls); using (MailMerge mailMerge = new MailMerge()) { mailMerge.TextComponent = serverTextControl; } } ``` The template can be any MS Word document with merge fields that can be added using the pre-designed *Reporting* ribbon tab of the TX Text Control visual editor or using MS Word. The sample template is shown in the next screenshot: ![Creating documents with TX Text Control](https://s1-www.textcontrol.com/assets/dist/blog/2022/05/05/a/assets/merge1.webp "Creating documents with TX Text Control") ### Merging with Data *MailMerge* provides support for the following data sources: - DataTable - DataSet - IEnumerable objects - JSON - XML For all of these data source, different *Merge* methods and implementations are available. For simplicity, the following JSON string is used as the data source: ``` [ { "company_name": "Text Control, LLC", "address": { "street": "1111 Text Control Way", "zip": "28226", "city": "Charlotte", "country": "United States" } } ] ``` In the next code snippet, the MergeJsonData is used to merge the template with the given JSON data. ``` // enable MS Word merge fields TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() { ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord }; // load JSON data string jsonData = System.IO.File.ReadAllText("data.json"); // create a temporary ServerTextControl using (TXTextControl.ServerTextControl serverTextControl = new TXTextControl.ServerTextControl()) { serverTextControl.Create(); // load the template serverTextControl.Load("template.docx", TXTextControl.StreamType.WordprocessingML, ls); // create the mail merge engine using (MailMerge mailMerge = new MailMerge()) { // connect to ServerTextControl mailMerge.TextComponent = serverTextControl; // merge data into template mailMerge.MergeJsonData(jsonData); } } ``` The resulting document is shown in the screenshot: ![Creating documents with TX Text Control](https://s1-www.textcontrol.com/assets/dist/blog/2022/05/05/a/assets/merge2.webp "Creating documents with TX Text Control") ### Exporting the Document After a successful merge process, the resulting document is loaded into the connected *Text Control* instance and can be exported to any supported document format. The following code shows how the resulting document is getting exported as an Adobe PDF document. ``` TXTextControl.LoadSettings ls = new TXTextControl.LoadSettings() { ApplicationFieldFormat = TXTextControl.ApplicationFieldFormat.MSWord }; string jsonData = System.IO.File.ReadAllText("data.json"); using (TXTextControl.ServerTextControl serverTextControl = new TXTextControl.ServerTextControl()) { serverTextControl.Create(); serverTextControl.Load("template.docx", TXTextControl.StreamType.WordprocessingML, ls); using (MailMerge mailMerge = new MailMerge()) { mailMerge.TextComponent = serverTextControl; mailMerge.MergeJsonData(jsonData); } // export document as PDF serverTextControl.Save("results.pdf", TXTextControl.StreamType.AdobePDF); } ``` ### Mail Merge Events *MailMerge* provides many events to control the merge process and to interact with fields by injecting custom data or logic. The following events can be used during the mail merge process: | Event | Description | |---|---| | BarcodeMerged | Occurs when a barcode has been merged successfully. | | BlockMerging | Occurs when a merge block is about to be merged. | | BlockRowMerged | Occurs when a merge block row has been merged successfully. | | ChartMerged | Occurs when a chart has been merged successfully. | | DataRowMerged | Occurs when a data row has been merged successfully. | | FieldMerged | Occurs when a field has been merged. | | FormFieldMerged | Occurs when a form field has been merged. | | ImageFieldMerged | Occurs when an image field, i.e., a merge field whose name is prefixed with "image:" has been merged. | | ImageMerged | Occurs when an image has been merged successfully. | | IncludeTextMerging | Occurs when an IncludeText field has been merged. | The number and the names of the events show that *MailMerge* provides way more than a simple mail merge process. *MailMerge* is a powerful rendering engine that supports repeating merge blocks, 1:n relationships, image merging, barcode support and populating form fields. Generally speaking, all document automation processes can be realized using the *MailMerge* class. > **Reading Tip: Event Handling** > > MailMerge: Field Mapping and Handling of Unmerged Fields > > [Read More ](https://www.textcontrol.com/blog/2022/05/04/mailmerge-field-mapping-and-handling-of-unmerged-fields/llms-full.txt) --- ## About Bjoern Meyer As CEO, Bjoern is the visionary behind our strategic direction and business development, bridging the gap between our customers and engineering teams. His deep passion for coding and web technologies drives the creation of innovative products. If you're at a tech conference, be sure to stop by our booth - you'll most likely meet Bjoern in person. With an advanced graduate degree (Dipl. Inf.) in Computer Science, specializing in AI, from the University of Bremen, Bjoern brings significant expertise to his role. In his spare time, Bjoern enjoys running, paragliding, mountain biking, and playing the piano. - [LinkedIn](https://www.linkedin.com/in/bjoernmeyer/) - [X](https://x.com/txbjoern) - [GitHub](https://github.com/bjoerntx) --- ## Related Posts - [MailMerge: Field Mapping and Handling of Unmerged Fields](https://www.textcontrol.com/blog/2022/05/04/mailmerge-field-mapping-and-handling-of-unmerged-fields/llms.txt) - [Generating Hierarchical Tables from JSON Data in .NET C#](https://www.textcontrol.com/blog/2023/08/03/generating-hierarchical-tables-from-json-data-in-csharp/llms.txt) - [MailMerge: Merging Hyperlinks using the FieldMerged Event](https://www.textcontrol.com/blog/2022/06/08/mailmerge-merging-hyperlinks-using-the-fieldmerged-event/llms.txt) - [MailMerge: Data Structures Explained with a Sample Template and JSON Data](https://www.textcontrol.com/blog/2022/03/14/mailmerge-data-structures-explained-with-a-sample-template-and-json-data/llms.txt) - [Adding Sorting and Filter Instructions to Existing MergeBlocks](https://www.textcontrol.com/blog/2021/07/16/adding-sorting-and-filter-instructions-to-existing-mergeblocks/llms.txt) - [X19 Sneak Peek: Manipulating MergeBlockInfo Objects](https://www.textcontrol.com/blog/2020/11/17/x19-sneak-peek-manipulating-mergeblockinfo-objects/llms.txt) - [Format Numeric String Values with MailMerge](https://www.textcontrol.com/blog/2020/10/22/format-numeric-string-values-with-mailmerge/llms.txt) - [TXTextControl.Markdown.Core 34.1.0-beta: Work with Full Documents, Selection, and SubTextParts](https://www.textcontrol.com/blog/2026/04/14/txtextcontrol-markdown-core-34-1-0-beta-work-with-full-documents-selection-and-subtextparts/llms.txt) - [TX Spell .NET 11.0 SP1 is Now Available: What's New in the Latest Version](https://www.textcontrol.com/blog/2026/04/08/tx-spell-net-11-0-sp1-is-now-available/llms.txt) - [TX Text Control 34.0 SP2 is Now Available: What's New in the Latest Version](https://www.textcontrol.com/blog/2026/02/18/tx-text-control-34-0-sp2-is-now-available/llms.txt) - [TX Text Control 34.0 SP1 is Now Available: What's New in the Latest Version](https://www.textcontrol.com/blog/2025/12/03/tx-text-control-34-0-sp1-is-now-available/llms.txt) - [Introducing TX Text Control 34.0: Your Next Leap in Document Processing](https://www.textcontrol.com/blog/2025/11/10/introducing-tx-text-control-34-0-your-next-leap-in-document-processing/llms.txt) - [Sneak Peek: TX Text Control 34.0 Coming November 2025](https://www.textcontrol.com/blog/2025/10/02/sneak-peek-tx-text-control-34-0-coming-november-2025/llms.txt) - [TX Text Control 33.0 SP3 is Now Available: What's New in the Latest Version](https://www.textcontrol.com/blog/2025/08/14/tx-text-control-33-0-sp3-is-now-available/llms.txt) - [TX Text Control 33.0 SP2 is Now Available: What's New in the Latest Version](https://www.textcontrol.com/blog/2025/06/18/tx-text-control-33-0-sp2-is-now-available/llms.txt) - [Document Lifecycle Optimization: Leveraging TX Text Control's Internal Format](https://www.textcontrol.com/blog/2025/05/16/document-lifecycle-optimization-leveraging-tx-text-controls-internal-format/llms.txt) - [Expert Implementation Services for Legacy System Modernization](https://www.textcontrol.com/blog/2025/05/07/expert-implementation-services-for-legacy-system-modernization/llms.txt) - [Service Pack Releases: What's New in TX Text Control 33.0 SP1 and 32.0 SP5](https://www.textcontrol.com/blog/2025/05/07/service-pack-releases-whats-new-in-tx-text-control-33-0-sp1-and-32-0-sp5/llms.txt) - [Top 5 Real-World Applications for TX Text Control Document Processing Libraries](https://www.textcontrol.com/blog/2025/04/01/top-5-real-world-applications-for-tx-text-control-document-processing-libraries/llms.txt) - [DWX Developer Week Moves to Mannheim - And Text Control Is on Board!](https://www.textcontrol.com/blog/2025/03/19/dwx-developer-week-moves-to-mannheim-and-tx-text-control-is-on-board/llms.txt) - [The Wait is Over: TX Text Control for Linux is Officially Here](https://www.textcontrol.com/blog/2025/03/12/the-wait-is-over-tx-text-control-for-linux-is-officially-here/llms.txt) - [Full .NET 9 Support in Text Control .NET Components for ASP.NET Core, Windows Forms, and WPF](https://www.textcontrol.com/blog/2024/11/11/full-net-9-support-in-text-control-net-components-for-asp-net-core-windows-forms-and-wpf/llms.txt) - [Toggle Field Codes in TX Text Control](https://www.textcontrol.com/blog/2024/11/07/toggle-field-codes-in-tx-text-control/llms.txt) - [TX Text Control 32.0 Service Pack 4 Released](https://www.textcontrol.com/blog/2024/09/02/tx-text-control-32-0-service-pack-4-released/llms.txt) - [Service Pack 3: MailMerge Supports SVG Images](https://www.textcontrol.com/blog/2024/04/29/service-pack-3-mailmerge-supports-svg-images/llms.txt)