Free Support Forum -

How to use Microsoft Word Mail Merge feature using Aspose.Words REST API

The Documentation for Aspose.Words for Cloud Templates 1.1 Features says that the API can consume data in JSON format, and instructs the user to look at the [executeTemplate (Controller Resource)] , but that thing is not a link, nor is it in the menu to the left. What documentation is the right one? The documentation for executeMailMerge (Controller Resource) doesn’t talk about JSON (except as a respones), neither does executeMailMerge vs executeTemplate.

executeTemplate Resource does show an example JSON data structure, but it does not explain what is required and not required about that data structure. Is it necessary that the outer structure be a JSON Object, or could it be a list? Is it necessary that the inner object be a list, or could it be an object? Etc.

I’m trying to work my way through it by trial and error, but the process is frustrating given that you pay to use the Cloud API by the request.


As far as executeMailMerge resource is concerned, it does not support JSON in the request body. Our developers are working on this issue and it will be available very soon.

executeTemplate API does support JSON and you can use foreach structures, fields with a dot in the name like Address.City etc. and simple fields. In case of foreach, you will pass the JSON structures as a list. In case of a dot, you will pass a JSON structure and in case of simple field, you will pass simple value as you can see in the simple template JSON at

In this example, Order is a foreach structure and passed as a list of orders. Address fields have dots in the field names and Address is passed as a JSON structure. Item is also a foreach structure and passed as a list of items. Remaining fields are simple fields and simple values are passed.

We will update your mentioned topics in a few hours for JSON related details and update you one done.

Best Regards,


Thanks for your attention to this matter. It will definitely help to update the documentation.

However, just to clarify exactly what I’m asking for. . . The documentation says in effect that the user is to provide a JSON data structure. JSON is very clearly defined and needs no documentation from you guys. And, the documentation says in effect that you can use Mustache tags in documents. Mustache tags are pretty well documented in that project as well.

The problem is that the implementation, at present, doesn’t actually conform to the standards it refers to. You can’t submit “a JSON data structure”, you need to submit a JSON object (not a list) that contains a list. And likewise, you can’t use Mustache tags generally, you can only use a subset of Mustache tags, and only in certain ways, and with several deviations from the standard. (For example, {{#foreach tagname}} rather than {{#tagname}} to enter a context.)

The problem with the documentation is simply that it doesn’t tell the user (e.g. the data structure submitter or the template designer) how your implementation differs from the cited standards. As you pointed out, the documentation does provide some examples of what can be done; e.g. it provides a sample JSON data structure, and there is a sample document available.

However, what would be really useful to a developer trying to use the system is simple and clear documentation that either:
  • Lays out in a positive fashion what is possible.
    • E.g. rather than saying, “Mustache tags”, saying exactly, Aspose supports these 12 tags, and only these 12 tags, used in these circumstances.
    • Or, rather than saying “JSON”, says exactly, you must submit a JSON structure to Aspose that:
      • Is a dictionary (not a list), and
      • has within it a single property that is a list of dictionaries,
      • which has within it at least two properties.
  • Or, lays out in a negative fashion what is possible, with reference to the standards.
    • E.g. Aspose supports everything in Mustache tags, except for X, Y, and Z.
This sort of clear and simple definition would make it a lot easier to develop applications that use Aspose Cloud API.


Thanks for the details. We will fix the issues reported in your threads on this topic and update the documentation accordingly.

Best Regards,