[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]Property Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Map Control
  [Collapse]Rich Text Editor
   [Expand]Product Information
    Product Class Structure
    Supported Formats
   [Expand]Getting Started
   [Expand]RichEditControl Document
    Text Formatting
    Import and Export
   [Expand]Page Layout
    Spell Checking
    Mail Merge
    Restrictions and Protection
    Syntax Highlighting
   [Expand]Visual Elements
    Keyboard Shortcuts
    HTML Tag Support
    [Expand]Text Boxes
    [Expand]Document Elements
    [Expand]Search and Replace
    [Collapse]Mail Merge
      How to: Perform a Mail Merge
      How to: Send the Mail-Merge Document as an E-Mail
    [Expand]Spell Check
    [Expand]Import and Export
    [Expand]User Interface Customization
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]PDF Viewer
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

How to: Perform a Mail Merge

The following sections describe a mail merge implementation:

Expanded Connect to Data

To perform a mail merge, you need a template and a data source.

  • The template is a document containing fields (placeholders for the information that will be merged).

  • The data source contains the data that will be merged into the fields in the main document to create the merged documents. The data source can be any object that exposes the System.Collections.IList interface.

    In most cases you can use objects which expose the System.Collections.ArrayList interface or external databases available as System.Data.DataTable objects (via corresponding data adapters).

The following code creates a sample System.Collections.ArrayList data source.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1680.

The mail merge data source is specified via the RichEditMailMergeOptions.DataSource property.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1680.

A mail merge document is not complete until it is assigned appropriate data fields names. After providing the data source, proceed to creating fields.

Expanded Insert Fields

To create a template, a merge field (or fields) is inserted into a text document . The field names correspond to the fields of a provided data source.

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).

In the Main Toolbar, the Show All Field Codes button displays field codes for all fields in a document, the Show All Field Results displays field placeholders if the View Merged Data button is switched off. If this button is switched on (the corresponding RichEditMailMergeOptions.ViewMergedData property is true), the current record of the data source is displayed in place of the field.

The field is inserted at the cursor position. The merge field code looks like the following:


The optional \* MERGEFORMAT switch, which you can add manually, retains formatting applied to the field.

Document fields that are used in a mail merge only enable 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 other fields (such as DATE or the conditional field IF), use the FieldCollection.Create method of the document's collection of fields.

Expanded Finish a Merge

To finish a mail merge, call the Document.MailMerge method. The resulting document can be saved to a file or a memory stream, or sent for further processing to another RichEditControl or RichEditDocumentServer instance.

The MailMerge method can take a MailMergeOptions object as a parameter that contains additional settings that are not available in the RichEditControlOptionsBase.MailMerge method.

These options enable specifying the data source, choosing records to merge (the MailMergeOptions.FirstRecordIndex and MailMergeOptions.LastRecordIndex properties) and separating the merged ranges in the resulting document (the MailMergeOptions.MergeMode property).

If a merge field is located in a document's header or footer, the MergeMode property should be set to MergeMode.NewSection for proper operation.

To create mail merge options, use the Document.CreateMailMergeOptions method.

To copy all styles contained in the template to the merged document, enable the MailMergeOptions.CopyTemplateStyles property.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=E1680.

The following code uses records 1 to 3 to perform a mail merge. Each record is merged into a new section in a merged document. The target document is created in another RichEditControl (richEditControl2).


You can export each merged record to a new PDF file. Refer to the E4308 example for details.

Is this topic helpful?​​​​​​​