# MailMerge

> Merge DataTables, business objects or JSON with the MailMerge component in a Windows Forms app: TextComponent, the Reporting ribbon tab and its dialog boxes.

- **Product:** TX Text Control .NET for Windows Forms
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET for Windows Forms > Overview > Components > MailMerge
- **1193 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/mailmerge/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/mailmerge/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/mailmerge/llms-full.txt

---

Letters, invoices, labels and reports all start as a template with placeholders, and `MailMerge` fills the placeholders with your data. In a Windows Forms application, users design the template in the editor with the **Reporting** ribbon tab, and `MailMerge` merges it with a DataTable, business objects or JSON, either in the visible `TextControl` or in the background.

### What MailMerge Is

[MailMerge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/llms-full.txt) in the `TXTextControl.DocumentServer` namespace is a component, derived from `System.ComponentModel.Component`, that merges templates with data. It is in the **TX Text Control 34.0** toolbox tab, and the designer places it in the component tray below the form.

`MailMerge` holds no document itself. Its [TextComponent](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/textcomponent-property/llms-full.txt) property connects it to a `TextControl`, whose document is the template and receives the result where the user sees it, or to a [ServerTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/servertextcontrol/llms-full.txt), which merges in the background. [Where the Merge Runs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/overview/#where-the-merge-runs) compares the two.

Mail merge, merge fields and the reporting features are part of the Enterprise and Professional editions. See [Editions and Feature Availability](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/editions/llms-full.txt).

### Templates and Data

A template is a regular document with placeholders for the data. **Merge fields**, MS Word MERGEFIELD fields, are replaced with the value of the same name, and **merge blocks** repeat a part of the template, such as a table row, for each record of a list. [Mail Merge Overview](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/overview/llms-full.txt) explains the reporting model and what a merge processes, and [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/fields/llms-full.txt) and [Merge Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/blocks/llms-full.txt) go into detail.

The data comes from a `DataTable` or `DataSet` with [Merge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/merge-method/llms-full.txt), from business objects with [MergeObjects](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/mergeobjects-method/llms-full.txt) and [MergeObject](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/mergeobject-method/llms-full.txt), from JSON with [MergeJsonData](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/mergejsondata-method/llms-full.txt), or from a database named in a data source configuration file. [How Data Reaches a Template](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/data-sources/#how-data-reaches-a-template) lists each kind with its method.

### The Reporting User Interface

Windows Forms applications get a ready-made user interface for designing templates, with the **Reporting** tab at its center. The [RibbonReportingTab](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonreportingtab/llms-full.txt) selects a data source through its [DataSourceManager](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/llms-full.txt), inserts merge fields and merge blocks, and opens the dialog boxes of the namespace `TXTextControl.DocumentServer.Windows.Forms`, which your own menus can open as well. [Reporting Ribbon and Dialog Boxes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/ribbon-dialogs/llms-full.txt) describes the tab and its dialogs.

### Your First Merge

[Mail Merge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/llms-full.txt) in Getting Started creates a template, merges data into its fields and adds a merge block. Properties such as [RemoveEmptyFields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/removeemptyfields-property/llms-full.txt) decide what happens to placeholders without data, as [Remove What Stays Empty](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/conditional-content/#remove-what-stays-empty) describes, and events such as [FieldMerged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/fieldmerged-event/llms-full.txt) let your code take part in the merge, as [The Events of MailMerge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/events/#the-events-of-mailmerge) describes.

### Key Classes

| Class | Purpose |
|---|---|
| [MailMerge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver/mailmerge/llms-full.txt) | Merges data into the template of a connected `TextControl` or `ServerTextControl`. |
| [MergeField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-fields/mergefield/llms-full.txt) | An MS Word merge field in a template. |
| [DataSourceManager](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/llms-full.txt) | Loads data sources for the Reporting tab and its dialog boxes. |
| [RibbonReportingTab](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonreportingtab/llms-full.txt) | The ribbon tab for designing templates. |
| [LoadSettings](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/loadsettings/llms-full.txt) | Imports the fields and blocks of a DOCX template when it is loaded. |

### Next Steps

- [Mail Merge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/llms-full.txt) in Getting Started: create a template, merge data into its fields and add merge blocks.
- [Mail Merge and Reporting](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/llms-full.txt): data sources, merge fields, merge blocks, events and the reporting user interface in detail.
- [Reporting Ribbon and Dialog Boxes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/ribbon-dialogs/llms-full.txt): the Reporting tab and its dialogs.
- [ServerTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/servertextcontrol/llms-full.txt): merge documents in the background.

---

## Nearby

- **Previous:** [Sidebar](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/sidebar/llms-full.txt)
- **Next:** [ServerTextControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/components/servertextcontrol/llms-full.txt)