Demo
Demo

Knowledge base

PMTA knowledge base›Block Global›Directive§ 3.3.1.39

mailmerge-expands-undefined-variables

Global

What to substitute for a mail merge variable without a value
in the configuration this is a linemailmerge-expands-undefined-variables trueinside the block Global
An empty spot or a visible bracket

The default is true: a mail merge variable for which no value was passed expands to an empty string. The message goes out with a hole in its place.

With the value false an insert like [foo] stays in the message as is — with the brackets and the variable name.

A choice between two ways of showing an error: quiet and loud. The quiet one lets a message through with the client’s name missing; the loud one shows the recipient square brackets.

The main trap is that the default hides the error. An empty string in place of a name looks like a layout typo: “Hello, !”. Recipients will notice it, not you, and not right away.

The value false is louder, but not better: brackets in a message read as a technical malfunction, and that affects the sender’s reputation worse than an omission.

The right way out is a third one, and it is not in this line: check data completeness on the submitting side. Both settings merely choose how an error that has already happened looks.

What the Hub does. It does not write it — the vendor true stays. Mail merge is not used in the Hub’s submission at all: messages are assembled on its side and go out ready.

There are no recipient variables in the Hub’s messages, so there is nothing to omit: the warm-up template expands only spintax {a|b}, and unclosed brackets are checked when the message is saved.

Recommended values

What to set. Both settings are bad, and you choose the lesser of two evils:

Value When
true (default) a person reads the message, and an omission is less noticeable than brackets
false messages are checked by eye before sending, and the bracket is needed as a signal

The second makes sense on a test mailing: there a bracket is a find, not a disgrace. On a production one the default is better.

The true default and the behavior of both values come from the manual, § 3.3.1.39. The assessment “both settings merely choose the form of the error” is ours.
Example configuration
# on a test mailing a bracket is a find, not a disgrace
mailmerge-expands-undefined-variables false
With this value an insert like [foo] stays in the message whole. On a production mailing this is worse than an omission: brackets read as a malfunction.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Choosing between two settings instead of checking the data

our experience

What it costsBoth merely choose how an error that has already happened looks. A message with missing data goes out either way — with a hole or with a bracket.
How to spot itMissing names or visible brackets regularly show up in mailings.
How to do it rightCheck data completeness on the submitting side, before sending.

Using the visible bracket on a production mailing

§ 3.3.1.39

What it costsRecipients read brackets in a message as a technical malfunction. This is more noticeable than an omission and worse for how the sender is perceived.
How to spot itRecipients see square brackets with variable names in messages.
How to do it rightKeep false only on test mailings.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
mailmerge-expands-undefined-variables <boolean>
Values
yes | no | true | false
Default
true § 3.3.1.39
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
Global
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The directive is written at the root of the configuration file and applies to the whole node: there is one rule for all mail merge. It cannot be split by sources or recipients.
⇄

Related directives

1 relation

Applies to

Personalization inside the engineThe rule concerns only messages assembled by mail merge; it does not apply to ordinary substitutions. § 3.3.1.39

Referenced from

allow-mailmerge<source>Decides what to do with a variable for which no value was passed. § 3.3.1.39

How to check on the node
The line is visible in the configuration; check with a message:
grep -n 'mailmerge-expands-undefined-variables\|allow-mailmerge' /etc/pmta/config /etc/pmta/virtualhost.txt
If mail merge is not allowed for any source, the line will not show up at all. Check the behavior with a message that has a deliberately missing variable.
◇

What else to read

3 articles

◇How a message gets into the engineSix described submission methods: extended SMTP, four language bindings and a directory the node watches on disk.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇Headers the sender uses to control deliverySix control headers let the submitting side choose a stream, tag a message with a job, set signing options and the key, the envelope identifier and the schedule; each is allowed separately and per source.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Connect a sending platform
Neighboring settings of the block Global:host-idinclude-headers-frompickup-remove-dothost-namepostmasterAll 108 directives of the block →