Back: CSharp Reference Implementation

Gateway Configuration Settings

Configuration File

The SMTP Gateway currently retrieves operational settings and flags from an Xml Configuration file. You give the Gateway the path to this configuration file during installation.

A sample (and full featured) configuration file is checked into the source tree under csharp\gateway\SmtpAgent\SmtpAgentConfig.xml

Path to the Configuration File

To operate, the Smtp Gateway must know the path to its configuration file. You do this when you attach the Gateway to Smtp Server using the registerGateway.bat script.

You can configure a single SMTP Server (service) to run multiple virtual SMTP virtual servers. You can attach a separate SMTP Gateway to each of these instances. Each gateway instance has an associated Service Instance Number and configuration file.

Because SMTP Server is a native process, you have to supply the gateway with its configuration file path using non-.NET techniques. The registerGateway.bat script writes basic bootstrap properties into a COM property bag attached to each installation of the SMTP Gateway. For example, the developer gateway install script (csharp\gateway\devinstall\install.bat) does the following:
call registerGateway.bat script 1 %destbin%\DevAgentConfig.xml
  • The magic number 1 is the service instance number (1 for default)

Currently, the gateway does not automatically detect changes in configuration, so you must restart SMTP Service if you change the configuration for a running system (iisreset).

The root element of your config file is:
/SmtpAgentConfig



Domain & Address

Every SMTP Gateway is responsible for a set of domains. These are the same domains you configured your Smtp Service to manage. Two configuration choices exist. Static or Dynamic domains. Choose one. Static domains are for installations that do not change often. Dynamic domains are for installations that will have a large volume of domains that change often such as large HISP bringing on a new domain daily.

Static Domains

SmtpAgentConfig/Domain/ (Required)
<SmtpAgentConfig>
  <Domain>redmond.hsgincubator.com</Domain>
  <Domain>nhind.hsgincubator.com</Domain>

Dynamic Domains

Resolve domains from configuration service.
SmtpAgentConfig/Domains/ (Required)

The domain resolver operates as a SOAP proxy client.
/SmtpAgentConfig/Domains/ServiceResolver__ (Required)

Child
Required
Description
AgenName
Y
Agent name identifier
ClientSettings/Url
Y
Url of the Domain Service
CacheSettings/Cache
N
true or false. Default is false
CacheSettings/CacheTTLSeconds
N
Cache lifetime in seconds

<SmtpAgentConfig>
  <Domains>
    <ServiceResolver>
      <AgentName>DirectBridge1</AgentName>
      <ClientSettings>
        <Url>http://localhost:6692/DomainManagerService.svc/Domains</Url>
      </ClientSettings>
      <CacheSettings>
    <Cache>true</Cache>
    <CacheTTLSeconds>20</CacheTTLSeconds>
      </CacheSettings>
    </ServiceResolver>
  </Domains>

Domain Manager

You can configure the gateway to retrieve domain settings from the Configuration Service. The gateway retrieve settings only for the domains listed in the config file (above).
/SmtpAgentConfig/DomainManager
Child
Required
Description
Url
Y
Url of the Domain Service
MaxReceivedMessageSize
Y
In bytes. Default - no limit
Secure
N
Use Windows Authentication. Default - false
ReceiveTimeout
N
Seconds. How long to wait for a response. Default: 10 minutes (WCF)
SendTimeout
N
Seconds. How long to wait for request transmission. Default: 1 minute (WCF)
...
  <DomainManager>
    <Url>http://localhost:6692/DomainManagerService.svc/Domains</Url>
  </DomainManager>

Address Manager

Optional.

When configured with an Address Manager, the gateway verfies that all domain address - i.e. addresses belonging to domains the gateway manages - exists. It does so by looking up the address using the AddressManager service.

The Gateway verified addresses in both directions.
  • If a sender of an outgoing message is unregistered, the gateway rejects the message
  • If some domain recipients of an incoming message are unregistered, the gateway removes them from the SMTP Envelope RCPTO.
    • If no domain recipients can be verified, the Gateway rejects the message
  • If the DSN features have been enabled in the Notification section then failure DSN's will be bounced back to the internal senders indicating why the receiver cannot be contacted such as security or trust failures.

