RTF mail merge

A mail merge fills the fields of a document from an outside data source, such as a spreadsheet or database, making one merged document per record. An RTF document that contains a {\*\mailmerge …} destination is a source document connected to such a data source; apart from that it is an ordinary RTF document with fields (MERGEFIELD and so on). The destination records how the document connects to the data and how the data fills the fields. None of these control words is in the RTF 1.6 specification; the control word index of the 1.9.1 specification flags them as added for Word 2007.

Syntax

<mailmerge>  '{\*' \mailmerge <mmmaintype> \mmlinktoquery? <mmdatatype> \mmdefaultsql?
             (<mmconnectstrdata> | <mmconnectstr>)? <mmquery>? <mmdatasource>?
             \mmblanklinks? <mmheadersource> <mmdest> <mmaddfieldname>? <mmmailsubject>?
             \mmattach? \mmshowdata? \mmreccurN \mmerrorsN <mmodso>*
             \mmodsocoldelimN \mmjdsotypeN \mmodsofhdrN <mmodsorecipdata>+ '}'
<mmmaintype> \mmmaintypecatalog | \mmmaintypeenvelopes | \mmmaintypelabels |
             \mmmaintypeletters | \mmmaintypeemail | \mmmaintypefax
<mmdatatype> \mmdatatypeaccess | \mmdatatypeexcel | \mmdatatypeqt | \mmdatatypeodbc |
             \mmdatatypeodso | \mmdatatypefile
<mmdest>     \mmdestnewdoc | \mmdestprinter | \mmdestemail | \mmdestfax
<mmodso>     '{\*' \mmodso (<mmodsoudldata> | <mmodsoudl>)? <mmodsotable>? <mmodsosrc>?
             <mmodsofilter>? <mmodsosort>? <fldmpdata>? '}'
<fldmpdata>  '{\*' \mmodsofldmpdata <mmfttype>? <mmodsoname>? <mmodsomappedname>?
             \mmodsofmcolumnN \mmodsodynaddrN \mmodsolidN '}'
<mmfttype>   \mmfttypenull | \mmfttypedbcolumn | \mmfttypeaddress | \mmfttypesalutation |
             \mmfttypemapped | \mmfttypebarcode
<mmodsorecipdata> '{\*' \mmodsorecipdata \mmodsoactiveN <uniqueid> '}'
<uniqueid>   '{' \mmodsohashN | \mmodsocolumnN & <mmodsouniquetag> '}'

