Log In
[Expand]General Information
[Collapse]WinForms Controls
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Map Control
  [Collapse]Rich Text Editor
   [Expand]Getting Started
     Text Formatting
     Import and Export
     Mail Merge
     Restrictions and Protection
     Line Numbering
     Table of Contents
     Check Spelling
     Syntax Highlighting
     Traversing the Document
   [Expand]Visual Elements
   [Expand]Member Tables
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Report Server
[Expand]eXpressApp Framework
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Mail Merge

This document provides an overview of an older approach to creating Mail Merge documents with the RichEditControl.


A newer and more convenient approach to Master-Detail Mail Merge is provided by the SnapControl and SnapDocumentServer. This approach is described in the following document: Snap Mail Merge.

The following sections describe an obsolete mail merge implementation that is still available to provide backward compatibility.

Expanded Performing a Mail Merge

Performing a mail merge in a rich text document requires the following two steps.

  • Specify the document data source by using the RichEditMailMergeOptions.DataSource property (it can be accessed via the RichEditControl.Options.MailMerge.DataSource notation).

  • Create a template by inserting MERGEFIELD fields. The field names refer to data column names of a specified data source.

    The MERGEFIELD field only enables the substitution of plain text. Formatted text that is inserted from a data source into a merge field will not be recognized and properly parsed. To insert formatted content, use the DOCVARIABLE field .

    To insert images, insert the MERGEFIELD field into an INCLUDEPICTURE field.

    To create master-detail mail merge reports, insert a DOCVARIABLE field with the variable name specified by the MERGEFIELD field.

To finish a mail merge and publish the document, call the Document.MailMerge method. To use mail merge options (e.g., to choose records to merge or separate the merged ranges in the resulting document), call the Document.CreateMailMergeOptions method and specify the created MailMergeOptions instance in the MailMerge method call.

To indicate the progress of a mail merge, use the IProgressIndicationService interface.

The resulting document can be saved to a file or a memory stream, or sent for further processing to another RichEditControl or RichEditDocumentServer instance.

Expanded Using Mail Merge Options

When a RichEditControl is assigned a mail merge data source, a data field is inserted into the document by clicking Insert Merge Field and selecting the field name in the invoked drop-down list (if a Ribbon UI is used) or a dialog window (if the Bar UI is used).

To hide unnecessary fields from this list, or replace obscure or lengthy display names, handle the RichEditControl.CustomizeMergeFields event.

The following events control the processes of performing mail merge and merging individual records.
- RichEditControl.MailMergeStarted and RichEditControl.MailMergeFinished;
- RichEditControl.MailMergeRecordStarted and RichEditControl.MailMergeRecordFinished.

The following commands may be useful when creating mail merge documents.




Inserts the MERGEFIELD field at the selection.


Invokes a dialog window to insert merge fields into a document from a connected data source.


Displays the codes of all fields in a document.


Displays field data in place of field codes.


Toggles the mode for displaying field codes.


Toggles the mode for displaying field data.


Navigates to the first data record in the connected data source.


Navigates to the last data record in the connected data source.


Navigates to the next data record in the connected data source.


Navigates to the previous data record in the connected data source.

Expanded See Also

How would you rate this topic?​​​​​​​