Custom Email Servers

Applicable to Sisense on Linux and Microsoft Windows

Sisense includes a default email server configuration that uses Mandrill by MailChimp to send automated emails such as dashboard reports or password reset emails. This configuration can be used for POC and testing environments.

Important: Custom email servers allow all your email transactions to be completely managed on your side.

In Sisense, you can set up your custom email server for sending Sisense emails to your users. There are two ways you can set up your custom email server, through Sisense or through the REST API.

Setting Up Your Email Server through Sisense

To set up a custom email server:

  1. In the Admin page, select Email Server.
  2. Select Enable Custom Email Server.
  3. Select the Email Service. For custom email servers, select SMTP Server. If you are modifying the Sisense Mandrill server to work with your server, select Mandril by MailChimp.
  4. If you selected Mandrill by Mailchimp, enter the following information:
    API Key: The API key provided by Mailchimp.
    Sender Email: The email address that is displayed as the Sender Email address in emails to your user.
    Sender Name: The name that is displayed as the Sender Name in emails to your user.
  5. If you selected SMTP Server, enter the following information:
    Host: The hostname or IP address to connect to. By default, this is 'localhost'.
    Port: The port to connect to (defaults to 25 or 465).
    Secure: When you send an email, some email servers check if secure transport (TLS) is available for that address or domain. This value determines if the connection should use TLS (if true) or not (if false). The default value is false. The connection may be upgraded to TLS if the email server requires it.
    Ignore TLS: If this is true and Secure is false, TLS will not be used even if the email server attempts to upgrade the connection to TLS-secure.
    This field should be set to true when connecting to a non-secure SMTP server.
    Require TLS: If this is true and Secure is false, it forces the connection to be upgraded to TLS-secure even if the email server does not advertise support for TLS.
    Connection Timeout: How many milliseconds to wait for the connection to establish.
    Greeting Timeout: How many milliseconds to wait for the greeting after connection is established.
    Socket Timeout: How many milliseconds of inactivity to allow.
    User: The user name of the user. As non-secure or restricted SMTP servers do not require authentication, do not include this field when connecting to a non-secure SMTP server.
    Password: The user’s password for the email server. As non-secure or restricted SMTP servers do not require authentication, do not include this field when connecting to a non-secure SMTP server.
    Sender Email: The email address that is displayed as the Sender Email address in emails to your user.
    Sender Name: The name that is displayed as the Sender Name in emails to your user.
    Enable NTLM Authentication: Enable if your custom email server supports NTLM authentication.
  6. Click Save to save your changes.
    After your changes are saved, the default values of the email server are replaced with your own.

Setting Up Your Email Server through the REST API

Through the Sisense REST API, you can send an HTTP POST request to issue Sisense emails through your own custom email server instead of the default Sisense email server. The REST API exposes properties that you can configure for the custom email servers such as security, timeout, and logging properties.

When authenticating an HTTP request, Sisense only supports the basic authentication through the Authorization method using plain text.

To set up a custom email server:

  1. In Sisense, click Admin, and then Rest API.
  2. In version 1.0 of the REST API, select Settings, then POST /settings/email_server, and then click Try It Out.
  3. In the body of your call, define the values of the following keys, for example:
    {
    "enable": true,
    "host": "smtp.ethereal.email",
    "port": 587,
    "secure": true,
    "ignoreTLS": false,
    "requireTLS": false,
    "connectionTimeout": 300,
    "greetingTimeout": 300,
    "socketTimeout": 300,
    "user": "[email protected]",
    "pass": "mypassword",
    "logger": false,
    "debug": false
    }
Key Value

enable

If true, allows access to the custom email server instead of the default Sisense email server.

Note: This property is different from the enable property found in version .9 of the REST API POST /settings/system request. In .9, enable activates Sisense emails. In version 1.0, enable sends Sisense emails through your custom server.

host

The hostname or IP address to connect to. By default, this is 'localhost'.

port

The port to connect to (defaults to 25 or 465).

secure

When you send an email, some email servers check if secure transport (TLS) is available for that address or domain.

This value determines if the connection should use TLS (if true) or not (if false). The default value is false. The connection may be upgraded to TLS if the email server requires it.

ignoreTLS

If this is true and secure is false, TLS will not be used even if the email server attempts to upgrade the connection to TLS-secure.

This field should be set to true when connecting to a non-secure SMTP server.

requireTLS

If this is true and secure is false, it forces the connection to be upgraded to TLS-secure even if the email server does not advertise support for TLS.

connectionTimeout

How many milliseconds to wait for the connection to establish.

greetingTimeout

How many milliseconds to wait for the greeting after connection is established.

socketTimeout

How many milliseconds of inactivity to allow.

user

The user name of the user.

As non-secure or restricted SMTP servers do not require authentication, do not include this field when connecting to a non-secure SMTP server.

pass

The user’s password for the email server.

As non-secure or restricted SMTP servers do not require authentication, do not include this field when connecting to a non-secure SMTP server.

logger

If set to True, Sisense logs events such as which server you connected to.If the value is not defined or is False, then nothing is logged.

debug

If set to true, then Sisense logs SMTP traffic. When False, Sisense logs only transaction events.Debug logs record everything and may increase in size quickly and impact performance. You should only set activate debug logging when troubleshooting a specific issue and then reset the logging level back to info.

  1. Click Run.
  2. After you have set up the email server, you need to change the sender email address to the domain of your custom email server so they are consistent. You can update the sender email through the POST 0.9 /branding endpoint in the SisenseREST API.
    { 
    					"emails": {
    					"senderEmail": "[email protected]"
    					}
    			}
  1. Click Run. Your Sisense emails are now sent through your custom email server.