Skip to content

OpaqueMail Proxy Tutorial

Jump to bottom Edit New page
Bert Johnson edited this page Jul 1, 2016 · 3 revisions

It's easy to get started with the OpaqueMail Proxy.

General

  1. Downloading the latest version
  2. Using the settings client
  3. Sample settings file

Proxying SMTP

  1. Signing outbound messages
  2. Encrypting outbound messages
  3. Removing S/MIME from proxied outgoing messages
  4. Filtering outbound messages to certain IP addresses
  5. Overriding the sender value for outbound messages
  6. Adding recipients to outbound messages
  7. Adding signatures to outbound messages
  8. Authenticating SMTP connections
  9. Redirecting email ports
  10. Debugging email development
  11. Exporting all outbound messages to .eml files

Proxying IMAP

  1. Filtering incoming messages to certain IP addresses
  2. Importing S/MIME certificates from incoming messages
  3. Overriding authentication
  4. Redirecting email ports
  5. Debugging email development
  6. Exporting all inbound messages to .eml files

Proxying POP3

  1. Filtering incoming messages to certain IP addresses
  2. Importing S/MIME certificates from incoming messages
  3. Overriding authentication
  4. Redirecting email ports
  5. Debugging email development
  6. Exporting all inbound messages to .eml files

##General

Downloading the latest version

The latest release of the OpaqueMail Proxy is always available on GitHub from https://github.com/bertjohnson/OpaqueMail/zipball/master.

For added security, the file's MD5 and SHA1 checksums can be verified on the OpaqueMail.org homepage.

The OpaqueMail Proxy requires Microsoft .NET 4.5.

The OpaqueMail Proxy runs as a Windows service and is configured through an XML file called "OpaqueMail.Proxy.xml". This file can be edited manually or through the settings client below.

2. Using the settings client

The OpaqueMail Proxy settings client (named OpaqueMail.ProxySettings.exe) is used to install the Windows service and create the initial proxy settings file (OpaqueMail.Proxy.xml).

Upon launching, the "OpaqueMail Proxy" Windows service will automatically be installed and started.

The settings client is divided into four tabs, with a "Save Settings" button on the bottom. Clicking "Save Settings" will overwrite OpaqueMail.Proxy.xml with the chosen settings. Hitting the "F5" key will reload the settings client to reflect any changes made.

####A. View the "About OpaqueMail Proxy" tab

The first tab of the OpaqueMail Proxy settings tab covers an overview of what the proxy does and how to manage its settings, similar to this page.

####B. Select email accounts to protect via the "Accounts" tab

The "Select E-mail Accounts" tab is used to select which local accounts should be updated to use this OpaqueMail Proxy installation. Upon loading or hitting "F5", the settings client automatically scans for accounts from the following locations:

Microsoft Outlook

Settings are found in the Windows registry under "Software\Microsoft\Office[VERSION]\Outlook\Profiles\Outlook\9375CFF0413111d3B88A00104B2A6676", where "[VERSION]" is a value between 8.0 and 15.0 depending on which version of Office you run.

Mozilla Thunderbird

Settings are found by looking at "prefs.js" files in the "ROAMINGAPPDATA\Thunderbird\Profiles" folder.

Opera Mail

Settings are found by looking at "LOCALAPPDATA\Opera Mail\Opera Mail\mail\accounts.ini".

Windows Live Mail

Settings are found by looking at files with the ".oeaccount" extension in the "LOCALAPPDATA\Microsoft\Windows Live Mail" folder.

####C. Choose S/MIME and certificate options under the "Certificates" tab##

The "Certificates" tab provides an overview of how certificates can be obtained and used, as well as selections for controlling S/MIME behavior.

The "S/MIME operations" drop-down provides choices for "Apply no S/MIME protection", "Sign messages only", "Encrypt messages only", and "Sign and encrypt messages (Recommended)". The "S/MIME protection mode" drop-down provides the choices of "Best effort: try to protect, but allow unprotected mail" and "Require exact settings".

####D. Review the "Other Options" tab

The final tab provides firewall and signature options. By default, the OpaqueMail Proxy only accepts connection from the localhost (e.g. an IP on the current machine or the loopback address 127.0.0.1).

3. Sample settings file

