Configure and Use External Mail Server

A mail server is required for sending notification emails from API Portal. A mail server is available in the deployment, but you can use an external, corporate mail server.
Using default mail server sends the mails with @CA domain in the sender address. To send mails from a different mail server with your customized email address, you can configure a mail server. 
API Portal supports only 
Simple Mail Transfer Protocol 
(SMTP) server.
This section describes how to configure SMTP mail server at portal level and at tenant level.
Configure SMTP at Portal Level
SMTP mail servers can use SSL and non-SSL channels to communicate with API Portal.
Prerequisite:
 Verify that Docker is configured with a proper storage driver and log driver in the 
/etc/docker/daemon.json file
.
Follow these steps:
  1. (Optional)
     If you are using SMTP over SSL, copy the certificate file from your corporate mail server and add it to a directory, for example, 
    /home/portal
     in the Portal VM. If you are not using SSL, proceed directly to the next step.
  2. Open the 
    <install_dir>/conf/portal.conf
     file and ensure that the following entries are at the end of the file:
    • PORTAL_SMTP_HOST:
       SMTP hostname or IP address. When using a FQDN, ensure this is resolvable by your DNS server. 
    • PORTAL_SMTP_PORT:
       SMTP server port. 
    • PORTAL_SMTP_USERNAME:
       User name to connect to SMTP server.
    • PORTAL_SMTP_PASSWORD:
       Password to authenticate with SMTP server.
    • (Optional) PORTAL_SMTP_SSL_CERT:
       Location of certificate for connecting to SMTP server over SSL. If you are not using SMTP over SSL, leave this variable empty or remove it altogether.
    The following code block shows an example: 
    PORTAL_SMTP_HOST="mail.example.com" PORTAL_SMTP_PORT="25" PORTAL_SMTP_USERNAME="qa_mail" PORTAL_SMTP_PASSWORD="mailpassword" PORTAL_SMTP_SSL_CERT=/etc/ca/apim-portal/certs/smtp.crt
  3. Save and close the 
    portal.conf
     file.
  4. Run the 
    portal.sh
     script.
An external mail server is configured.
Configure SMTP at the Tenant Level
Configure mail server to send emails from a different mail server with the custom SMTP configurations. You can use trusted certificates to authenticate the API Portal or client or both.
Ensure that the tenant uses only the following SMTP authentication mechanisms, as supported by API Portal:
  • PLAIN
  • LOGIN
  • CRAM-MD5
  • DIGEST-MD5
To configure SMTP at the tenant level:
  1. Log in as administrator.
  2. Select 
    Settings
    , Email Settings.
  3. Select 
    Enabled
     to configure custom SMTP service.
    Disabled option is used for the default mail server that is configured during deployment.
  4. Select one of the following delivery protocols to send emails:
    • SMTP
    • SMTPS
    • SMTP TLS
  5. (If you have selected SMTPS or SMTP TLS) Complete the following information to upload the trusted certificates:
    • SSL Authentication Type
      • Server Authentication
        : Select this option if you want API Portal to send the client a trusted certificate to authenticate itself.
      • Mutual Authentication
        Select this option if you want the client and API Portal to mutually authenticate each other using their corresponding trusted certificates.
    • Server Certificate:
      Upload a trusted certificate in X.509 format that is required for a secure connection with the SMTP server. 
      Maximum file size:
       50 KB 
    • (If Mutual Authentication is selected)
       Client Certificate: 
      To verify the client authentication by the server, select Create CSR and then upload a trusted certificate.
      Consider the following points before uploading the trusted certificate:
      • The maximum file size of the certificate must be 50 KB.
      • If you have already uploaded a certificate to authenticate your client, then the newly uploaded valid certificate replaces the old one after you select Save. This change cannot be reversed.
      • Replacing a previously uploaded certificate may disrupt your existing SMTP connection. In such a case, API Portal displays a warning message. Ensure that you check the corresponding CSR, the connection details, and so on, to establish a successful SMTP connection.
      • If you have already uploaded a client certificate, you cannot delete it. You need upload a new one.
      • Do not upload an expired certificate.
      • CSR is not available for download later.
      Complete the field values to create the CSR:
      • Common Name: 
        Specifies a distinguished name that is associated with your CSR. 
        Recommendation
        : The Common Name is typically composed of Host + Domain Name.
      • Alias Name: 
        Specifies a common identifier name that is associated with the CSR. Ensure that you add a unique alias name every time you upload a new certificate.
      • Organization/ Department/ City/ State/ Country: 
        Specifies the details relevant to your organization.
      • Key Size: 
        Select the key length (in bits) for the RSA Key pair. The signature algorithm that is used to generate the key pair is SHA256withRSA.
    • Alias Name: 
      Specifies the Alias Name, unique to your CSR. Depending on your selection, the corresponding CSR is selected.
    • Choose File: 
      Selects the certificate. Ensure that the format of the certificate and file type is valid.
    If you upload an invalid certificate, selecting
    Save
    does not save the file. If you have previously configured a connection, API Portal continues to connect to that connection. If you do not have a previously successful connection, the connection to the SMTP server shows as inactive.
    To delete the saved certificate, select
    Clear File
    , and then save the changes. This is applicable only for server certificates.
  6. Define the connection details for an 
    SMTP
     server.
    • SMTP Host: 
      Specifies the Host Name of the SMTP Server.
    • SMTP Port: 
      Specifies the port of the SMTP server through which the communication happens.
    • (Optional) Username: 
      Specify the username if the SMTP server is enabled for authentication. 
    • (Optional) Password: 
      Specify password that is associated with the username.
  7. Define the emails options:
    The domain that is associated with the 
    From Address
     and
     Bounce Email
     must be a trusted domain on the SMTP host.
    • (Optional) Sender's Name: 
      Specifies the name of the sender.
    • Sender's Address: 
      Specifies the from email address.
    • Verification Email: 
      Specifies the email to test if the connection is successful.
    • (Optional) Bounce Email: 
      Bounced email notifications are sent to the specified email address.
  8. Select 
    Save 
    to save the SMTP configuration.
    The connection to the SMTP server is tested once you save the configuration. 
    • If the connection is successful, an external mail server is configured and success message stating "Connection is active" is displayed. Also a test email is sent to your specified verification email address.
    • If the connection is unsuccessful, API Portal, allows you to save the configuration but there is no connection to the SMTP server. Also a warning message stating "Connection is inactive" is displayed.
    Every time an email is sent, the connection to the SMTP server is validated. If the email is received successfully, it means the connection is successful, and accordingly the connection status is displayed in the Email Settings page. Similarly, even if the connection had been up and running, but due to some error, the email was not delivered, the connection is found inactive. This status is updated on the Email Settings page.