Rewrite rule template substitutions and control sequences

Substitutions are used to substitute into the rewritten address a character string the value of which is determined by the particular  substitution sequence used. For instance in the template $U@domain.com the  is a substitution sequence. It causes the username portion of the address being rewritten to be substituted into the  output of the template. Thus, if jdoe@host1.domain.com was being rewritten by this template, the resulting output would be jdoe@domain.com, the    substituting in the username portion, jdoe, of the original address.

Special control sequences may also appear in rewrite rule templates. These sequences impose additional conditions to the applicability of a given rewrite rule: not only must the pattern portion of the rewrite  rule match the host/domain specification being examined, but other  aspects of the address being rewritten must meet conditions set by the  control sequence or sequences. For instance, the  control sequence  requires that the address being rewritten be an envelope address while  the   sequence requires that it be a forward pointing address. Thus, the rewrite rule domain.com   $U@domain.com$E$F will only apply to (i.e., only rewrite) envelope To addresses of the form user@domain.com. If a domain/host specification matches the pattern portion of a rewrite rule but doesn&#x27;t meet all of the criteria  imposed by control sequences in the rule&#x27;s template, then the rewrite  rule fails and the rewriter continues to look for other applicable  rules. This makes possible sets of rewrite rules such as domain.com    $U%domain.com@conversion-daemon$Nconversion domain.com   $U@domain.com which will result in messages to user@domain.com being passed to the conversion channel. However, should the conversion channel rewrite a message with the address user@domain.com, that message will not again  pass through the conversion channel. This then allows all mail to user@domain.com to pass through the conversion channel and for the  conversion channel to emit mail to that address without causing a mail  loop. (Note: This is not a realistic example, as actual routing through the conversion channel is normally instead handling via the   mapping table rather than through rewrite rules; but this sort of rewrite rule approach could be used with other channels, such as a    type of channel.)

