# Mail Merge Examples

> Mail merge demos and samples: merge blocks, conditions, images, barcodes, template design in the editor, Web APIs, background queues and parallel merging.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Examples > Mail Merge Examples
- **2442 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/examples/mail-merge/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/examples/mail-merge/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/examples/mail-merge/llms-full.txt

---

A merge has two halves, and the examples cover both: designing a template with merge fields and blocks, usually in the Document Editor, and merging it with data on the server with `MailMerge`. The online demos show each reporting structure with its template, data and code, from a single merge block to conditional sections. The sample projects put the merge into applications: Web APIs, background queues, Blazor and dynamic contracts.

### Online Demos: Merging on the Server

These demos merge data into a template with `MailMerge` on the server:

| Example | What it shows | Where |
|---|---|---|
| Concept | Business data that a user enters merged into a template on the server | [Mail Merge Concept](https://demos.textcontrol.com/demos/server-side-mail-merge/concept) |
| Merge blocks | Repeating regions of a template filled from nested JSON arrays | [Merge Blocks](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/merge-blocks) |
| Alternating rows | Table rows in two alternating colors | [Alternating Row Colors](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/alternating-rows) |
| Conditional sections | Regions of the template removed when their data is empty | [Conditional Sections](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/conditional-sections) |
| Conditional fields | Text chosen by IF fields from the values of the data | [Conditional Fields](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/conditional-fields) |
| Barcodes | Barcodes filled with values from the data | [Merging Barcodes](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/barcodes) |
| Images | Named image placeholders replaced by base64-encoded images from the data | [Merging Images](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/images) |
| Number formats | Numeric formats defined in the template applied to raw values | [String Formatter](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/string-formatter) |
| Prefixes | Values of related objects addressed with table name prefixes and dot notation | [Using Prefixes](https://demos.textcontrol.com/demos/server-side-mail-merge/reporting-structures/prefixes) |
| Merging in code | A template built from fields in code and merged with JSON data, in the interactive lab | [Mail Merge with JSON](https://demos.textcontrol.com/demos/interactive-coding/mail-merge-json) |

### Online Demos: Designing Templates

These demos design templates in the Document Editor:

| Example | What it shows | Where |
|---|---|---|
| Overview | A template designed and merged with data in the editor | [Mail Merge Overview](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-overview) |
| Template Assistant | Fields and merge blocks inserted from the data, with sorting, filters and conditions | [Mail Merge Template Assistant](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-template-designer) |
| Nested blocks | Tables with nested repeating merge blocks designed from JSON data | [Nested Merge Block Designer](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-nested-blocks) |
| Data source from JavaScript | JSON data passed to the editor in the browser with [loadJsonData](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/loadjsondata-method/llms-full.txt), so that users insert fields and repeating blocks from it on the **Reporting** tab | [Data Source from JavaScript](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-data-source-from-java-script) |
| Conditional blocks | Merge blocks merged only when a condition on the parent data is met | [Conditional Merge Blocks](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-conditions) |
| Sub-templates | Templates included in a main template with IncludeText fields | [Merging Sub-Templates](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-include-text) |
| Formulas | Table formulas that calculate merged values | [Mail Merge and Formulas](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-formulas) |
| Contracts | Contracts with dynamic sections generated from a template | [Dynamic Contract Generation](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-contract) |
| Merging from the editor | The template of the editor merged on the server and exported as PDF | [Merge using MailMerge](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-controller) |

The blog article [Learning Mail Merge Templates from Basic Fields to Advanced Reporting Structures](https://www.textcontrol.com/blog/2026/08/27/learning-mail-merge-templates-from-basic-fields-to-advanced-reporting-structures/) leads through these demos from simple fields to complex reports.

### Sample Projects

| Example | What it shows | Where |
|---|---|---|
| Dynamic NDAs | Sections of an NDA template included or left out depending on the JSON data, as described in [Generating Dynamic NDAs Using TX Text Control MailMerge in C# .NET](https://www.textcontrol.com/blog/2025/04/08/generating-dynamic-ndas-using-tx-text-control-mailmerge-in-csharp-dotnet/). Version 33.0 | [TXTextControl.Server.NDA.Dynamic](https://github.com/TextControl/TXTextControl.Server.NDA.Dynamic) |
| Templates and forms | A template designed in the Document Editor, merged with data and filled out as a form in the Document Viewer in one ASP.NET Core application, as described in [Best Practices for Mail Merge and Form Field Processing in ASP.NET Core C# Applications](https://www.textcontrol.com/blog/2024/07/30/best-practices-for-mail-merge-and-form-field-processing-in-asp-net-core-csharp-applications/). Version 33.0 | [TXTextControl.Server.Core.BestPractice](https://github.com/TextControl/TXTextControl.Server.Core.BestPractice) |
| Blazor | A template in the Blazor Document Editor merged with data and saved as PDF, as described in [TX Text Control for Blazor: Mail Merge Integration Tutorial](https://www.textcontrol.com/blog/2025/03/25/tx-text-control-for-blazor-mail-merge-integration-tutorial/). Version 33.0 | [TXTextControl.Web.Blazor.MailMerge](https://github.com/TextControl/TXTextControl.Web.Blazor.MailMerge) |
| Web API endpoint | An endpoint that receives a template, data and merge settings and returns a PDF, as described in [Designing a MailMerge Web API Endpoint with ASP.NET Core in C#](https://www.textcontrol.com/blog/2024/07/12/designing-a-mailmerge-web-api-endpoint-with-asp-net-core-in-c-sharp/). Version 33.0 with the Classic engine | [TXTextControl.MailMerge.WebAPI](https://github.com/TextControl/TXTextControl.MailMerge.WebAPI) |
| Templates in a database | Templates created in the editor, stored in LiteDB and merged from there, as described in [Store and Merge Templates in a Database using LiteDB and ASP.NET Core C#](https://www.textcontrol.com/blog/2023/11/23/store-and-merge-templates-in-a-database-using-litedb-and-aspnet-core-csharp/). Version 33.0 with the Classic engine | [TextControl.DocumentStorage](https://github.com/TextControl/TextControl.DocumentStorage) |
| Mustache placeholders | A class that turns `{{mustache}}` placeholders, including blocks, into merge fields and merge blocks before the merge, as described in [Mail Merge: Merging Templates with Mustache Syntax in C#](https://www.textcontrol.com/blog/2024/06/06/mail-merge-merging-templates-with-mustache-syntax-in-csharp/). The repository contains the class only | [MustacheMatcher](https://github.com/TextControl/MustacheMatcher) |
| Barcodes and QR codes | A packing slip merged from JSON data whose barcodes and QR codes take their values from the data, as described in [Enhancing Documents with QR Codes and Barcodes in .NET C#: A Comprehensive Guide](https://www.textcontrol.com/blog/2024/07/11/enhancing-documents-with-qr-codes-and-barcodes-in-net-csharp-a-comprehensive-guide/). Version 33.0 with the Classic engine | [TXTextControl.Server.Barcodes](https://github.com/TextControl/TXTextControl.Server.Barcodes) |
| Angular | Templates designed in the Angular Document Editor and merged with JSON data by an ASP.NET Core Web API, as described in [MailMerge with Angular and ASP.NET Core](https://www.textcontrol.com/blog/2024/03/15/mailmerge-with-angular-and-asp-net-core/). Version 32.0 | [TXTextControl.Server.Angular.MailMerge](https://github.com/TextControl/TXTextControl.Server.Angular.MailMerge) |
| Background queue | A Web API that queues document requests, creates the documents in a hosted service and notifies the client through a webhook, as described in [Queuing and Generating Documents using an IHostedService and WebHooks](https://www.textcontrol.com/blog/2023/09/01/queuing-and-generating-documents-using-an-ihostedservice-and-webhooks/). Version 31.0 on .NET 6 | [TextControl.Web.MVC.MailMerge.BackgroundWorker](https://github.com/TextControl/TextControl.Web.MVC.MailMerge.BackgroundWorker) |

The PDF generation Web API for Linux is listed in [Document Processing Examples](https://docs.textcontrol.com/tx-text-control-dotnet-server/examples/document-processing/#linux-docker-and-web-apis), and the samples that create electronic invoices with a merge in [PDF Examples](https://docs.textcontrol.com/tx-text-control-dotnet-server/examples/pdf/llms-full.txt).

### Blog Articles With Code

| Example | What it shows | Where |
|---|---|---|
| Parallel merging | Many merge jobs processed at the same time in worker processes with `TXTextControl.DocumentServer.ParallelMailMerge`, with a benchmark | [Create 100,000 Documents in Under an Hour with Parallel MailMerge in .NET C#](https://www.textcontrol.com/blog/2026/07/27/create-100000-documents-in-under-an-hour-with-parallel-mailmerge-in-dotnet-csharp/) |
| Merging on Linux | DOCX templates merged into PDF documents in a .NET console application on Linux | [Use MailMerge in .NET on Linux to Generate Pixel-Perfect PDFs from DOCX Templates](https://www.textcontrol.com/blog/2025/05/27/use-mailmerge-in-dotnet-on-linux-to-generate-pixel-perfect-pdfs-from-docx-templates/) |
| Sorting and filtering | The rows of merge blocks sorted and filtered | [Filtering and Sorting Repeating Blocks in MailMerge using C#](https://www.textcontrol.com/blog/2025/08/21/filtering-and-sorting-repeating-blocks-in-mailmerge-using-csharp/) |
| Business objects with totals | Objects that calculate their own sums merged into a template | [Merging Self-Calculating Business Objects with TX Text Control MailMerge in C#](https://www.textcontrol.com/blog/2024/12/27/merging-self-calculating-business-objects-with-tx-text-control-mailmerge-in-csharp/) |
| One document or many | Several records merged into one document with first-page headers and footers, or into separate documents | [Merging Multiple Records with First-Page Headers and Footers](https://www.textcontrol.com/blog/2025/04/14/merging-multiple-records-with-first-page-headers-and-footers/) |
| Merge blocks in code | Merge blocks inserted into a template with the `DataSourceManager` | [Mail Merge: Inserting Merge Blocks using the DataSourceManager in C#](https://www.textcontrol.com/blog/2024/10/02/mail-merge-inserting-merge-blocks-using-the-datasourcemanager-in-csharp/) |

### Next Steps

- [Mail Merge and Reporting](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/llms-full.txt): templates, data sources, merge blocks and conditions in detail.
- [Mail Merge](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/mail-merge/llms-full.txt) in Getting Started: a first merge step by step.
- [Multiple Processes](https://docs.textcontrol.com/tx-text-control-dotnet-server/performance/multiple-processes/llms-full.txt): merge large batches in parallel.

---

## Nearby

- **Previous:** [Document Processing Examples](https://docs.textcontrol.com/tx-text-control-dotnet-server/examples/document-processing/llms-full.txt)
- **Next:** [PDF Examples](https://docs.textcontrol.com/tx-text-control-dotnet-server/examples/pdf/llms-full.txt)