/SmtpAgentConfig/AddressManager
Child
Required
Description
Url
Y
Url of the Address Manager Service
MaxReceivedMessageSize
Y
In bytes. Default - no limit
Secure
N
Use Windows Authentication. Default - false
ReceiveTimeout
N
Seconds. How long to wait for a response. Default: 10 minutes (WCF)
SendTimeout
N
Seconds. How long to wait for request transmission. Default: 1 minute (WCF)
Settings
N
Optional settings for this AddressManager

/SmtpAgentConfig/AddressManager/Settings
Child
Required
Description
EnableDomainSearch
N
true or false. Default is false. Set to true will validate an email address as true if the address exists in the config store's address table or if the email host exists in the config stores Domain table. In both cases the address or domain must be enabled.

...
  <AddressManager>
    <Url>http://localhost:6692/DomainManagerService.svc/Addresses</Url>
    <Settings>
      <EnableDomainSearch>true</EnableDomainSearch>
    </Settings>
  </AddressManager>



Public Cert Resolution

You can configure the gateway to resolve public certificates from:
  • DNS
  • A machine store - and typically, only in debug/test environments.
  • From the Middle Tier ConfigService
  • PluginResolvers (the following are included in the reference implementation):
    • LdapCertResolver

Your production deployments will typically use DNS.

You can use multiple resolvers. The Gateway will try them in order until one succeeds.

/SmtpAgentConfig/PublicCerts (Required)

Dns Certificate Resolution

Resolve public certificates using DNS.

/SmtpAgentConfig/PublicCerts/DnsResolver
Child
Required
Description
ServerIP
Y
IP Address of the DNS server to send Dns requests to
BackupServerIP
N
IP Address of the DNS server to try if the primary throws fails (exceptions)
Timeout
N
In Milliseconds. Default 5000
Cache
N
true or false. Default is false
ResolveFromRoot
N
Some DNS servers do not support CERT requests. The resolver will resolve CERTS directly from certificate domain's root servers. Default is false. (NY Impl)
...
 <PublicCerts>
    <DnsResolver>
      <ServerIP>127.0.0.1</ServerIP>
      <Timeout>5000</Timeout>
    </DnsResolver>

Machine Store

Public certs stored on the local machine.
/SmtpAgentConfig/PublicCerts/MachineResolver
Child
Required
Description
Name
Y
The name of the certificate store.
Location
N
LocalMachine (default) or CurrentUser
...
 <PublicCerts>
    <MachineResolver>
      <Name>NHINDExternal</Name>
    </MachineResolver>

Config Service

Resolve private certs from the Configuration Service.
/SmtpAgentConfig/PrivateCerts/ServiceResolver

The certificate resolver operates as a SOAP proxy client.
/SmtpAgentConfig/PrivateCerts/ServiceResolver/ClientSettings (Required)
Child
Required
Description
Url
Y
Url of the Certificate Service
MaxReceivedMessageSize
Y
In bytes. Default - no limit
Secure
N
Use Windows Authentication. Default - false
ReceiveTimeout
N
Seconds. How long to wait for a response. Default: 10 minutes (WCF)
SendTimeout
N
Seconds. How long to wait for request transmission. Default: 1 minute (WCF)
...
  <PublicCerts>
    <ServiceResolver>
      <ClientSettings>
        <Url>http://localhost:6692/CertificateService.svc/Certificates</Url>
      </ClientSettings>
    </ServiceResolver>

PluginResolver Certificate Resolution

Resolve public certificates using PluginResolvers.
/SmtpAgentConfig/PublicCerts/PluginResolver/Definition
Child
Required
Description
TypeName
Y
.Net type implementing this plugin. It is a qualified type name in the following format: Assembly Name, TypeName
Settings
N
Optional settings for this plugin.

LdapCertResolver Plugin