The text groups are {\mmconnectstrdata #SDATA}, {\mmconnectstr …}, {\mmquery …}, {\mmdatasource …}, {\mmheadersource …}, {\mmaddfieldname …}, {\mmmailsubject …}, {\mmodsoudl …}, {\mmodsoudldata #SDATA}, {\mmodsotable …}, {\mmodsosrc …}, {\mmodsofilter #SDATA}, {\mmodsosort #SDATA} (the specification’s grammar prints this one as \mmodsofilter by mistake), {\mmodsoname …}, {\mmodsomappedname …} and {\mmodsouniquetag …}. #SDATA is hexadecimal data.

The grammar writes \mmblanklinks, but the control word index lists it as \mmblanklines (a flag, 2007); the specification gives no description of it.

Connection and query

Control word	Type	Meaning
`\*\mailmerge`	destination	The mail merge settings; marks the document as a source document.
`\mmlinktoquery`	flag	The query string in `\mmquery` refers to an outside query file, in the form `SELECT * FROM <query file path>`. Without it the query is not a link to a file.
`\mmdefaultsql`	flag	Use the default query, `SELECT * FROM <datasource>`.
`\*\mmconnectstrdata`	destination	The connection string for reconnecting to the data source, hex-encoded.
`\*\mmconnectstr`	destination	The connection string as plain text; replaced by `\mmconnectstrdata` because long strings may be cut short.
`\mmquery`	destination	The SQL query run against the data source to get the records. Without it no query is associated.
`\mmdatasource`	destination	Location of the data source.
`\mmheadersource`	destination	A file with column headers, for a data source that has none; headers are needed to map columns to fields.
`\mmaddfieldname`	destination	The column holding e-mail addresses, independent of the field mappings. Without it, or if the column does not exist, no addresses are used.
`\mmmailsubject`	destination	Subject line for merged e-mails or faxes; ignored for other destinations.
`\mmattach`	flag	Send merged e-mails with the document as an attachment instead of as the message body; only with `\mmdestemail`.
`\mmshowdata`	flag	Show the data of a record in place of the merge fields; the record is `\mmreccurN` (1 if missing).
`\mmreccurN`	value	One-based index of the record to show. Ignored without `\mmshowdata`; values below 1 or above the record count are treated as 1.
`\mmerrorsN`	value	Error reporting: 1 simulate the merge and report errors in a new document; 2 pause at each error (the default, also for missing or other values); 3 merge and report errors in a new document.
`\mmblanklines`	flag	Listed in the index only; not described.

Document, data and destination types

Control word	Meaning
`\mmmaintypecatalog`	The source document is a catalogue (directory).
`\mmmaintypeenvelopes`	Envelopes.
`\mmmaintypelabels`	Labels.
`\mmmaintypeletters`	Letters.
`\mmmaintypeemail`	E-mail messages.
`\mmmaintypefax`	Faxes.
`\mmdatatypeaccess`	Connected to a database through Dynamic Data Exchange (DDE).
`\mmdatatypeexcel`	Connected through DDE (the specification gives the same wording as for Access).
`\mmdatatypeqt`	Connected through an outside query tool.
`\mmdatatypeodbc`	Connected through ODBC.
`\mmdatatypeodso`	Connected through the Office Data Source Object (ODSO).
`\mmdatatypefile`	Connected to a text file through DDE.
`\mmdestnewdoc`	Merge into new documents.
`\mmdestprinter`	Print the merged documents.
`\mmdestemail`	Send the merged documents as e-mails.
`\mmdestfax`	Send the merged documents as faxes.

Office Data Source Object settings

The \mmodso groups hold further settings used when the data type is \mmdatatypeodso; otherwise readers may ignore them in favour of the settings above.

Control word	Type	Meaning
`\*\mmodso`	destination	The ODSO settings.
`\*\mmodsoudldata`	destination	A Universal Data Link (UDL) connection string, hex-encoded, used only with ODSO.
`\*\mmodsoudl`	destination	The UDL string as text; replaced by `\mmodsoudldata` because long strings may be cut short.
`\mmodsotable`	destination	Which table or worksheet of a data source with several to use.
`\mmodsosrc`	destination	Location of the data source (ODSO only).
`\*\mmodsofilter`	destination	Which records to include; `\mmodsoudldata` wins on conflict.
`\*\mmodsosort`	destination	Order of the records; `\mmodsoudldata` wins on conflict.
`\mmodsocoldelimN`	value	Column delimiter of the data source, as the decimal Unicode value of the character.
`\mmjdsotypeN`	value	A suggestion of the data source type; may be ignored. The values are not listed.
`\mmodsofhdrN`	value	The first row of the data holds column names. Without it the first row is data.
`\*\mmodsofldmpdata`	destination	One mapping of a data column to a type of merge field.
`\mmodsoname`	destination	The column’s name in the data source.
`\mmodsomappedname`	destination	The predefined field name it maps to (such as `First Name`); may be ignored if the program has no such field.
`\mmodsofmcolumnN`	value	Zero-based index of the column; 0 if missing or too large. The specification’s example writes −1 for unmapped fields.
`\mmodsodynaddrN`	value	Order the AddressBlock field by the record’s country, or use the country-invariant form. Without it the form depends on the country.
`\mmodsolidN`	value	Language ID in which the mapped field name was made.
`\mmfttypenull`, `\mmfttypedbcolumn`, `\mmfttypeaddress`, `\mmfttypesalutation`, `\mmfttypemapped`, `\mmfttypebarcode`	flag	Type of the mapping: null, database column, address block, salutation, mapped, barcode.
`\*\mmodsorecipdata`	destination	Inclusion or exclusion of one record.
`\mmodsoactiveN`	value	0: leave the record out of the merge. Missing: include it.
`\mmodsohashN`	value	A hash identifying the record.
`\mmodsocolumnN`	value	Zero-based column holding a unique value for the record, used with `\mmodsouniquetag`; ignored if too large.
`\mmodsouniquetag`	destination	That unique value.

{\*\mailmerge\mmmaintypeletters\mmlinktoquery\mmdatatypeodso{\*\mmconnectstrdata …}
{\mmquery SELECT * FROM `Sheet1$`}{\mmdatasource C:\\Documents and Settings\\Desktop\\ExampleExternalDataSource.xls}
\mmdestnewdoc\mmreccur1\mmerrors2{\*\mmodso{\*\mmodsoudldata …}{\mmodsotable Sheet1$}
{\mmodsosrc C:\\Documents and Settings\\Desktop\\ExampleExternalDataSource.xls}{\*\mmodsofilter }{\*\mmodsosort }
{\*\mmodsofldmpdata\mmfttypedbcolumn{\mmodsoname First Name}{\mmodsomappedname First Name}\mmodsofmcolumn1\mmodsolid1033}
…}}

Shortened from the specification’s example of a document connected to a spreadsheet.

Source

Microsoft, Rich Text Format (RTF) Specification, version 1.9.1, 19 March 2008, section “Mail Merge” and Appendix B; the PDF copy Microsoft keeps for its Open Specifications (officeprotocoldoc.z19.web.core.windows.net/files/Archive_References/[MSFT-RTF].pdf), read in full for this page.

.RTF File Format – Mail merge

Syntax

Connection and query

Document, data and destination types

Office Data Source Object settings

Source