How to Create a Mail Merge using Bookmarks

April 08 2019

In a Word document, a bookmark can refer to a location in the document or an actual block of text within the document. The GcWord API provides methods to access all the bookmarks in a Word document and allows you to alter its text. This article describes how you can implement a mail merge quickly and easily using bookmarks and a Word API.

Consider a mail merge scenario, where a company wants to notify its customers about the dispatch of merchandise/products from their warehouse. In such a scenario, the content of the mail drafted for each customer would remain same, the only part that needs to be altered is each customer’s name and address.

For this example, we’ll create a template document using MS Word. The parts of text that need to be replaced during the mail merge are represented using some placeholder text. For example, the sender, receiver, and receiver’s address are inserted using placeholder text. These placeholder texts will be marked as bookmarks so we can replace their text to generate new documents and implement a mail merge.

Step 1: Designing the mail merge template

We'll design a template document using MS Word, which contains the mail draft. We'll insert placeholder text for the "From, To, and Address" parts of the document text.

These placeholder text in the document will be marked as bookmarks.

Here is a glimpse of how the template will look:

How to Create a MailMerge using Bookmarks on .NET Core 3

In the above image, the name of each customer and the address will need to be replaced. This text is inserted as a bookmark.

Step 2: Generating the mail merge document

Using the GcWord API, you can load this document in code to access all the bookmarks. Replace the text of each bookmark with an appropriate value to generate the new document. The bookmarks collection in the document can be accessed using the Bookmarks property.

The code below shows how you can replace the text of each bookmark in the document:

public GcWordDocument CreateDocx()
        {
            //Load the template document
            GcWordDocument doc = new GcWordDocument();
            doc.Load(Path.Combine("Resources", "WordDocs", "MailMergeBmk-tpl.docx")); 

           //Get all the bookmarks from the document 
           var bmks = doc.Body.Bookmarks;

            // Replace bookmarks with actual data. 
            setBmkText("title", "Mr.");
            setBmkText("surname", "Smith");
            setBmkText("address", "123 Bits Dr.");
            setBmkText("city", "Byteville");
            setBmkText("state", "VT");
            setBmkText("zip", "12345");
            setBmkText("country", "U.S.A.");

            // Done:
            return doc;

            // Method to replace a bookmarked text with a specified value.
            void setBmkText(string bmk, string value)
            {
                //Check if the bookmark exists in the bookmark collection or not
                if (!bmks.Contains(bmk))
                    return;
                var t = bmks[bmk].GetRange();
                t.Texts[0].Value = value;
                for (int i = t.Texts.Count - 1; i > 0; --i)
                    t.Texts[i].Delete();
            }
        }

The newly generated document can be saved using the Save method of the GcWordDocument class.

When previewed in MS Word, your finished version will look like this:

How to Create a MailMerge using Bookmarks on .NET Core 3