Optional Plugin implemented Settings defined for LdapCertResolver Plugin. Please note: If you hope to be able to query LDAP Certificates (externally in another HISP's LDAP store) you will need to enable this plugin. Use the same IP you are using for the DNS Resolver and add the section <PluginResolver> just after the <dnsresolver> section as shown in the codebox below. A reboot is required after altering this.
/SmtpAgentConfig/PublicCerts/PluginResolver/Definition/Settings
Child
Required
Description
ServerIP
N
IP Address of the DNS server to send Dns requests to. Will use machines network interface configured DNS servers if not supplied.
BackupServerIP
N
(Not released. In source code.) IP Address of the DNS server to try if the primary throws fails (exceptions).
Timeout
N
In Milliseconds. Default 5000
Cache
N
true or false. Default is false

...
...
 <PublicCerts>
    <DnsResolver>
      <ServerIP>127.0.0.1</ServerIP>
      <Timeout>5000</Timeout>
    </DnsResolver>
    <PluginResolver>
      <Definition>
        <TypeName>Health.Direct.ResolverPlugins.LdapCertResolverProxy, Health.Direct.ResolverPlugins</TypeName>
        <Settings>
          <ServerIP>127.0.0.1</ServerIP>
        </Settings>
      </Definition>
    </PluginResolver>

Private Key Resolution

You can configure the gateway to resolve private certificates from:
  • The Config Middle Tier service
  • From a Machine Store.

You can use multiple resolvers. The Gateway will try them in order until one succeeds.

/SmtpAgentConfig/PrivateCerts (Required)

Config Service

Resolve private certs from the Configuration Service.
/SmtpAgentConfig/PrivateCerts/ServiceResolver

The certificate resolver operates as a SOAP proxy client.
/SmtpAgentConfig/PrivateCerts/ServiceResolver/ClientSettings (Required)
Child
Required
Description
Url
Y
Url of the Certificate Service
MaxReceivedMessageSize
Y
In bytes. Default - no limit
Secure
N
Use Windows Authentication. Default - false
ReceiveTimeout
N
Seconds. How long to wait for a response. Default: 10 minutes (WCF)
SendTimeout
N
Seconds. How long to wait for request transmission. Default: 1 minute (WCF)
...
  <PrivateCerts>
    <ServiceResolver>
      <ClientSettings>
        <Url>http://localhost:6692/CertificateService.svc/Certificates</Url>
      </ClientSettings>
    </ServiceResolver>

Machine Store

Resolve private certs stored from machine storage.
/SmtpAgentConfig/PrivateCerts/MachineResolver
Child
Required
Description
Name
Y
The name of the certificate store.
Location
N
LocalMachine (default) or CurrentUser
...
  <PrivateCerts>
    <MachineResolver>
      <Name>NHINDPrivate</Name>
    </MachineResolver>

Anchor Resolution

You can configure the gateway to resolve anchors from the Configuration Service, a local machine store or from ABBI (Blue Button) trust bundles.

You can configure your Gateway use multiple resolvers. The Gateway will try them in order until one succeeds.

You can also use the Plugin MultiSourceResolver (Gateway Version 1.2.0.2 and later) to configure the Gateway to try multiple *child* anchor resolvers. The MultiSourceResolver will combine the anchors discovered by its children into a single list.

The plugin BundleResolver will resolve ABBI (Blue Button) and other trust bundles from configured bundle Urls.

/SmtpAgentConfig/Anchors (Required)

Config Service Anchor Store

Resolve private certs from the Configuration Service.
/SmtpAgentConfig/Anchors/ServiceResolver

The certificate resolver operates as a SOAP proxy client.
/SmtpAgentConfig/Anchors/ServiceResolver/ClientSettings (Required)
Child
Required
Description
Url
Y
Url of the Certificate Service
MaxReceivedMessageSize
Y
In bytes. Default - no limit
Secure
N
Use Windows Authentication. Default - false
ReceiveTimeout
N
Seconds. How long to wait for a response. Default: 10 minutes (WCF)
SendTimeout
N
Seconds. How long to wait for request transmission. Default: 1 minute (WCF)
...
  <Anchors>
    <ServiceResolver>
      <ClientSettings>
        <Url>http://localhost:6692/CertificateService.svc/Anchors</Url>
      </ClientSettings>
    </ServiceResolver>

Machine Store

Anchors stored on the local machine.

/SmtpAgentConfig/Anchors/MachineResolver
Child
Required
Description
Incoming
Y
Settings for resolving incoming anchors
Outgoing
Y
Settings for resolving outgoing anchors
/SmtpAgentConfig/Anchors/MachineResolver/Incoming (Required)
Child
Required
Description
Name
Y
The name of the certificate store.
Location
N
LocalMachine (default) or CurrentUser
/SmtpAgentConfig/Anchors/MachineResolver/Outgoing (Required)
Child
Required
Description
Name
Y
The name of the certificate store.
Location
N
LocalMachine (default) or CurrentUser
...
  <Anchors>
    <MachineResolver>
      <Incoming>
        <Name>NHINDAnchors</Name>
      </Incoming>
      <Outgoing>
        <Name>NHINDAnchors</Name>
      </Outgoing>
    </MachineResolver>
  </Anchors>

Plugin Anchor Resolvers

Gateway V1.2.0.2 and later come with the following plugin anchor resolvers:
  • MultiSourceAnchorResolver
  • BundleResolver

The resolvers are implemented in Health.Direct.ResolverPlugins.dll. This should be deployed in your Gateway bin.

MultiSourceAnchorResolver

[V1.2.0.2] and later.

The MultiSourceAnchorResolver plugin combines the anchors resolved by one or more child resolvers into a single list.
Each child is always tried. This plugin is useful when you wish to resolve anchors from multiple sources, such as your default config service AND those published for ABBI (Blue Button)
  <Anchors>
    <PluginResolver>
      <Definition>
        <TypeName>Health.Direct.ResolverPlugins.MultiSourceAnchorResolver, Health.Direct.ResolverPlugins</TypeName>
        <Settings>
          <!-- Add child resolvers here -->
          <ServiceResolver> <!-- Find anchors in Standard Config Service Store -->
            <ClientSettings>
              <Url>http://localhost/ConfigService/CertificateService.svc/Anchors</Url>
            </ClientSettings>
             .....Resolver settings...
          </ServiceResolver>
          <BundleResolver> <!-- Also find configured anchor bundles -->
             ...Resolver settings....
          </BundleResolver>
        </Settings>
      </Definition>
    </PluginResolver>
  </Anchors>

Bundle Resolver (ABBI Blue Button)

[V1.2.0.2] and later.

Use the bundle resolver to resolve configured anchor bundles for domains and/or addresses.

  • Make sure your Config Service and Database schema was upgraded to support Bundles
  • You can use the ConfigConsole.exe to configure bundles.
    • Type *commands bundle* to get a list of bundle management commands
  • You configure an *owner* to trust an anchor bundle pointed at by a Url. *Owner* can be either a domain or an address-- just like you configure anchors in the config service.

The BundleResolver caches downloaded bundles. Use the CacheTTLSettings property below to control cache duration. In production, you should set the Cache setting to 1 day or greater.

  <Anchors>
    <PluginResolver>
      <Definition>
        <TypeName>Health.Direct.ResolverPlugins.MultiSourceAnchorResolver, Health.Direct.ResolverPlugins</TypeName>
        <Settings>
          <!-- Use Configured Bundles such as blue button -->
          <BundleResolver>
            <ClientSettings>
              <Url>http://localhost/ConfigService/CertificateService.svc/Bundles</Url>
            </ClientSettings>
            <CacheSettings>
              <Cache>true</Cache>
              <NegativeCache>true</NegativeCache>
              <!-- Set the CacheSetting to be large, since bundles don't change very often -->
              <CacheTTLSeconds>86400</CacheTTLSeconds>
            </CacheSettings>
            <MaxRetries>1</MaxRetries>
            <Timeout>30000</Timeout>
            <VerifySSL>true</VerifySSL>
          </BundleResolver>
           <!-- Use other anchors and trust relationships you had already set up -->
          <ServiceResolver>
            <ClientSettings>
              <Url>http://localhost/ConfigService/CertificateService.svc/Anchors</Url>
            </ClientSettings>
            <CacheSettings>
              <Cache>true</Cache>
              <NegativeCache>true</NegativeCache>
              <CacheTTLSeconds>60</CacheTTLSeconds>
            </CacheSettings>
          </ServiceResolver>
        </Settings>
      </Definition>
    </PluginResolver>
  </Anchors>



Cryptography

/SmtpAgentConfig/Cryptographer
Child
Required
Description
DefaultEncryption
N
Options:
  • RSA_3DES,
  • AES128
  • AES192
  • AES256.

Default: AES128
DefaultDigest
N
Options:
  • SHA1
  • SHA256
  • SHA384
  • SHA512

Default: SHA1

...
  <Cryptographer>
    <DefaultEncryption>AES128</DefaultEncryption>
    <DefaultDigest>SHA1</DefaultDigest>
  </Cryptographer>


Trust Model

These settings control how the Gateway verifies X509 certificates.

/SmtpAgentConfig/Trust
Child
Required
Description
MaxIssuerChainLength
N
Resolve the issuance chain for each cert (including intermediaries) to this depth.
Default: 4
RevocationCheckMode
N
Controls how certificate revocations are checked.

Options:
  • NoCheck
  • Online
  • Offline

Default: Online.

See MSDN: X509RevocationMode .
See How to enabled CRL support on Windows with the .NET RI
Timeout
N
When doing revocation checking, the Chain Builder will attempt to download CRL (revocation lists) from their source Urls.
This sets a Timeout used by the chain builder when downloading CRLs.

Default: System defined (Windows). Recommeded.

The trust section can be omitted from the config file and all defaults will be used. Here is an example Trust section.

...
  <Trust>
    <MaxIssuerChainLength>4</MaxIssuerChainLength>
    <RevocationCheckMode>Online</RevocationCheckMode>
    <Timeout>2000</Timeout>
  </Trust>


Notifications (Acks)

You can configure the gateway to automatically issue processed MDN notifications for those incoming messages that request them.

As of version 1.1.0.0 MDN notifications can be configured to follow the Implementation Guid for Delivery Notifications in Direct
DSN codes defined by the monitor service can be found in DSN Notification CSharp


/SmtpAgentConfig/Notifications
Child
Required
Description
AutoResponse
N
Automatically send acks - if requested (using MDN request header).
Default: false
AlwaysAck
N
Send Acks even if not requested. Note: Acks will be sent only if AutoResponse is true.
Text
N
Standard plain text explanation sent with each ack.
ProductName
N
The name of this product. Used to build the Reporting-UA header for an MDN.
AutoDsnFailureCreation
N
Always or TimelyAndReliable. The TimelyAndReliable option is default. TimelyAndReliable option indicates edge client must request delivery notifications. DSN style notifications include failure to resolve public certificates, failure to chain up to a trust anchor, failure to receive a timely processed MDN, and failure to receive a timely dispatched MDN. To receive DSNs for failed public certificate resolution and trust anchor chaining AutoDsnFailureCreation must be either set to Always. Or set to TimelyAndReliable and the sending client has requested delivery notification by including the following header. Disposition-Notification-Options: X-DIRECT-FINAL-DESTINATION-DELIVERY=optional,true
To also get DSN timeout messages the MDN Monitor Service must be installed and configured. See Monitor Server Settings and MDN Monitor
Lastly DSN messages will be coming from Postmaster at the same domain as the sender. To receive message from yourself install your trust anchor and set EnabledRelay to true in the InternalMessage setting.
GatewayIsDestination
N
true or false. Default false. When true gateway will a generate dispatched MDN. When false final destination is responsible for dispatched MDN if requested. See Implementation Guid for Delivery Notifications in Direct to request a dispatched mdn

The AutoDsnFailurCreation 1.1.0.0 feature list:
  • Compatible with 1.0.0.* gateway.
  • Notifies edge client of failures as DSN messages. Untrusted recipients will generate failed DSN messages if configured or requested. If not requested and not configured results will be the same as a V1 gateway. Note in V1 partial trusted recipient lists are delivered to trusted recipients without any negative notification. Careful analysis of the log files reveal the partial delivery. If all recipients are untrusted the message ends in the bad messages folder.

...
  <Notifications>
    <AutoResponse>true</AutoResponse>
    <AlwaysAck>true</AlwaysAck>
    <Text>Message Delivery Notification</Text>
    <GatewayIsDestination>true</GatewayIsDestination>
  </Notifications>


Routing


The gateway implements simple message routing based on an address's type.

All addresses maintained in the Config System (middle tier)can have an associated type for the address. You can set a route for each address type. Each route can have one or more receivers - the Gateway will automatically loadbalance over them.

/SmtpAgentConfig/IncomingRoutes
Child
Required
Description
Route
Y
One or more Routes

The Gateway supports two types of routes:
  • Folder Routes
  • Plugin Routes

Folder Routes

The Gateway places messages in destination folders/fileshares.

/SmtpAgentConfig/IncomingRoutes/Route
Child
Required
Description
AddressType
Y
Address Type (string)
CopyFolder
Y
Directory path

For redundancy and loadbalancing, you can associate multiple CopyFolders with a single route.

Plugin Routes

The Gateway creates an instance of a .NET Type in an Assembly you provide. It hands messages to this Type - which can do whatever it wants with it.

The type must implement IReceiver<ISmtpMessage>. See samples in code (csharp\gateway\smtpagent\SmtpMessageForwarder.cs) and in the smtpAgent.tests unit tests see HttpReceiver in the TestRouter.cs file.

/SmtpAgentConfig/IncomingRoutes/PluginRoute
Child
Required
Description
AddressType
Y
Address Type (string)
Receiver
Y
Contains the plugin receiver definition

Config Sample

  <IncomingRoutes>
    <Route>
      <AddressType>BANANA</AddressType>
      <CopyFolder>\\share1\drop\banana</CopyFolder>
      <CopyFolder>\\share2\drop\banana</CopyFolder>
    </Route>
    <Route>
      <AddressType>POTATO</AddressType>
      <CopyFolder>C:\drop\dest1</CopyFolder>
      <CopyFolder>C:\drop\dest2</CopyFolder>
      <CopyFolder>C:\drop\dest3</CopyFolder>
    </Route>
    <PluginRoute>
      <AddressType>SMTP</AddressType>
      <Receiver>
        <TypeName>Health.Direct.SmtpAgent.SmtpMessageForwarder, Health.Direct.SmtpAgent</TypeName>
        <Settings>
          <AddressType>SMTP</AddressType>
          <Server>foo.xyz</Server>
          <Port>33</Port>
        </Settings>
      </Receiver>
      <Receiver>
        <TypeName>Health.Direct.SmtpAgent.SmtpMessageForwarder, Health.Direct.SmtpAgent</TypeName>
        <Settings>
          <AddressType>SMTP</AddressType>
          <Server>bar.xyz</Server>
          <Port>39</Port>
        </Settings>
      </Receiver>
    </PluginRoute>
  </IncomingRoutes>

If a particular receiver fails for any reason, the router will automatically try one of the alternatives till success, or all alternatives are exhausted(the router will pick alternatives randomly).

Message Wrapping

Mail transport headers typically travel in the clear. To protect transport headers, the Gateway "wraps" messages.

__/SmtpAgentConfig
Child
Required
Description
WrapOutgoing
N
Boolean. Default: True. Automatically Wrap outgoing messages in message/rfc822 wrapper.
AllowNonWrappedIncoming
N
Boolean. Default: True. Accept messages that were not wrapped. True by default to allow for interop with S/MIME done by mail clients themselves - e.g. Thunderbird & Outlook.

Message Processing

These settings control how the messages are processed:
  • Outgoing Messages
  • Incoming Messages
  • Bad (Rejected) Messages
  • Internal Relay

You use settings to:
  • Control whether messages are actually relayed
  • For Debugging - whether a copy of the message is dropped in a local folder

Outgoing Messages

Outgoing messages are sent by THIS domain to other domains. Messages will be:
  • Signed
  • Encrypted

To actually have your email sent to the Internet, set EnableRelay to true.

/SmtpAgentConfig/Outgoing

Child
Required
Description
CopyFolder
N
Path to the folder where the gateway puts a copy of trusted outgoing messages (encrypted)

To stop copying messages, remove the CopyFolder element.
EnableRelay
N
true or false. If false, outgoing messages are not put on the wire. Default: true

...
  <ProcessOutgoing>
    <CopyFolder>C:\inetpub\mailroot\outgoing</CopyFolder>
    <EnableRelay>false</EnableRelay>
  </ProcessOutgoing>

Incoming Messages

Incoming messages are sent by other domains TO this one. Messages will be:
  • Decrypted
  • Have Signatures Validated

If the Gateway accepts a message AND Relay is Enabled:
  • It will attempt to Route the message (see Routing section above).
  • If no Route matches, the decrypted message will be returned to SMTP Server, which will proceed with its pipeline.
    • The SMTP Pipeline could have a registered persistance store such as POP3 or the standard "Drop" folder
    • OR, the server may have been set up to forward messages to a Smart Host

/SmtpAgentConfig/Incoming

Child
Required
Description
CopyFolder
N
Path to the folder where the gateway places a copy trusted incoming messsages (decrypted)

To stop copying messages, remove the CopyFolder element.
EnableRelay
N
true or false. If false, incoming messages are not put on the wire. Default: true

...
  <ProcessIncoming>
    <CopyFolder>C:\inetpub\mailroot\incoming</CopyFolder>
    <EnableRelay>false</EnableRelay>
  </ProcessIncoming>

Bad Messages

Bad messages are messages the Gateway rejects. Reasons for the rejection could include:
  • Malformed/non-SMIME compliant messages
  • Encryption/Decryption failed
  • Signature creation/verification failed
  • Certificate Resolution failed - such as over DNS
  • Certs are un-trusted
  • Message is from an untrusted source
  • Target user address does not exist (in Config System)
  • Etc

You can save a copy of failed messages in a diagnostics folder.

/SmtpAgentConfig/BadMessage
Child
Required
Description
CopyFolder
N
Path to the folder where the gateway placed reject messages

To stop copying messages, remove the CopyFolder element.

...
  <BadMessage>
    <CopyFolder>C:\inetpub\mailroot\badMail</CopyFolder>
  </BadMessage>

Capturing Raw Messages

You can capture messages in the raw - outgoing and incoming - before the gateway processes them. This is very useful for debugging.

You should disable this option on production.

/SmtpAgentConfig/Raw
Child
Required
Description
CopyFolder
N
Path to the folder where the gateway placed every message

To stop copying messages, remove the CopyFolder element.
...
  <RawMessage>
    <CopyFolder>C:\inetpub\mailroot\raw</CopyFolder>
  </RawMessage>

Internal Relay

You typically setup the SMTP Gateway to run in front of your e-mail server. The gateway treats all messages originating from within the domain as outgoing messages.
Similarly, the gateway treats all messages sent by addresses in external domains as incoming. Incoming messages must be signed and ecrypted, or else the are automatically dropped.

In certain configurations, you may want to have the gateway also function as your email server. To do so, outgoing messages with recipients in locally managed domains must be looped back and reprocessed as incoming messages.
This option is especially useful for test and staging deployments. The gateway accomplishes this loopback by placing a copy of the outgoing message in the SMTP Server's pickup folder.

By default, the gateway will not allow internal message delivery.

When no address manager is configured and no routes configured, MDNs will only be issued if the EnableRelay flag is set.

/SmtpAgentConfig/InternalMessage

Child
Required
Description
CopyFolder
N
Path to the Smtp Server's pickup folder

To stop copying messages, remove the CopyFolder element
EnableRelay
N
true or false. Default: false

...
  <InternalMessage>
    <CopyFolder>C:\inetpub\mailroot\Pickup</CopyFolder>
    <EnableRelay>false</EnableRelay>
  </InternalMessage>

MDN Monitor

You can configure the gateway to track outgoing messages and incoming notifications.
In 1.1.0.0 a MdnMonitorWinSrv Windows service is added as an installation option. The service monitors tracked outgoing messages and correlated notifications. If a message is not delivered timely according to the Implementation Guid for Delivery Notifications in Direct, a failed delivery status notification will be sent to the outgoing message sender.

/SmtpAgentConfig/MdnMonitor
Child
Required
Description
Url
Y
Url of the Domain Service
MaxReceivedMessageSize
Y
In bytes. Default - no limit
Secure
N
Use Windows Authentication. Default - false
ReceiveTimeout
N
Seconds. How long to wait for a response. Default: 10 minutes (WCF)
SendTimeout
N
Seconds. How long to wait for request transmission. Default: 1 minute (WCF)
...
  <MdnMonitor>
    <Url>http://localhost:6692/MonitorService.svc/Dispositions</Url>
  </MdnMonitor>


Logging

The Gateway writes debug and status information to a log file.

You can configure the log file using a Log File Settings section.

You can use this configuration to set log levels as well as optionally bubble log data into the Event Log, where it can be monitored using SCOM/MOM packs.

You can also replace the logging mechanims with your own, by implementing Health.Direct.Common.Diagnostics.ILogger. You can plugin your implementation using

Auditing

The Gateway maintains an Audit Log of Accepted & Rejected messages, both inbound and outbound. It does so using an Auditor.

The Auditor is an object that implements the Health.Direct.Common.Diagnostics.IAuditor interface.

The default auditor writes to the Windows EventLog as shown in the configuration below.

You can customize Audit Log capture by implementing your own auditor. You do so by implementing
Health.Direct.Common.Diagnostics.IAuditor, and then changing the Gateway configuration file:

<SmtpAgentConfig>
...
  <Container>
    <Component>
      <Service>Health.Direct.Common.Diagnostics.IAuditor, Health.Direct.Common</Service>
      <Type>Health.Direct.Common.Diagnostics.EventLogAuditor, Health.Direct.Common</Type>
      <Scope>Singleton</Scope>
    </Component>
  </Container>
...

In the sample above, the <Service> and <Type> tags specifies {FullTypeName, AssemblyName}