Overview

DSMTP has four ways of setting up an alias or mail redirection.

We DO NOT recommend using a mixture of ALL of them :-)

You can:

1. create a forward rule (in dmail.conf)
2. create an alias rule (in a domain specific aliases file)
3. create a 'forward' file for each user (in the drop directory or home directory)
4. return a new destination address in your external authentication response

Skip straight to some examples
How to forward multiple copies

In general, the syntax of all of the above rules require an 'alias_address' and a 'destination_address'. E.g. a forward rule might look like,
forward bob@domain1.com julie@domain2.com
which has the syntax:
forward alias_address destination_address

When DSMTP gets an incoming message it looks for a rule with an alias_address that matches the address on that incoming message (the 'RCPT TO:' line of the SMTP protocol). The rule then gives DSMTP a new 'destination_address' to which DSMTP tries to deliver the message.

So what are the basic differences?

1. Forward settings are simple because they are processed as soon as a message arrives - i.e. before anything else is done. So they can be for ANY domain, not just domains on your server. They must contain the full email address (both user and domain) for both the alias_address and destination address. E.g.
forward Bob.Smith@domain bsmith@domain

Forward settings are entered in dmail.conf itself (or you can use #include if you want them in another file).

2. Similarly, an alias might be:
Bob.Smith: bsmith@domain
i.e. aliases have the syntax,
alias: destination_address
Aliases are only for users on local domains (as set by host_domain and vdomain settings).

You enter aliases in an 'alias file' that is specific to the domain that the user is in.

3. You can also have a forward file for any specific user. This forward file is checked just before the incoming message is written to the user's drop file. The file can be located in the user's home directory (on UNIX based platforms) or in the drop file directory.

Since the file is for a specific user, it only needs to contain a list of (comma separated) destination addresses.

Because the forward file is looked for so late in the process, DSMTP will only find and action it if no other redirection rules have already been found (unless they allow the original recipient to also get the message).

4. The last option is available to you if you are running an External Authentication Module. You can make your module (NWAuth has it built in) return a new destination address in the fwd="" field of its response.

This is very nice as you can edit forwarding in your user database (e.g. LDAP or ODBC databases).

Below are some general notes on mail redirection. These are followed by the following sections:

1. forward_settings
2. aliases
3. forward files
4. Ext. Auth FWD Field

Notes:

1. DSMTP does not necessarily look for the different types of rule at the same point in the message delivery process.
2. In general, you can use a mixture of the different mail redirection options, but we do not recommend using all of them at once, as the expected result can be difficult to work out. See mixed forwarding systems
3. You can also, in general, have multiple rules for any given alias_address and they will all be applied, e.g.
   forward mymail destination1
   forward mymail destination2
   etc.
4. All methods of mail redirection can be used to make DSMTP deliver messages to a specific file or to a robot, see Special Forwards.
5. Forwarding implies that the original recipient does not get the message. However most of the forwarding options have a method to allow the original recipient to get the message as well as the new destination. E.g. instead of using a forward setting you could use a forward_cc setting.
6. For information on checking forward rules see the following FAQ,
   How can I check what aliases I have set up for a user?

1. Forward Settings

Forward settings are for any domain, local or non-local users. DSMTP searches for and applies them as soon as it receives a message.

E.g.
forward bob@domainx.com julie@domainy.com will cause DSMTP to forward any mail received for the address, bob@domainx.com to the destination address, julie@domainy.com.

If DSMTP cannot get the message delivered to the destination address, i.e. julie@domainy.com, then it will bounce the message in the normal way.

The received address, bob@domainx.com above, can be for any domain. It does not have to be one that DSMTP recognizes as a host_domain or vdomain setting.

NB: Notes on forward settings:

• The original recipient does not get the message. If you want them to, use the forward_cc setting.
• Forward settings can be created for any users on any domain
• There is a fallback_address setting to pick up mail not covered by a forward setting for a specific domain.
• If you have domain names with upper case characters in them, you should create forward settings for them in the lower case. This is because DSMTP will lower case the domain name before looking for settings in dmail.conf.
• After changing a forward setting you should only have to do the tellsmtp reload command, to make DSMTP reload its forward settings.

Relevant settings: (in the reference section)
forward forward_cc

2. Aliases

An alias is written on one line, starting with the user part of an address which DSMTP should look for on incoming messages (in the RCPT TO: line). Then you type a colon followed by a space and the destination address where DSMTP should deliver the message to instead, if it finds the match. Here is an example,
Bob.Smith: bsmith@domain
i.e. alias: destination_address
(the two addresses are separated by a colon, ':' and a space)

You add the entry to a file that contains aliases for a specific domain, i.e. you create a domain(s) specific alias file.

To do this, add a setting to dmail.conf like,
alias_file_domain domain filename
where domain is the domain to which all of the aliases in the file, filename, apply.

After changing aliases remember to reload DSMTP with the
tellsmtp reload command.

NB: Notes on Aliases:

• NOTE: All aliases found for a user by DSMTP are applied.
• Aliases are only for local domains. DSMTP checks that the destination domain is local before looking for an alias.
• Aliases are case sensitive except for the Postmaster alias, which in version 2.4e and above, can be any case (POSTMASTER, postmaster,PoStMaStEr etc.).

  So, for the examples above you must have separate aliases for
  Bob.Smith: bsmith@domain
  and
  bob.smith: bsmith@domain

  There is a fallback_address setting to pick up mail not covered by a forward rule for a specific domain.

• The postmaster alias should not be specified in an alias file as DSMTP automatically creates it for all domains. The destination is set by the dmail.conf setting, sysadmin
• After changing or adding an alias within a file you should only have to do the tellsmtp reload command, to make DSMTP reload its aliases.
• In versions 2.5e and above you can specify the alias as one of the destination addresses, if you want the original recipient to also get the message, e.g.
  bob.smith: bob.smith,user@domainx.com
  will now work. This is known as a 'self referencing alias'.

Relevant settings: (in the reference section)
alias_file alias_file_domain

4. Ext. Auth FWD field

External Authentication modules can optionally return the field fwd="emailaddress" in their response to a successful 'lookup' or 'check' command, e.g.
+OK username config 0 fwd="destination_address"

If such a field is returned, DSMTP will cache the destination address along with the username. DSMTP will then use the destination address as a forwarding rule for that user. So any mail arriving for that user will be forwarded to the destination address, as if there was a forward rule for them in dmail.conf. Obviously then this type of forwarding is only for local domains, where DSMTP is going to try to look up the user.

In Version 2.5d and above you can make your external authentication return multiple destination addresses, as well as a destination file or robots and also the $user symbol, so that the original recipient receives the message (like forward_cc). E.g. the following examples are now valid;

single destination address:
+OK username config 0 fwd="destination_address"

multiple destination address:
+OK username config 0 fwd="destination_address1,destination_address2"

single destination and original recipient receives the message:
+OK username config 0 fwd="$user,destination_address"

forward to destination and to a robot:
+OK username config 0 fwd="destination_address,|c:\dmail\drespond.exe c:\dmail\message.txt -hasheaders"

forward to specific file:
+OK username config 0 fwd="c:\dmail\filename"

The multiple entries are comma separated (spaces are not a separator), and you CAN NOT have quotes within the forward field. This means that you cannot put multiple word arguments in the command line for the robot (as they would need quotes around them). See the drespond -hasheaders option to help get around this problem.

The $user can be used once with any other destination in the field.

The tellsmtp command,
tellsmtp clear_cache_all
was added in version 2.4e, to reset DSMTP's cache.
(we will be adding tellpop clear_cache_all and tellpop clear_cache user at a later date)

DSMTP caches the last 1000 lookups. So after changing a FWD entry in the external authentication database you have to do a,
tellsmtp clear_cache_all
command, from a command prompt.
Both DPOP and DSMTP cache their user lookup results. On a password fail, they refresh their cached entry, just in case the password has changed for the user. So you should not need to do a cache clear for either DPOP or DSMTP after changing a password.

You should look at the source to NWAuth to get an idea of what should be returned by your external authentication module. Also see the External Authentication section for details on the syntax of the external authentication protocol. Note that the fwd="" field is an optional field which comes after the uid.

FYI . . .
If you are wanting to do multiple forwards or to pipe the message to a robot, and you do not have a version where you can enter multiple destination addresses in the fwd="" field. Note that you can enter a destination_address that points to multiple forward rules in dmail.conf. Similarly the forward rule(s) could pipe to a robot.

3. Forward Files

The other method for forwarding messages is using forward files for specific users. Forward files are checked just before the message is written to the user's drop file. If found then the message is not written to the user's drop file and the redirection is done instead.

For the rest of this section note that
user_drop_name
is the users drop file name, which may, depending on your settings, include a drop_prefix, e.g. dom1_username and may have a vdomain_separator other than the underscore '_'.

Note: DSMTP has been made to work with all types of forward file, so if you mix forwarding systems then we appreciate that DSMTP's operation gets rather complicated. Basically we recommend that you decide on one way to do forwarding and stick to it. For example, it is not recommended to let some users do forwarding with a forward file and let other users use the fwd field of external authentication. At the end of this section there are some notes covering what happens when you use mixed systems.

On Windows platforms:

To set up a forward file for a user you should create a file, user_drop_name.fwd in the same directory as the user's drop file.

In this file you should add a list of comma, space or semicolon delimited addresses. If it is a pipe to a robot or drop file, then the entries must be one per line.

For example, a .fwd file could look like this:

bob@domainx.com,julie@domainy.com
dog@domainz.com;cow@domainq.com
horse@domainw.com rabbit@domainn.com
"|\dmail\drespond.exe message.txt"
"\strange_path\username"

Which would result in all of the above addresses, robots and strange drop files receiving the message (but as with all forward rules the original recipient won't get the message - see forward_cc if you want the original recipient to receive the message). Normally you would probably only have one or two entries in a forward file.

Notes on forward file syntax:

• entries can be separated by being entered on a new line
• entries are separated on a line by commas or semicolons (not spaces)
• special forwards should be entered on a line by themselves
• special forwards can have quotes around them if required

On UNIX based platforms:

You can use either:

1. UNIX style .forward files where the file is located in the user's home directory

2. Our .fwd files which are located beside the user's drop file (as described for windows platforms above).

You can only choose option 1 if you are using UNIX authentication, i.e. you have set
authent_method unix_user
and you have set home directories in the system password file.

If you are not using External Authentication and the passwd file check finds a valid user, DSMTP will exclusively look for the file ~user_drop_name/.forward, and use it if it finds it, where ~user_drop_name is the home directory for the user from the passwd file. If it cannot find the .forward file then it won't look for any other forward files, but if the home directory entry is blank then it will look for the .fwd file as per the windows platform details above. Note that virtual domain password files set with the vdomain_passwd setting are processed in the same way, i.e. you can enter a home directory for the users and DSMTP will look for a .forward file within it.

If you have home directories specified for users in the passwd file (or vdomain passwd files) but want the user's forward file in the drop file directory, then you can set
no_dotforward true
and DSMTP will only ever look for a .fwd file as per the windows platform details above.

If you are using external authentication then DSMTP will look for the .fwd file on UNIX based platforms (as per the windows platform details above).
 

Notes on using Mixed Forwarding Systems:

DSMTP has been made to work with all types of forward file, so if you mix forwarding systems we appreciate that DSMTP's operation gets rather complicated. Basically, we recommend that you decide on one way to do forwarding and stick to it. For example, it is not recommended to let some users do forwarding with a forward file and let other users use the fwd field of external authentication.

Forward rules, aliases and the fwd="" field returned as part of an External Authentication are separate forwarding systems that have precedence over forward files, i.e. If any of these exist for a user, DSMTP will not look for a forward file. Having said that, all the other forwarding options have precedence, a forward file will still affect them if they use a self referencing option, i.e. where that system calls for the original recipient to also receive the message - e.g. $user in a fwd="" field. In these cases, DSMTP has been told to try to deliver the message to the user (amongst other things) and just before it writes the drop file it checks for the forward file and, if found, uses it INSTEAD of delivering to the original recipient.

Here is all the above in a semi-coded form for those of you who prefer to read it this way . . .

When DSMTP uses .forward . . .

DSMTP checks or does the following and they MUST ALL be true:
authent_method Unix_user (so not ext. auth)
no_dotforward false
password lookup succeeds
password lookup returns a home directory

If they are all true then DSMTP checks the file,
home_directory/.forward

When DSMTP uses .fwd . . .

if any of the above are NOT true, AND the external authentication returns an EMPTY fwd="" field OR one with $user, then it checks the file,
drop_file.fwd
where drop file includes the drop_path (possibly including hashing) and the drop file name (possibly including drop_prefix and vdomain_separator), e.g.
d:\dmail\in\t\y\dom1_bob.fwd

To clarify, if the external authentication does return a forward destination then the .fwd file is not used UNLESS the destination is self referential - e.g. includes $user. If the destination does include $user but the .fwd file exists, the original recipient still won't get the message.

Special Forwards

All of the forwarding methods allow you to make DSMTP forward the message to a special destination of a specific file or program. To do this...

for a robot:
you must use the pipe symbol, '|' at the start of the destination address.

for a file:
you must include a path character, '/' or '\', which means that you must specify a full path and filename.

E.g. for a forward rule to write the file to the special UNIX file, /dev/nul, (it makes things disappear!) you could have,
forward bob@domainx.com /dev/nul

In this manual we refer to programs which receive a message (read in on stdin) as a 'robot'.

So, similarly, in order to send Bob's mail to a robot called drespond, you might have
forward bob@domainx.com |c:\dmail\drespond

If you want to make DSMTP take command line arguments for the program or robot, you should include the destination address within quotes, e.g.
forward bob@domainx.com "|c:\dmail\drespond arg1 arg2"

For more information on robots, see
Robots and specifically on autoresponders, see
Autoresponders - DRespond

Routing

DSMTP can be used to route mail on to another server. In order to do this, you will probably need to use gateway and forward settings and possibly, relay_to.

To help you work out which setting to use, this is the very basic outline of what DSMTP does with a message when it arrives:

1. apply any forward rules
2. check if the destination is a local domain (if not then queue it up for relaying on to the correct destination server (a gateway setting can be used for non-local domains that will often be encountered, so that DSMTP does not have to do a DNS lookup)
3. (is a local domain) looks for an alias
4. then do a lookup on the username (not the password)

The alias, or the forward or the username lookup (using an external auth module) can all specify that the message should go to a different destination, or to a robot. But given that they don't, DSMTP writes the message to the local user's drop file.

Gateways

DSMTP has a gateway setting, which has the syntax,
gateway domain ipaddress

If DSMTP is going to do a DNS MX lookup on the domain specified, it will instead simply use the ipaddress specified.

In general, this means that the gateway setting will be used for outgoing mail or for incoming mail that is not destined for the local server (relaying).

FYI . . .
The SMTP protocol was originally intended to allow messages to take an indirect path from SMTP server to SMTP server in order to reach the server where the user is considered 'local'. This is message relaying. These days, a message will normally go directly from the sending user's local SMTP server directly to the SMTP server where the destination user is 'local'. This is because the DNS mail exchange (MX) lookup done on the destination domain, will normally return the IP address of the end server and because server administrators tend to not allow mail to pass through their email server (there is generally no need and it allows spammers to hide).

If you want messages to go via a specific IP address, you can use a gateway setting to accomplish this. This is often done to allow mail to be sent through fire walls or where you have distributed internal email servers and you want email to enter the internet through one point.

Bounces and Delivery Status Notification (DSN)

(under construction, 16/6/99)

What happens when DSMTP cannot deliver a message?

The answer to this depends on what stage the message has got to before DSMTP cannot deliver it.

Note: You may like to read the FAQ, Tell me about the SMTP protocol

1. The connecting client is thrown off the server because of where they are connecting from - e.g. a ban_ip setting.
2. At the Rcpt To: stage of the SMTP protocol.

   DSMTP responds with a 500 level SMTP code and a text message giving the reason for rejection.

   This is the best place for DSMTP to reject the message as the sender will normally get an immediate message from the email client showing DSMTP's reason for rejection, e.g. the user is not known as a local user or relaying is not permitted by them.

3. At the end of the DATA stage:

   DSMTP responds with a 500 level SMTP code and a text message giving the reason for rejection.

4. when a relayed message is rejected by the next server:

   DSMTP creates a DSN if it has been requested, otherwise it bounces the message.

5. when a message for a non-local server cannot be delivered YET:

   DSMTP queues the message and sends a DELAY DSN if requested. It then tries to send it again in 2 hours time. It continues to try to send it up to the number of hours set by the max_retrytime setting.

   Examples of reasons for a message not being able to be delivered are the DNS server is not responding (so the destination server's ip address cannot be resolved), the destination server is not responding or returns a 400 level SMTP code (meaning come back later).

6. when DSMTP has accepted a message for local delivery and then fails to write it to the local user's drop file:

   This is very unlikely.

   DSMTP would create a DSN message if requested or otherwise bounce the message.

Settings Affecting Bounces:

Bounces are affected by the following DSMTP settings in dmail.conf:
bounce_body
bounce_maxlen

DSNs:

Delivery Status Notifications can be requested as part of the Extended SMTP (ESMTP) protocol.

This is done on the end of the RCPT TO: line of the SMTP protocol with the NOTIFY command. E.g.
RCPT TO:<bob@domain> NOTIFY=FAILURE
requests that the sender wants to be notified of a failure to deliver to bob@domain.

The NOTIFY command can take the value NEVER or one or more of, SUCCESS,FAILURE,DELAY.

Some examples:
RCPT TO:<bob@domain> NOTIFY=SUCCESS
RCPT TO:<bob@domain> NOTIFY=FAILURE,DELAY

Where:

+ A NOTIFY parameter value of "NEVER" requests that a DSN not be returned to the sender under any conditions.

+ A NOTIFY parameter value containing the 'SUCCESS' or 'FAILURE' keywords requests that a DSN be issued on successful delivery or delivery failure, respectively.

+ A NOTIFY parameter value containing the keyword 'DELAY' indicates the sender's willingness to receive 'delayed' DSNs. Delayed DSNs may be issued if delivery of a message has been delayed for an unusual amount of time, but the final delivery status (whether successful or failure) cannot be determined. The absence of the DELAY keyword in a NOTIFY parameter requests that a 'delayed' DSN NOT be issued under any conditions.

See also, I got a bounce (Delivery Status Notification) message from DSMTP ... for a list of explanations of common DSN and bounce messages.

Mail Re-direction Examples

1. How to redirect but do the normal delivery as well:
   (e.g. fred wants a copy of bob's mail, but bob still wants to receive it too)

   Mail re-direction usually means that the original recipient does not get the message, but it is easy to instruct DSMTP to carry out the delivery as well as the re-direction.

   a) Using Forward settings: use a forward carbon copy.

   forward_cc bob@domain1.com fred@domain2.com

   results in mail addressed to bob@domain1.com being re-directed to fred@domain2.com AND still going into bob's mailbox, bob@domain1.com.

   b)In alias files: use the special destination, $user, in the alias file destination.

   bob: $user,fred@domain2.com

   results in bob getting his mail as normal, and fred@domain2.com also getting a copy.

2. How to forward multiple copies: (fred and john want to receive all mail addressed to sales)

   a) use multiple forward settings as all matching forward settings will be applied.

   forward sales@domain1.com fred@domain1.com
   forward sales@domain1.com john@domain2.com

   results in fred and john receiving mail addressed to sales@domain1.com and the sales mailbox does not get any mail (fred and john could be at any destination domain).

   b)In alias files: give a comma separated list of destinations.

   sales: fred@domain2.com,john@domain2.com

   results in fred and john receiving mail addressed to 'sales', instead of it going to the 'sales' mailbox. By specifying the domain to which the alias file applies, you can control which domains this alias exists for. See the next example...

3. How do you set up an alias on all local domains?
   (bob wants to get mail addressed to sales@*)

   If bob really wants mail addressed to the user 'sales' at any domain which passes through DSMTP (incoming AND outgoing) then simply use a forward setting,

   forward sales@* bob@domain1.com

   Note - if bob tries to send a message to sales@othercompany.com then he will find his outgoing message gets re-directed back to him!

   What is more likely is that you only want bob to get mail addressed to sales at LOCAL domains.

   Option 1:

   If you add a domain as an alias of the main domain, by adding host_domain settings after your main domain, e.g.

   host_domain domain1.com
   host_domain domain2.com
   host_domain domain3.com

   then the user sales, will automatically have the aliases,

   sales@domain1.com
   sales@domain2.com
   sales@domain3.com

   so then all you have to add is an alias to redirect mail from sales@domain1.com to bob@domain1.com. One way to do this is to add the following alias to the domain1.com alias file,

   sales: bob@domain1.com

   (use the following line to tell DSMTP about the domain1.com alias file,
   alias_file_domain domain1.com c:\dmail\dom1aliases.txt )

   Option 2:

   You can use alias files to create the sales alias for any local domain, by specifying an alias file with the wildcard character.

   The alias_file_domain setting has the syntax,

   alias_file_domain <domain> <filename>

   You can specify that the file contains aliases for all domains with the wildcard character, i.e.

   alias_file_domain * c:\dmail\global_aliases.txt

   If you just want the alias for domains, domain1.com, domain2.com and domain3.com then point 3 settings at the same file, i.e.

   alias_file_domain domain1.com c:\dmail\aliases_group1.txt
   alias_file_domain domain2.com c:\dmail\aliases_group1.txt
   alias_file_domain domain3.com c:\dmail\aliases_group1.txt

   The domains, domain1.com, domain2.com and domain3.com can be declared as local with either a host_domain or vdomain line.

   In both cases, use the following line to add the alias in the alias file which you have specified

   sales: bob@domain1.com
   

ETRN

Yes, DMail supports the ETRN protocol as part of its support for Extended SMTP, ESMTP. This allows you to host or gateway for domains which are located on a 'remote' or 'dial up' server.

Basically, if another SMTP server sends DMail the ETRN command,e.g.,
ETRN domainx.com
DSMTP will try to send any mail in its outgoing queue waiting for that domain.

NB: DMail handles the queuing of mail for a 'dial up' domain automatically as part of its normal message queuing. If a connection cannot be established to the destination server (i.e. the dial up server that is one of your ETRN domains), DSMTP queues the message and tries to send it every 2 hours up to a limit set by the setting,
max_retrytime.

So in theory, to host an ETRN domain you don't have to do anything, DMail does it automatically.

However, in practice you probably need to set a,
gateway
setting for the domain and you will probably also need to set your SPAM rules so that users can relay mail through your server to that domain. The easiest way to do this is generally with the
relay_to
dmail.conf setting.

We have recently added a setting to version 2.8b,
suspend_domain
which can be useful. You can set it to suspend all mail for a specified domain, so that DSMTP does not try to send the mail every 2 hours. This setting does not affect the ETRN command, so that when an ETRN is received for the domain, DSMTP will still send all mail queued for it. NB: This can be a little dangerous because if a domain did not dial up and send ETRN for 2 months, any waiting mail would not get bounced to the sender.

DSMTP can also send the ETRN command, which allows it to act as the 'remote' or 'dial up' server. It sends the ETRN command as part of the ras_timer RAS dial up setting.