Mail Merge Examples
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 |
| Merge blocks | Repeating regions of a template filled from nested JSON arrays | Merge Blocks |
| Alternating rows | Table rows in two alternating colors | Alternating Row Colors |
| Conditional sections | Regions of the template removed when their data is empty | Conditional Sections |
| Conditional fields | Text chosen by IF fields from the values of the data | Conditional Fields |
| Barcodes | Barcodes filled with values from the data | Merging Barcodes |
| Images | Named image placeholders replaced by base64-encoded images from the data | Merging Images |
| Number formats | Numeric formats defined in the template applied to raw values | String Formatter |
| Prefixes | Values of related objects addressed with table name prefixes and dot notation | Using Prefixes |
| Merging in code | A template built from fields in code and merged with JSON data, in the interactive lab | Mail Merge with 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 |
| Template Assistant | Fields and merge blocks inserted from the data, with sorting, filters and conditions | Mail Merge Template Assistant |
| Nested blocks | Tables with nested repeating merge blocks designed from JSON data | Nested Merge Block Designer |
| Data source from JavaScript | JSON data passed to the editor in the browser with loadJsonData, so that users insert fields and repeating blocks from it on the Reporting tab | Data Source from JavaScript |
| Conditional blocks | Merge blocks merged only when a condition on the parent data is met | Conditional Merge Blocks |
| Sub-templates | Templates included in a main template with IncludeText fields | Merging Sub-Templates |
| Formulas | Table formulas that calculate merged values | Mail Merge and Formulas |
| Contracts | Contracts with dynamic sections generated from a template | Dynamic Contract Generation |
| Merging from the editor | The template of the editor merged on the server and exported as PDF | Merge using MailMerge |
The blog article 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. Version 33.0 | 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. Version 33.0 | 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. Version 33.0 | 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#. Version 33.0 with the Classic engine | 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#. Version 33.0 with the Classic engine | 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#. The repository contains the class only | 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. Version 33.0 with the Classic engine | 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. Version 32.0 | 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. Version 31.0 on .NET 6 | TextControl.Web.MVC.MailMerge.BackgroundWorker |
The PDF generation Web API for Linux is listed in Document Processing Examples, and the samples that create electronic invoices with a merge in PDF Examples.
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# |
| 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 |
| Sorting and filtering | The rows of merge blocks sorted and filtered | Filtering and Sorting Repeating Blocks in MailMerge using C# |
| 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# |
| 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 |
| Merge blocks in code | Merge blocks inserted into a template with the DataSourceManager | Mail Merge: Inserting Merge Blocks using the DataSourceManager in C# |
Next Steps
- Mail Merge and Reporting: templates, data sources, merge blocks and conditions in detail.
- Mail Merge in Getting Started: a first merge step by step.
- Multiple Processes: merge large batches in parallel.