The following code block shows all available settings for the OpaqueMail proxy. One SMTP proxy, one IMAP proxy, and one POP3 proxy are included. Additional proxies could be defined by changing the ServiceCount property and adding additional Service blocks.

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- IP addresses to accept connections from.  Delete or set value to "*" to accept connections from any IP. -->
      <!-- Individual IPs can be specified, separated by commas, or ranges can be specified.  The "*" wildcard character is supported. -->
      <!-- By default, connections are only accepted from the localhost. -->
      <AcceptedIPs>0.0.0.0</AcceptedIPs>
 
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Username used when authenticating to the remote SMTP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerUsername></RemoteServerUsername>
      <!-- (Optional) Password used when authenticating to the remote SMTP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerPassword></RemoteServerPassword>
      
      <!-- (Optional) "From" address for all sent messages.  When supplied, it will override any values sent from the client. -->
      <From></From>
      <!-- (Optional) "To" address for all sent messages.  When supplied, it will add the recipient(s) to any included with the original message. -->
      <To></To>
      <!-- (Optional) "CC" address for all sent messages.  When supplied, it will add the recipient(s) to any included with the original message. -->
      <CC></CC>
      <!-- (Optional) "BCC" address for all sent messages.  When supplied, it will add the recipient(s) to any included with the original message. -->
      <BCC></BCC>
      <!-- (Optional) Signature to add to the end of each sent message. -->
      <Signature></Signature>
 
      <!-- Send e-mail reminders when a signing certificate is due to expire within 30 days. -->
      <SendCertificateReminders>True</SendCertificateReminders>
 
      <!-- Whether all outgoing messages require the S/MIME settings specified below. -->
      <!-- When set to "RequireExactSettings", any messages that can't be signed or encrypted will be dropped, unsent. -->
      <!-- When set to "BestEffort", OpaqueMail Proxy will attempt to sign and/or encrypt messages but still forward any that can't be. -->
      <SMIMESettingsMode>BestEffort</SMIMESettingsMode>
 
      <!-- Whether to sign the e-mail.  When true, signing is the first S/MIME operation. -->
      <SMIMESign>True</SMIMESign>
      <!-- Whether to encrypt the e-mail's envelope.  When SmimeSign is true, encryption is the second S/MIME operation. -->
      <SMIMEEncrypt>True</SMIMEEncrypt>
      <!-- Triple-wrap the e-mail by signing, then encrypting the envelope, then signing the encrypted envelope. -->
      <SMIMETripleWrap>True</SMIMETripleWrap>
 
      <!-- Remove envelope encryption and signatures from passed-in messages.  If true and SmimeSigned or SmimeEncryptEnvelope is also true, new S/MIME operations will be applied. -->
      <SMIMERemovePreviousOperations>True</SMIMERemovePreviousOperations>
 
      <!-- (Optional) Location where all outbound messages are saved as EML files. -->
      <ExportDirectory></ExportDirectory>
 
      <!-- Where log files should be stored, if any.  Leave blank to avoid logging. -->
      <!-- Date and instance variables can be encased in angle braces.  For example, "Logs\SMTPProxy{#}-{yyyy-MM-dd}.log". -->
      <LogFile>Logs\SMTPProxy{#}-{yyyy-MM-dd}.log</LogFile>
      <!-- Proxy logging level, determining how much information is logged.  Possible values: None, Critical, Error, Warning, Information, Verbose, Raw -->
      <LogLevel>Verbose</LogLevel>
    </Service1>
  </SMTP>
  <IMAP>
    <!-- The number of IMAP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- IP addresses to accept connections from.  Delete or set value to "*" to accept connections from any IP. -->
      <!-- Individual IPs can be specified, separated by commas, or ranges can be specified.  The "*" wildcard character is supported. -->
      <!-- By default, connections are only accepted from the localhost. -->
      <AcceptedIPs>0.0.0.0</AcceptedIPs>
 
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>993</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote IMAP server hostname to connect to.  Common values: imap.gmail.com, imap.mail.yahoo.com -->
      <RemoteServerHostName>imap.gmail.com</RemoteServerHostName>
      <!-- Remote IMAP server port to connect to.  993 is recommended, but 143 may be required. -->
      <RemoteServerPort>993</RemoteServerPort>
      <!-- Whether the remote IMAP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Username used when authenticating to the remote IMAP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerUsername></RemoteServerUsername>
      <!-- (Optional) Password used when authenticating to the remote IMAP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerPassword></RemoteServerPassword>
 
      <!-- (Optional) Location where all incoming messages are saved as EML files. -->
      <ExportDirectory></ExportDirectory>
 
      <!-- Where log files should be stored, if any.  Leave blank to avoid logging. -->
      <!-- Date and instance variables can be encased in angle braces.  For example, "Logs\IMAPProxy{#}-{yyyy-MM-dd}.log". -->
      <LogFile>Logs\IMAPProxy{#}-{yyyy-MM-dd}.log</LogFile>
      <!-- Proxy logging level, determining how much information is logged.  Possible values: None, Critical, Error, Warning, Information, Verbose, Raw -->
      <LogLevel>Verbose</LogLevel>
    </Service1>
  </IMAP>
  <POP3>
    <!-- The number of POP3 proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- IP addresses to accept connections from.  Delete or set value to "*" to accept connections from any IP. -->
      <!-- Individual IPs can be specified, separated by commas, or ranges can be specified.  The "*" wildcard character is supported. -->
      <!-- By default, connections are only accepted from the localhost. -->
      <AcceptedIPs>0.0.0.0</AcceptedIPs>
 
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>995</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote POP3 server hostname to connect to.  Common values: pop.gmail.com, pop3.live.com, pop.mail.yahoo.com -->
      <RemoteServerHostName>pop.gmail.com</RemoteServerHostName>
      <!-- Remote POP3 server port to connect to.  995 is recommended, but 110 may be required. -->
      <RemoteServerPort>995</RemoteServerPort>
      <!-- Whether the remote POP3 server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Username used when authenticating to the remote POP3 server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerUsername></RemoteServerUsername>
      <!-- (Optional) Password used when authenticating to the remote POP3 server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerPassword></RemoteServerPassword>
 
      <!-- (Optional) Location where all incoming messages are saved as EML files. -->
      <ExportDirectory></ExportDirectory>
      
      <!-- Where log files should be stored, if any.  Leave blank to avoid logging. -->
      <!-- Date and instance variables can be encased in angle braces.  For example, "Logs\POP3Proxy{#}-{yyyy-MM-dd}.log". -->
      <LogFile>Logs\POP3Proxy{#}-{yyyy-MM-dd}.log</LogFile>
      <!-- Proxy logging level, determining how much information is logged.  Possible values: None, Critical, Error, Warning, Information, Verbose, Raw -->
      <LogLevel>Verbose</LogLevel>
    </Service1>
  </POP3>
</Settings>

##Proxying SMTP:

The Simple Mail Transfer Protocol (SMTP) is the ubiquitous standard for sending email. The OpaqueMail Proxy offers myriad options to make SMTP more flexible, from simply adding authentication to adding encryption and logging.

###1. Signing outbound messages

The first steps in ensuring integrity and non-repudiation of messages is signing outbound email. Setting up S/MIME signing with the OpaqueMail Proxy is easy. The proxy can either use existing certificates or generate its own self-signed certificates.

To install your own certificates, import them into the Windows "Local Machine" store. In order to be used for S/MIME operations, private keys will need to be imported. The OpaqueMail Proxy attempts to match certificates based on their subject names, either starting with "E=" or CN=".

If the proxy is configured to sign outbound messages via the <SMIMESign/> property, but a sender's certificate can't be found, a new certificate will automatically be generated and stored in the Windows certificate store.

If the <SendCertificateReminders/> element is set to "True", the OpaqueMail Proxy will email notifications 30 days before a used signing certificate is set to expire.

Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail with S/MIME signatures:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- Send e-mail reminders when a signing certificate is due to expire within 30 days. -->
      <SendCertificateReminders>True</SendCertificateReminders>
 
      <!-- Whether to sign the e-mail.  When true, signing is the first S/MIME operation. -->
      <SMIMESign>True</SMIMESign>
    </Service1>
  </SMTP>
</Settings>

###2. Encrypting outbound messages

When using S/MIME, messages are usually encrypted in addition to being signed.

In order to encrypt a message, you must know the public key of each recipient. Most email clients require manual installation of other users' public keys, which can be cumbersome. To assist with that, the OpaqueMail Proxy's IMAP and POP3 configurations support automatically importing all received public keys.

To specify outbound messages should be encrypted, the <SMIMEEncrypt/> value is set to "True", similar to <SMIMESign/>. For added protection, messages can be "triple-wrapped", meaning they're first digitally signed, then encrypted, and finally signed again as authentication. To configure triple-wrapping, set the <SMIMETriplWrap/> property.

Because we can't encrypt messages to recipients who don't have public keys (or who have unknown public keys), we need to determine what to do in that situation. The <SMIMESettingsMode/> property has two values to determine proxy behavior. When set to "BestEffort", OpaqueMail Proxy will attempt to encrypt messages but still forward any that can't be encrypted. When set to "RequireExactSettings", encrypted messages will be allowed through while anything insecure will be blocked.

Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail with S/MIME signing and encryption:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- Send e-mail reminders when a signing certificate is due to expire within 30 days. -->
      <SendCertificateReminders>True</SendCertificateReminders>
 
      <!-- Whether all outgoing messages require the S/MIME settings specified below. -->
      <!-- When set to "RequireExactSettings", any messages that can't be signed or encrypted will be dropped, unsent. -->
      <!-- When set to "BestEffort", OpaqueMail Proxy will attempt to sign and/or encrypt messages but still forward any that can't be. -->
      <SMIMESettingsMode>BestEffort</SMIMESettingsMode>
 
      <!-- Whether to sign the e-mail.  When true, signing is the first S/MIME operation. -->
      <SMIMESign>True</SMIMESign>
      <!-- Whether to encrypt the e-mail's envelope.  When SmimeSign is true, encryption is the second S/MIME operation. -->
      <SMIMEEncrypt>False</SMIMEEncrypt>
      <!-- Triple-wrap the e-mail by signing, then encrypting the envelope, then signing the encrypted envelope. -->
      <SMIMETripleWrap>False</SMIMETripleWrap>
    </Service1>
  </SMTP>
</Settings>

###3. Removing S/MIME from proxied outgoing messages

Some email clients fail to implement S/MIME properly, so it may be useful to have the OpaqueMail Proxy "undo" S/MIME operations and then optionally re-apply them correctly. For example, certain versions of Microsoft Outlook don't perform "detached signatures", meaning that the authenticity of sent messages can't be verified. It may be better to remove the signature Outlook attaches and override it with the OpaqueMail Proxy's signature.

To remove S/MIME operations from outgoing messages, set the <SMIMERemovePreviousOperations/> value to "True". If the <SMIMESign/> and <SMIMEEncrypt/> values are omitted, the forwarded message will then be sent in plaintext.

Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail, replacing any previous S/MIME signatures or encryption with new versions performed by OpaqueMail Proxy:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- Whether all outgoing messages require the S/MIME settings specified below. -->
      <!-- When set to "RequireExactSettings", any messages that can't be signed or encrypted will be dropped, unsent. -->
      <!-- When set to "BestEffort", OpaqueMail Proxy will attempt to sign and/or encrypt messages but still forward any that can't be. -->
      <SMIMESettingsMode>BestEffort</SMIMESettingsMode>
 
      <!-- Whether to sign the e-mail.  When true, signing is the first S/MIME operation. -->
      <SMIMESign>True</SMIMESign>
      <!-- Whether to encrypt the e-mail's envelope.  When SmimeSign is true, encryption is the second S/MIME operation. -->
      <SMIMEEncrypt>True</SMIMEEncrypt>
      <!-- Triple-wrap the e-mail by signing, then encrypting the envelope, then signing the encrypted envelope. -->
      <SMIMETripleWrap>True</SMIMETripleWrap>
 
      <!-- Remove envelope encryption and signatures from passed-in messages.  If true and SmimeSigned or SmimeEncryptEnvelope is also true, new S/MIME operations will be applied. -->
      <SMIMERemovePreviousOperations>True</SMIMERemovePreviousOperations>
 
    </Service1>
  </SMTP>
</Settings>

###4. Filtering incoming messages to certain IP addresses

SMTP traffic can be filtered via the OpaqueMail Proxy's <AcceptedIPs/> value. It serves as a whitelist, restricting traffic to local machine connections by default.

Accepted IP values can be added in a comma-separated list and the asterisk ("*") can be used as a wildcard character.

Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail, limiting connections to the 10.1.* address space or 192.168.1.101:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- IP addresses to accept connections from.  Delete or set value to "*" to accept connections from any IP. -->
      <!-- Individual IPs can be specified, separated by commas, or ranges can be specified.  The "*" wildcard character is supported. -->
      <!-- By default, connections are only accepted from the localhost. -->
      <AcceptedIPs>10.1.*,192.168.1.101</AcceptedIPs>
 
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </SMTP>
</Settings>

###5. Overriding the sender value for outbound messages

It's sometimes necessary to override the sender's name or e-mail address for outbound messages. This can be performed with the OpaqueMail Proxy's <From/> property. Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail, specifying all messages come from "dispatch@example.com":

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
      
      <!-- (Optional) "From" address for all sent messages.  When supplied, it will override any values sent from the client. -->
      <From>"Example Dispatch" &lt;dispatch@example.com&gt;</From>
    </Service1>
  </SMTP>
</Settings>

###6. Adding recipients to outbound messages

One or more recipients can be added to all outbound messages. These can be done as visible "To" and "CC" addresses or as hidden "BCC" addresses. This can be useful for augmenting hard-coded email address values or copying all messages to an archive.

Addresses are specifed via the <To/>, <CC/>, and <BCC/> properties. Values should be semicolon delimited.

Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail, copying "archive@example.com" on every message:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
      
      <!-- (Optional) "To" address for all sent messages.  When supplied, it will add the recipient(s) to any included with the original message. -->
      <To></To>
      <!-- (Optional) "CC" address for all sent messages.  When supplied, it will add the recipient(s) to any included with the original message. -->
      <CC></CC>
      <!-- (Optional) "BCC" address for all sent messages.  When supplied, it will add the recipient(s) to any included with the original message. -->
      <BCC>archive@example.com</BCC>
    </Service1>
  </SMTP>
</Settings>

###7. Adding signatures to outbound messages

The OpaqueMail Proxy can be used to add static signatures to all outbound messages using the <Signature/> element. In text/html messages, signatures will be inserted before the closing BODY tag. In text/plain messages, signatures are inserted at the end of the message.

Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail, adding a disclaimer to all messages:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Username used when authenticating to the remote SMTP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerUsername></RemoteServerUsername>
      <!-- (Optional) Password used when authenticating to the remote SMTP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerPassword></RemoteServerPassword>
      
      <!-- (Optional) Signature to add to the end of each sent message. -->
      <Signature>--&lt;p/&gt;
&lt;Disclaimer:&gt;&lt;p/&gt;
 
The contents of this message are for your eyes only.  We might be offering terrible advice and are not responsible for anything you attempt based on this message.</Signature>
    </Service1>
  </SMTP>
</Settings>

###8. Authenticating SMTP connections

Some older SMTP clients connect anonymously with no authentication, which is usually blocked to prevent spam. The OpaqueMail Proxy can add authentication to all outbound messages using the <RemoteServerUsername/> and <RemoteServerPassword/> properties.

When specified, the proxy will use "LOGIN" authentication for all outbound connections, ignoring any credentials passed from local clients.

Sample configuration file for a simple SMTP proxy that listens locally and forwards messages to Gmail with constrained authentication:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Username used when authenticating to the remote SMTP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerUsername>username@gmail.com</RemoteServerUsername>
      <!-- (Optional) Password used when authenticating to the remote SMTP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerPassword>Pass@word1</RemoteServerPassword>
      
    </Service1>
  </SMTP>

###9. Redirecting email ports

One of the simplest uses of the OpaqueMail Proxy is to redirect SMTP traffic to use different ports. This can be useful when a local client is hardcoded to use a specific port or not use TLS / SSL protection, but the remote server's settings have been changed.

Sample configuration file for a simple SMTP proxy that listens locally on port 25 and forwards messages to Gmail on port 587 with TLS / SSL protection:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>25</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>False</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </SMTP>
</Settings>

###10. Debugging email development

When developing email applications, it's vital to be able to trace network traffic. While tools like packet sniffers can be used, OpaqueMail Proxy simplifies debugging by offering real-time SMTP logs.

The <LogLevel/> setting determines what information is documented about each SMTP connection. Valid levels are "None" (for no logging), "Critical" (for tracking critical errors only), "Error" (for tracking all errors), "Warning" (for tracking all errors and warnings), "Information" (for documenting all errors, warnings, and connection information such as times connected and bytes transferred), "Verbose" (for tracking all of the above, plus exactly which SMTP verbs are transmitted), and "Verbatim" (which logs all SMTP traffic verbatim).

The "Verbose" and "Verbatim" values are useful for logging SMTP command flow and troubleshooting subtle connection problems. Traffic from the server-to-client is denoted with a "S: " prefix while traffic from the client-to-server is denoted with a "C: " prefix.

Log file storage can be specified via the <LogFile/> setting. By default, log files are stored relative to the current service path, but can be stored anywhere. Variables, such as date formatting, can be used to ensure log files are kept segmented (e.g. with one per day).

Sample configuration file for a simple SMTP proxy that listens locally on and forwards messages to Gmail, while saving all SMTP data to the "Logs" subfolder:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- Where log files should be stored, if any.  Leave blank to avoid logging. -->
      <!-- Date and instance variables can be encased in angle braces.  For example, "Logs\SMTPProxy{#}-{yyyy-MM-dd}.log". -->
      <LogFile>Logs\SMTPProxy{#}-{yyyy-MM-dd}.log</LogFile>
      <!-- Proxy logging level, determining how much information is logged.  Possible values: None, Critical, Error, Warning, Information, Verbose, Raw -->
      <LogLevel>Verbatim</LogLevel>
    </Service1>
  </SMTP>
</Settings>

###11. Exporting all outbound messages to .eml files

The OpaqueMail Proxy can be used to export all outbound messages to raw ".eml" files. This can be useful for debugging, archiving, migration, and compliance.

To specify where outbound messages are stored, set the <ExportDirectory/> property. If a message has a "Message-ID" header, that is used as its filename. Otherwise, a random GUID is used as its filename.

Sample configuration file for a simple SMTP proxy that listens locally on and forwards messages to Gmail, copying all messages to the "Sent" subfolder:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <SMTP>
    <!-- The number of SMTP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>587</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
      
      <!-- Remote SMTP server hostname to connect to.  Common values: smtp.gmail.com, smtp.live.com, smtp.mail.yahoo.com -->
      <RemoteServerHostName>smtp.gmail.com</RemoteServerHostName>
      <!-- Remote SMTP server port to connect to.  587 is recommended, but 465 or 25 may be required. -->
      <RemoteServerPort>587</RemoteServerPort>
      <!-- Whether the remote SMTP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Location where all outbound messages are saved as EML files. -->
      <ExportDirectory>Sent</ExportDirectory>
    </Service1>
  </SMTP>
</Settings>

###Proxying IMAP:

Internet Message Access Protocol (IMAP) is a common option for email query and retrieval. It offers more capabilities than POP3 and continues to evolve. IMAP is supported by most enterprise hosts. The OpaqueMail Proxy offers several options to simplify working with IMAP.

##1. Filtering incoming messages to certain IP addresses

IMAP traffic can be filtered via the OpaqueMail Proxy's <AcceptedIPs/> value. It serves as a whitelist, restricting traffic to local machine connections by default.

Accepted IP values can be added in a comma-separated list and the asterisk ("*") can be used as a wildcard character.

Sample configuration file for a simple IMAP proxy that listens locally and forwards messages to Gmail, limiting connections to the 10.1.* address space or 192.168.1.101:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <IMAP>
    <!-- The number of IMAP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- IP addresses to accept connections from.  Delete or set value to "*" to accept connections from any IP. -->
      <!-- Individual IPs can be specified, separated by commas, or ranges can be specified.  The "*" wildcard character is supported. -->
      <!-- By default, connections are only accepted from the localhost. -->
      <AcceptedIPs>10.1.*,192.1.168.110</AcceptedIPs>
 
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>993</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote IMAP server hostname to connect to.  Common values: imap.gmail.com, imap.mail.yahoo.com -->
      <RemoteServerHostName>imap.gmail.com</RemoteServerHostName>
      <!-- Remote IMAP server port to connect to.  993 is recommended, but 143 may be required. -->
      <RemoteServerPort>993</RemoteServerPort>
      <!-- Whether the remote IMAP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </IMAP>
</Settings>

###2. Importing S/MIME certificates from incoming messages

One of the primary purposes of the OpaqueMail Proxy is to import incoming S/MIME certificates. Most email clients have poor usability for working with certificates and require multiple steps to import certificates. The OpaqueMail Proxy simplifies the process by saving all valid certificates to the Windows Local Machine certificate store.

No special XML configuration is needed beyond an active IMAP proxy instance.

Sample configuration file for a simple IMAP proxy that listens locally and forwards messages to Gmail, automatically importing valid S/MIME certificates:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <IMAP>
    <!-- The number of IMAP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>993</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote IMAP server hostname to connect to.  Common values: imap.gmail.com, imap.mail.yahoo.com -->
      <RemoteServerHostName>imap.gmail.com</RemoteServerHostName>
      <!-- Remote IMAP server port to connect to.  993 is recommended, but 143 may be required. -->
      <RemoteServerPort>993</RemoteServerPort>
      <!-- Whether the remote IMAP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </IMAP>
</Settings>

###3. Overriding authentication

IMAP is typically an authenticated protocol. In order to benefit from most commands, servers require the user to sign in and select a mailbox.

For situations where IMAP authentication needs to be overridden (such as for hard-coded credentials), the OpaqueMail Proxy supports <RemoteServerUsername/> and <RemoteServerPassword/> properties.

Sample configuration file for a simple IMAP proxy that listens locally and forwards messages to Gmail, overriding all credentials with the following:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <IMAP>
    <!-- The number of IMAP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>993</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote IMAP server hostname to connect to.  Common values: imap.gmail.com, imap.mail.yahoo.com -->
      <RemoteServerHostName>imap.gmail.com</RemoteServerHostName>
      <!-- Remote IMAP server port to connect to.  993 is recommended, but 143 may be required. -->
      <RemoteServerPort>993</RemoteServerPort>
      <!-- Whether the remote IMAP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Username used when authenticating to the remote IMAP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerUsername>username@gmail.com</RemoteServerUsername>
      <!-- (Optional) Password used when authenticating to the remote IMAP server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerPassword>Pass@word1</RemoteServerPassword>
    </Service1>
  </IMAP>
</Settings>

###4. Redirecting email ports

One of the simplest uses of the OpaqueMail Proxy is to redirect IMAP traffic to use different ports. This can be useful when a local client is hardcoded to use a specific port or not use TLS / SSL protection, but the remote server's settings have been changed.

Sample configuration file for a simple IMAP proxy that listens locally on port 1001 and forwards traffic to Gmail on port 993 with TLS / SSL protection:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <IMAP>
    <!-- The number of IMAP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>1001</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>False</LocalEnableSSL>
 
      <!-- Remote IMAP server hostname to connect to.  Common values: imap.gmail.com, imap.mail.yahoo.com -->
      <RemoteServerHostName>imap.gmail.com</RemoteServerHostName>
      <!-- Remote IMAP server port to connect to.  993 is recommended, but 143 may be required. -->
      <RemoteServerPort>993</RemoteServerPort>
      <!-- Whether the remote IMAP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </IMAP>
</Settings>

###5. Debugging email development

When developing email applications, it's vital to be able to trace network traffic. While tools like packet sniffers can be used, OpaqueMail Proxy simplifies debugging by offering real-time IMAP logs.

The <LogLevel/> setting determines what information is documented about each IMAP connection. Valid levels are "None" (for no logging), "Critical" (for tracking critical errors only), "Error" (for tracking all errors), "Warning" (for tracking all errors and warnings), "Information" (for documenting all errors, warnings, and connection information such as times connected and bytes transferred), "Verbose" (for tracking all of the above, plus exactly which IMAP verbs are transmitted), and "Verbatim" (which logs all IMAP traffic verbatim).

The "Verbose" and "Verbatim" values are useful for logging IMAP command flow and troubleshooting subtle connection problems. Traffic from the server-to-client is denoted with a "S: " prefix while traffic from the client-to-server is denoted with a "C: " prefix.

Log file storage can be specified via the <LogFile/> setting. By default, log files are stored relative to the current service path, but can be stored anywhere. Variables, such as date formatting, can be used to ensure log files are kept segmented (e.g. with one per day).

Sample configuration file for a simple IMAP proxy that listens locally on and forwards messages to Gmail, while saving all IMAP data to the "Logs" subfolder:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <IMAP>
    <!-- The number of IMAP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>993</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote IMAP server hostname to connect to.  Common values: imap.gmail.com, imap.mail.yahoo.com -->
      <RemoteServerHostName>imap.gmail.com</RemoteServerHostName>
      <!-- Remote IMAP server port to connect to.  993 is recommended, but 143 may be required. -->
      <RemoteServerPort>993</RemoteServerPort>
      <!-- Whether the remote IMAP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- Where log files should be stored, if any.  Leave blank to avoid logging. -->
      <!-- Date and instance variables can be encased in angle braces.  For example, "Logs\IMAPProxy{#}-{yyyy-MM-dd}.log". -->
      <LogFile>Logs\IMAPProxy{#}-{yyyy-MM-dd}.log</LogFile>
      <!-- Proxy logging level, determining how much information is logged.  Possible values: None, Critical, Error, Warning, Information, Verbose, Raw -->
      <LogLevel>Verbatim</LogLevel>
    </Service1>
  </IMAP>
</Settings>

###6. Exporting all inbound messages to .eml files

The OpaqueMail Proxy can be used to export all received messages to raw ".eml" files. This can be useful for debugging, archiving, migration, and compliance.

To specify where incoming messages are stored, set the <ExportDirectory/> property. If a message has a "Message-ID" header, that is used as its filename. Otherwise, a random GUID is used as its filename.

Sample configuration file for a simple IMAP proxy that listens locally and forwards traffic to Gmail, copying all received messages to the "Received" subfolder:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <IMAP>
    <!-- The number of IMAP proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>993</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote IMAP server hostname to connect to.  Common values: imap.gmail.com, imap.mail.yahoo.com -->
      <RemoteServerHostName>imap.gmail.com</RemoteServerHostName>
      <!-- Remote IMAP server port to connect to.  993 is recommended, but 143 may be required. -->
      <RemoteServerPort>993</RemoteServerPort>
      <!-- Whether the remote IMAP server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Location where all incoming messages are saved as EML files. -->
      <ExportDirectory>Received</ExportDirectory>
    </Service1>
  </IMAP>
</Settings>

##Proxying POP3:

The Post Office Protocol version 3 (POP3) is the simplest mechanism for retrieving email. It doesn't feature as much functionality as IMAP, but it's supported by the vast majority of email hosts.

###1. Filtering incoming messages to certain IP addresses

POP3 traffic can be filtered via the OpaqueMail Proxy's <AcceptedIPs/> value. It serves as a whitelist, restricting traffic to local machine connections by default.

Accepted IP values can be added in a comma-separated list and the asterisk ("*") can be used as a wildcard character.

Sample configuration file for a simple POP3 proxy that listens locally and forwards messages to Gmail, limiting connections to the 10.1.* address space or 192.168.1.101:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <POP3>
    <!-- The number of POP3 proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- IP addresses to accept connections from.  Delete or set value to "*" to accept connections from any IP. -->
      <!-- Individual IPs can be specified, separated by commas, or ranges can be specified.  The "*" wildcard character is supported. -->
      <!-- By default, connections are only accepted from the localhost. -->
      <AcceptedIPs>10.1.*,192.1.168.110</AcceptedIPs>
 
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>995</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote POP3 server hostname to connect to.  Common values: pop.gmail.com, pop3.mail.yahoo.com -->
      <RemoteServerHostName>pop.gmail.com</RemoteServerHostName>
      <!-- Remote POP3 server port to connect to.  995 is recommended, but 110 may be required. -->
      <RemoteServerPort>995</RemoteServerPort>
      <!-- Whether the remote POP3 server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </POP3>
</Settings>

###2. Importing S/MIME certificates from incoming messages

One of the primary purposes of the OpaqueMail Proxy is to import incoming S/MIME certificates. Most email clients have poor usability for working with certificates and require multiple steps to import certificates. The OpaqueMail Proxy simplifies the process by saving all valid certificates to the Windows Local Machine certificate store.

No special XML configuration is needed beyond an active POP3 proxy instance.

Sample configuration file for a simple POP3 proxy that listens locally and forwards messages to Gmail, automatically importing valid S/MIME certificates:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <POP3>
    <!-- The number of POP3 proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>995</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote POP3 server hostname to connect to.  Common values: pop.gmail.com, pop3.mail.yahoo.com -->
      <RemoteServerHostName>pop.gmail.com</RemoteServerHostName>
      <!-- Remote POP3 server port to connect to.  995 is recommended, but 110 may be required. -->
      <RemoteServerPort>995</RemoteServerPort>
      <!-- Whether the remote POP3 server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </POP3>
</Settings>

###3. Overriding authentication

POP3 is typically an authenticated protocol. In order to benefit from most commands, servers require the user to sign in and select a mailbox.

For situations where POP3 authentication needs to be overridden (such as for hard-coded credentials), the OpaqueMail Proxy supports <RemoteServerUsername/> and <RemoteServerPassword/> properties.

Sample configuration file for a simple POP3 proxy that listens locally and forwards messages to Gmail, overriding all credentials with the following:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <POP3>
    <!-- The number of POP3 proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>995</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote POP3 server hostname to connect to.  Common values: pop.gmail.com, pop3.mail.yahoo.com -->
      <RemoteServerHostName>pop.gmail.com</RemoteServerHostName>
      <!-- Remote POP3 server port to connect to.  995 is recommended, but 110 may be required. -->
      <RemoteServerPort>995</RemoteServerPort>
      <!-- Whether the remote POP3 server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Username used when authenticating to the remote POP3 server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerUsername>username@gmail.com</RemoteServerUsername>
      <!-- (Optional) Password used when authenticating to the remote POP3 server.  When supplied, it will override any values sent from the client. -->
      <RemoteServerPassword>Pass@word1</RemoteServerPassword>
    </Service1>
  </POP3>
</Settings>

###4. Redirecting email ports

One of the simplest uses of the OpaqueMail Proxy is to redirect POP3 traffic to use different ports. This can be useful when a local client is hardcoded to use a specific port or not use TLS / SSL protection, but the remote server's settings have been changed.

Sample configuration file for a simple POP3 proxy that listens locally on port 1001 and forwards traffic to Gmail on port 995 with TLS / SSL protection:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <POP3>
    <!-- The number of POP3 proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>1001</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>False</LocalEnableSSL>
 
      <!-- Remote POP3 server hostname to connect to.  Common values: pop.gmail.com, pop3.mail.yahoo.com -->
      <RemoteServerHostName>pop.gmail.com</RemoteServerHostName>
      <!-- Remote POP3 server port to connect to.  995 is recommended, but 110 may be required. -->
      <RemoteServerPort>995</RemoteServerPort>
      <!-- Whether the remote POP3 server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
    </Service1>
  </POP3>
</Settings>

###5. Debugging email development

When developing email applications, it's vital to be able to trace network traffic. While tools like packet sniffers can be used, OpaqueMail Proxy simplifies debugging by offering real-time POP3 logs.

The <LogLevel/> setting determines what information is documented about each POP3 connection. Valid levels are "None" (for no logging), "Critical" (for tracking critical errors only), "Error" (for tracking all errors), "Warning" (for tracking all errors and warnings), "Information" (for documenting all errors, warnings, and connection information such as times connected and bytes transferred), "Verbose" (for tracking all of the above, plus exactly which POP3 verbs are transmitted), and "Verbatim" (which logs all POP3 traffic verbatim).

The "Verbose" and "Verbatim" values are useful for logging POP3 command flow and troubleshooting subtle connection problems. Traffic from the server-to-client is denoted with a "S: " prefix while traffic from the client-to-server is denoted with a "C: " prefix.

Log file storage can be specified via the <LogFile/> setting. By default, log files are stored relative to the current service path, but can be stored anywhere. Variables, such as date formatting, can be used to ensure log files are kept segmented (e.g. with one per day).

Sample configuration file for a simple POP3 proxy that listens locally on and forwards messages to Gmail, while saving all POP3 data to the "Logs" subfolder:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <POP3>
    <!-- The number of POP3 proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>995</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote POP3 server hostname to connect to.  Common values: pop.gmail.com, pop3.mail.yahoo.com -->
      <RemoteServerHostName>pop.gmail.com</RemoteServerHostName>
      <!-- Remote POP3 server port to connect to.  995 is recommended, but 110 may be required. -->
      <RemoteServerPort>995</RemoteServerPort>
      <!-- Whether the remote POP3 server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- Where log files should be stored, if any.  Leave blank to avoid logging. -->
      <!-- Date and instance variables can be encased in angle braces.  For example, "Logs\POP3Proxy{#}-{yyyy-MM-dd}.log". -->
      <LogFile>Logs\POP3Proxy{#}-{yyyy-MM-dd}.log</LogFile>
      <!-- Proxy logging level, determining how much information is logged.  Possible values: None, Critical, Error, Warning, Information, Verbose, Raw -->
      <LogLevel>Verbatim</LogLevel>
    </Service1>
  </POP3>
</Settings>

###6. Exporting all inbound messages to .eml files

The OpaqueMail Proxy can be used to export all received messages to raw ".eml" files. This can be useful for debugging, archiving, migration, and compliance.

To specify where incoming messages are stored, set the <ExportDirectory/> property. If a message has a "Message-ID" header, that is used as its filename. Otherwise, a random GUID is used as its filename.

Sample configuration file for a simple POP3 proxy that listens locally and forwards traffic to Gmail, copying all received messages to the "Received" subfolder:

<?xml version="1.0" encoding="utf-8" ?>
<Settings>
  <POP3>
    <!-- The number of POP3 proxy services to run.  Each proxy's settings will be outlined in subsequent Service blocks. -->
    <ServiceCount>1</ServiceCount>
    <Service1>
      <!-- Local IP address to listen on.  "Any" means listen on all IPs. -->
      <LocalIPAddress>Any</LocalIPAddress>
      <!-- Local port to listen on. -->
      <LocalPort>995</LocalPort>
      <!-- Whether local connections support TLS/SSL protection. -->
      <LocalEnableSSL>True</LocalEnableSSL>
 
      <!-- Remote POP3 server hostname to connect to.  Common values: pop.gmail.com, pop3.mail.yahoo.com -->
      <RemoteServerHostName>pop.gmail.com</RemoteServerHostName>
      <!-- Remote POP3 server port to connect to.  995 is recommended, but 110 may be required. -->
      <RemoteServerPort>995</RemoteServerPort>
      <!-- Whether the remote POP3 server supports TLS/SSL protection. -->
      <RemoteServerEnableSSL>True</RemoteServerEnableSSL>
 
      <!-- (Optional) Location where all incoming messages are saved as EML files. -->
      <ExportDirectory>Received</ExportDirectory>
    </Service1>
  </POP3>
</Settings>
Add a custom footer
Add a custom sidebar
Clone this wiki locally