A summary of template substitutions and control sequences is presented in Summary of template substitutions  and control sequences.

  $ n G Rewrite default host substitutions Insert nth element, counting from left to right, of the current   $H Rewrite host domain and IP literal substitutions Unmatched portion of host/domain specification; left of dot in pattern  $L Rewrite host domain and IP literal substitutions Unmatched portion of domain literal; right of dot in pattern literal  $U Rewrite username and subaddress substitutions Username from original address  $0U</a> Rewrite username and subaddress substitutions Local part (username) from original address, minus any subaddress <tr bgcolor="blanchedalmond"> $1U</a> Rewrite username and subaddress substitutions Subaddress, if any, from local part (username) of original address <tr bgcolor="blanchedalmond"> $$</a> Rewrite literal character substitutions Inserts a dollar sign (literal) <tr bgcolor="blanchedalmond"> $%</a> Rewrite literal character substitutions Inserts a percent sign (literal) <tr bgcolor="blanchedalmond"> $@</a> Rewrite literal character substitutions Inserts an at sign (literal) <tr bgcolor="blanchedalmond"> $\</a> Rewrite case control substitutions Force substituted material to lowercase <tr bgcolor="blanchedalmond"> $^</a> Rewrite case control substitutions Force substituted material to uppercase <tr bgcolor="blanchedalmond"> $_</a> Rewrite case control substitutions Use original case (and do not do LDAP URL character encoding) <tr bgcolor="blanchedalmond"> $=</a> Rewrite LDAP query URL substitutions Force subsequent material to be properly quoted (encoded) according to      LDAP URL syntax rules <tr bgcolor="blanchedalmond"> $. text .</a> Rewrite LDAP query URL substitutions Specify text to use as the rewrite result in cases of temporary LDAP lookup failures <tr bgcolor="blanchedalmond"> $..</a> Rewrite LDAP query URL substitutions Turn off special handling of temporary LDAP lookup failures: even temporary LDAP lookup failures are interpreted as rewrite rule failure <tr bgcolor="blanchedalmond"> $W</a> Rewrite unique string substitutions Substitutes in a random, unique string <tr bgcolor="blanchedalmond"> $&lt;...&gt;</a> Rewrite hash substitutions Substitute in a hash of the argument <tr bgcolor="blanchedalmond"> $ n &lt;...&gt;</a> Rewrite hash substitutions Substitute in a hash of the argument, modulo n  <tr bgcolor="blanchedalmond"> $]...[     2.2.6.4</a> LDAP search URL lookup <tr bgcolor="blanchedalmond"> $( text ) 2.2.6.5</a> General &quot;database&quot; substitution; rule fails if lookup fails <tr bgcolor="blanchedalmond"> ${...}     2.2.6.6</a> Apply specified mapping to supplied string <tr bgcolor="blanchedalmond"> $[...]     <a href="book_463.html#head2_custroutinesubs">2.2.6.7</a> Invoke customer supplied routine; substitute in result <tr bgcolor="blanchedalmond"> $&amp;n <a href="book_464.html#head2_singlefieldsubstitutions">2.2.6.8</a> nth part of unmatched (or wildcarded) host as counting from left to      right starting from 0 <tr bgcolor="blanchedalmond"> $!     n       <a href="book_464.html#head2_singlefieldsubstitutions">2.2.6.8</a> n th part of unmatched (wildcarded) host as counted from right to left starting from 0 <tr bgcolor="blanchedalmond"> $*     n       <a href="book_464.html#head2_singlefieldsubstitutions">2.2.6.8</a> n th part of matching pattern as counting from left to right starting from 0 <tr bgcolor="blanchedalmond"> $#     n       <a href="book_464.html#head2_singlefieldsubstitutions">2.2.6.8</a> n th part of matching pattern as counted from right to left starting from 0 <tr bgcolor="blanchedalmond"> $     n D      <a href="book_46c.html#head2_subportion">2.2.6.2</a> Portion of domain specification that matched, preserving from the n th leftmost part starting from 0 <tr bgcolor="blanchedalmond"> $     n H      <a href="book_46c.html#head2_subportion">2.2.6.2</a> Portion of host/domain specification that didn't match, preserving from the n th leftmost part starting from 0 <tr bgcolor="blanchedalmond"> <a href="Rewrite_transport_substitutions">$Y</a> Rewrite transport substitutions Equivalent to $1Y; that is, substitute in the 1st (counting from the      left, starting from 0) field of the transport information; for the case of incoming SMTP messages, this corresponds to the SMTP server IP      address <tr bgcolor="blanchedalmond"> <a href="Rewrite_transport_substitutions">$ n Y</a> Rewrote transport substitutions Substitute in the n th (counting from the left, starting from 0) field of the transport information; hence, for incoming SMTP messages $0Y substitutes in the literal string &quot; &quot;, $1Y (see also $Y) substitutes in the SMTP server IP address, $2Y substitutes in the SMTP server port, $3Y substitutes in the SMTP client IP address, and $4Y substitutes in the SMTP client port <tr bgcolor="lightseagreen"> Control sequence Section Effect on rewrite rule <tr bgcolor="blanchedalmond"> <a href="Channel_match_force_truncation_rewrite">$1~</a> Channel match force truncation rewrite Force channel match &quot;success&quot; effect, although truncating the rewrite rule at this point if the &quot;real&quot; channel match failed <tr bgcolor="blanchedalmond"> <a href="TLD_comparison_rewrites">$,</a> TLD comparison rewrites (New in MS 7.0.5) Rewrite rule succeeds only if the top-level part of      the domain name argument following this metacharacter is present in the current list of known Top Level Domains (the list as constructed from      the        file) <tr bgcolor="blanchedalmond"> <a href="TLD_comparison_rewrites">$&gt;</a> TLD comparison rewrites (New in MS 7.0.5) Rewrite rule succeeds only if the top-level part of      the domain name argument following this metacharacter is not present in       the current list of known Top Level Domains (the list as constructed       from the        file) <tr bgcolor="blanchedalmond"> <a href="Alias-specific_rewrites">$:</a> Alias-specific rewrites Apply only if the address being rewritten is the result of an alias <tr bgcolor="blanchedalmond"> <a href="Alias-specific_rewrites">$;</a> Alias-specific_rewrites Fail if the address being rewritten is the result of an alias <tr bgcolor="blanchedalmond"> <a href="Address_direction_and_location-specific_rewrites">$E</a> Address direction and location-specific rewrites Apply only to envelope addresses <tr bgcolor="blanchedalmond"> <a href="Address_direction_and_location-specific_rewrites">$B</a> Address direction and location-specific rewrites Apply only to header/body addresses <tr bgcolor="blanchedalmond"> <a href="Address_direction_and_location-specific_rewrites">$F</a> Address direction and location-specific rewrites Apply only to forward-directed (     e.g., To:) addresses <tr bgcolor="blanchedalmond"> <a href="Address_direction_and_location-specific_rewrites">$R</a> Address direction and location-specific rewrites Apply only to backwards-directed (     e.g., From:) addresses <tr bgcolor="blanchedalmond"> <a href="Source_channel-specific_rewrites">$M</a> channel Source channel-specific rewrites Apply only if channel channel is rewriting the address <tr bgcolor="blanchedalmond"> <a href="Source_channel-specific_rewrites">$1M</a> Source channel-specific rewrites Apply only if an &quot;internal&quot; channel is rewriting the address <tr bgcolor="blanchedalmond"> <a href="Source_channel-specific_rewrites">$N</a> channel Source channel-specific rewrites Fail if channel channel is rewriting the address <tr bgcolor="blanchedalmond"> <a href="Source_channel-specific_rewrites">$1N</a> Source channel-specific rewrites Fail if an &quot;internal&quot; channel is rewriting the address <tr bgcolor="blanchedalmond"> <a href="Destination_channel-specific_rewrites">$Q</a> channel Destination channel-specific rewrites Apply if sending to channel channel <tr bgcolor="blanchedalmond"> <a href="Destination_channel-specific_rewrites">$C</a> channel Destination channel-specific rewrites Fail if sending to channel channel <tr bgcolor="blanchedalmond"> <a href="Deployment_map_role_rewrites">$/</a> host | role (New in MS 8.0.2) Deployment map role-specific rewrites Apply if the specified host has the specified role in the deployment map <tr bgcolor="blanchedalmond"> <a href="Deployment_map_role_rewrites">$|</a> host | role (New in MS 8.0.2) Deployment map role-specific rewrites Fail if the specified host has the specified role in the deployment map <tr bgcolor="blanchedalmond"> <a href="Host_location-specific_rewrites">$S</a> Host location-specific rewrites Apply if host is from a source route <tr bgcolor="blanchedalmond"> <a href="Host_location-specific_rewrites">$A</a> Host location-specific rewrites Apply if host is to the right of the at sign <tr bgcolor="blanchedalmond"> <a href="Host_location-specific_rewrites">$P</a> Host location-specific rewrites Apply if host is to the right of a percent sign <tr bgcolor="blanchedalmond"> <a href="Host_location-specific_rewrites">$X</a> Host location-specific rewrites Apply if host is to the left of an exclamation point <tr bgcolor="blanchedalmond"> <a href="Changing_the_current_tag_value">$T</a> newtag Changing the current tag value Set the rewrite rule tag to     newtag <tr bgcolor="blanchedalmond"> $I &#160;     Apply if sending to any of the channels in      channel-list <tr bgcolor="blanchedalmond"> $O channel-list &#160;     Fail if sending to any of the channels in      channel-list <tr bgcolor="blanchedalmond"> $?     errmsg <a href="book_46b.html#head2_rewriteerrormessages">2.2.6.20</a> If rewriting fails, return errmsg instead of the default error message <tr bgcolor="blanchedalmond"> $     nxxxyyy ? errmsg <a href="book_46b.html#head2_rewriteerrormessages">2.2.6.20</a> If rewriting fails, return SMTP error code n.xxx.yyy and error text errmsg instead of the default SMTP error code and error message <tr bgcolor="blanchedalmond"> $V domain <a href="book_46g.html#head2_rewritedomainmap">2.2.6.14</a> Succeed if domainMap succeeds (that is, if the domain name     domain is found in the DC tree) <tr bgcolor="blanchedalmond"> $Z domain <a href="book_46g.html#head2_rewritedomainmap">2.2.6.14</a> Succeed if domainMap fails (that is, if the domain name     domain is      not found in the DC tree) <tr bgcolor="blanchedalmond"> $ n J     &#160; Set mailbox flags <tr bgcolor="blanchedalmond"> $     n K      &#160; Clear mailbox flags <tr bgcolor="blanchedalmond"> &#160;     Set override <a href="alias_magic"> </a> value to be used for the domain which matched this rewrite rule when the rewrite rule is being used during alias expansion; n must be an appropriate  value <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is the message block size <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is greater than the message block size <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is greater than or equal to the message block size <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is less than the message block size <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is less than or equal to the message block size <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails when is the message block size <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is the number of lines in the message <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is greater than the number of lines in the message <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is greater than or equal to the number of lines in the message <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is less than the number of lines in the message <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is less than or equal to the number of lines in the message <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails when is the number of lines in the message <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is the message priority <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is greater than the message priority <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is greater than or equal to the message priority <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is less than the message priority <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails unless is less than or equal to the message priority <tr bgcolor="blanchedalmond"> <a href="book_46j.html#head2_rewritecomparisons">2.2.6.18</a> (New in 8.0) Rewrite fails when is the message priority -->

See also:
 * CONVERSIONS mapping table
 * Rewrite username and subaddress substitutions
 * Rewrite host domain and IP literal substitutions
 * Rewrite subdomain single field substitutions
 * Rewrite default host substitutions
 * Rewrite literal character substitutions
 * Rewrite case control substitutions
 * Rewrite LDAP query URL substitutions
 * Rewrite general database substitutions
 * Rewrite apply specified mapping substitutions
 * Rewrite routine substitutions
 * Rewrite unique string substitution
 * Rewrite hash substitutions
 * Rewrite transport substitutions
 * Source channel-specific rewrites
 * Destination channel-specific rewrites
 * Address direction and location-specific rewrites
 * Host location-specific rewrites
 * Deployment map role rewrites
 * Domain LDAP lookup rewrites
 * Channel match force truncation rewrite
 * TLD comparison rewrites
 * alias_magic override rewrite
 * Alias-sensitive rewrites
 * List-name-sensitive rewrites
 * Message size or priority comparison rewrites
 * Changing the current tag value
 * Controlling error messages associated with rewriting
 * Rewrite rule templates