When sendmail receives a message via SMTP, it can also receive an envelope identifier as part of the envelope sender declaration:

MAIL From:<address> ENVID=envelopeID

Here, the MAIL FROM: command specifies the envelope sender's address. Following that address is the keyword ENVID= followed by the envelope identifier. Whenever this identifier is presented and accepted, sendmail will place a copy of the identifier into this ${dsn_envid} macro.

A badly formed identifier (one that is not properly xtext-encoded, Section 21.6.2) will be rejected with:

501 5.5.4 Syntax error in ENVID parameter value

For a more complete explanation of the ENVID= keyword, see the ${envid} macro in ${envid}. Note that this ${dsn_envid} macro is set when mail is received via SMTP and when the -V command-line switch (-V) is used to set the envelope identifier. By contrast, the ${envid} macro is set only during delivery.

Note that the envelope ID described here is different from the message ID (as used with the Message-Id: header, Message-ID:), and different from the queue ID (which identifies a queued file, Section 11.2.1).

One possible use for this ${dsn_envid} macro might be to syslog the envelope identifier. Another possible use might be to include a header showing the envelope identifier. Consider these mc configuration lines that do the latter:

LOCAL_CONFIG
H?${dsn_envid}?X-DSN-ENVID: ${dsn_envid}
C{persistentMacros} {dsn_envid}

Under V8.12 and above sendmail, the X-DSN-ENVID: header in the preceding example will be included only if the message was received with an envelope identifier that caused the ${dsn_envid} macro to have a value. The C line in the preceding example adds the name {dsn_envid} to the $={persistentMacros} class. Without this line, the value in the ${dsn_envid} macro would not survive queueing.

${dsn_envid} is transient. If it is defined in the configuration file or in the command line, that definition can be ignored by sendmail. Note that a $& prefix is necessary when you reference this macro in rules (that is, use $&{dsn_envid}, not ${dsn_envid}), but a $& prefix is not necessary in header definitions.