Troubleshooting Sugar Email Archiving (SNIP) Activation

Overview

With Sugar Email Archiving (a.k.a. SNIP), messages sent to a special email address are automatically archived and linked to corresponding Sugar records. This allows for archiving from any email client without the use of a plugin or other syncing process. This article provides troubleshooting guidance to resolve potential issues that may be encountered during activation.

For help activating the service, refer to the Email documentation in the Administration Guide. For information about using the service, refer to the Emails documentation in the Application Guide.

Symptoms

An error is displayed while attempting to activate the Sugar Email Archiving service.

Resolution

For activation problems, please check the following:

Uniquely Enabled

Email Archiving can be enabled for multiple instances per license key, but each instance must be registered independently and receive its own, unique email address. When cloning an instance which uses Email Archiving, the clone will initially display as having the service enabled, but Email Archiving will not function for the clone. You must disable then re-enable Email Archiving on the clone in order to generate an email address unique to the instance and allow the instance to begin using the service. This can be performed via Admin > Email Archiving as described in the Email documentation.

On-Site Instance Accessibility

Our Email Archiving servers can only work with your instance when it may be reached over the internet. Please see the Configuring IP Addresses, Ports, and Domains article for IP addresses.

Site URL Configuration

For on-site instances, please make sure that the site_url specified in your config.php is set correctly. This site_url value must match the publicly-accessible URL.

Firewalls

For on-site instances, certain firewall setups may block the activation request. Try temporarily disabling the firewall and attempt the activation again.

ModSecurity Firewall

If your organization uses the ModSecurity web-application firewall (WAF), you likely abide by attack-detection rules that block certain user agents for security purposes. The Sugar Email Archiving server will contact your Sugar instance via the "python" user agent. Contact your network administrator to confirm that your ModSecurity settings are not blocking the user agent called "python" from connecting.

Reverse-Proxy Configurations

In most network infrastructures, a reverse proxy is needed to triage requests from the Internet to the appropriate places. For example, when an employee sends a message to the SNIP email address, Sugar's Email Archiving server will request permission from your network to import the email message into your Sugar instance. This request is typically handled by your network via reverse-proxy methods. 

When Apache is used as a reverse proxy, please confirm the following:

• The virtual host configuration that is serving your Sugar instance should contain the following line: SetEnvIf X-Forwarded-Proto https HTTPS=on
• The virtual host configuration that is forwarding the request to your backend should contain the following line: RequestHeader set X-Forwarded-Proto "https"

When Nginx is used as a reverse proxy, please confirm the following:

• The "location" block that redirects requests to the backend should contain the following line : proxy_set_header X-Forwarded-Proto https;
• If using the ProxyPassMatch or ProxyPassReverse directives, you will not be able to successfully activate Email Archiving if you are specifying a port number with the server host (e.g. http://hostname:80/).

Load Balancer/SSL Configurations

SNIP supports both plain-text HTTP communication as well as encrypted HTTPS communication when properly configured. Registration is a multi-step process that relies on several settings from the application configuration as well as the web server request environment in order to successfully complete.

When front-end proxies or load balancers are used to handle load balancing or the SSL offload, additional configurations must be done in order to make sure the request environment is correct:

• The config settings for site_url and host_name must match the public name of the instance.
• The proxy must correctly pass the Host: header to the backend server(s) and the backend servers must have the correct virtual host (vhost) setup for that name.
• If SSL is being used, the SSL certificate must be a fully valid certificate signed by a well-known public Certificate Authority (CA) and include proper chaining as needed. Private certificates/CAs are not supported.
• If the proxy is performing an "SSL Offload" where it passes only HTTP traffic to the backend servers, it must make some distinction between HTTP and HTTPS requests and pass that distinction on to the backend server. If the backend server does not understand between HTTP and HTTPS requests, it will default to generating HTTP URLs in the OAuth token, regardless of the site_url setting.
• HTTPS distinction can be performed in a number of ways for the Apache web server, for example:
  • Insert the header X-Request-Was-SSL: Yes into the request when sending it to the backend servers and use SetEnvIf to set HTTPS to "on" if the header is there.
  • Run an additional vhost on a separate port of the backend server(s) that uses SetEnv HTTPS on to imply HTTPS, and direct the HTTPS-offloaded traffic to that port from the proxy.