Using SMTP SSL in Cloud Director

One of our customer ask a question about possibility of sending Email notifications with SMTP over SSL in his organization. Here is instruction how to configure Email notifications using SMTP server that will use SSL connection.

1. Log into the Cloud Director API as a Organization Administrator:
   Request:

POST  https://vcloud-director-fqdn/api/sessions

Headers:

 Accept: Accept = application/*+xml;version=32.0
 Authorization:  Basic (username@orgname / password)

In response (200 OK) you should copy x-vmware-vcloud-access-token for further queries as Bearer token.

2. Next you should get Organization information from Cloud Director (href that will be used in next queries)
Request:

GET  https://vcloud-director-fqdn/api/org

Headers:

Accept: application/*+json;version=32.0
Authorization = Bearer token that we get at step 1

In response (200 OK) you get UUID of organization that goes after /org/ pattern in href option. In our case UUID is 9fc961d2-7939-496e-895b-e7c0137b86ba

3. We can get info about current settings of Email configuration using GET request with UUID of organization that we get at step 2. Don't forget to add Content-type into Headers.

Request:

GET  https://vcloud-director-fqdn/api/admin/org/9fc961d2-7939-496e-895b-e7c0137b86ba/settings/email

Headers:

Accept: application/*+json;version=32.0
Authorization: Bearer token that we get at step 1
Content-Type: application/vnd.vmware.admin.organizationEmailSettings+json

In response (200 OK) you get the same data that is availiable at Cloud Director Email page

Default current settings in Cloud Director looks like:

4. If we want to add information about server that will use SSL settings we should prepare data that will be added to JSON :

Sender's email address = fromEmailAddress
Email subject prefix = defaultSubjectPrefix
Send system notifications to - All organization administrators = isAlertEmailToAllAdmins
Send system notifications to - These email addresses = alertEmailTo

SMTP server name = host
SMTP server port = port
Requires authentication = isUseAuthentication
User name = username
Password = password

Additional settings that aren't availiable in Web interface is :

smtpSecureMode - Security protocol to use when connecting to the SMTP server
It can be :
NONE - Do not use any security protocol
SSL - Use the SSL/TLS protocol
START_TLS - Use the STARTTLS protocol

In documentation VMware Cloud Director API there is an error in smtpSecureMode description in case of STARTTLS protocol. Correct option should be START_TLS not startTls .

SslTrustStore - Custom truststore to use to trust peer certificates when establishing a secure connection using SSL/STARTTLS (when enabled).
This option should be used in case of Self-Signed certificates.

Final JSON body that contains all the data should look like this:

{
    "isDefaultSmtpServer": false,
    "isDefaultOrgEmail": false,
    "fromEmailAddress": "robot@vmadm.in",
    "defaultSubjectPrefix": "",
    "isAlertEmailToAllAdmins": false,
    "alertEmailTo": [],
    "smtpServerSettings": {
        "otherAttributes": {},
        "isUseAuthentication": true,
        "host": "mail.vmadm.in",
        "port": 465,
        "username": "robot@vmadm.in",
        "password": "Afkff7PAS2wdLD7AN",
        "smtpSecureMode": "SSL",
        "sslTrustStore": null
    }
}

Request:

PUT  https://vcloud-director-fqdn/api/admin/org/9fc961d2-7939-496e-895b-e7c0137b86ba/settings/email

Headers:

Accept: application/*+json;version=32.0
Authorization: Bearer token that we get at step 1
Content-Type: application/vnd.vmware.admin.organizationEmailSettings+json

In response (200 OK) you get the same data that were sent in Body of request to API

If we check settings in Cloud Director we see that data contains info from JSON body.

Warning! If you make some changes from Web interface at Email settings page all the settings that belong to SSL SMTP will be lost and you'll need to add them with API request one more time. Be careful !
As alternative you can add all the settings except SSL SMTP options via HTML5 interface, then GET settings, copy them to notepad and make changes of SMTP SSL and add password to these JSON, and finally PUT them to API .

5. Finally we can test email sending to any email address with TEST button

If your settings is correct you'll get email at Destination email address

Congratulations! You're awesome!

FYI:
If you want to set global Email SMTP SSL settings at Cloud Director level you should use username@system at API auth and GET/PUT requests to API at endpoint: https://vcloud-director-fqdn/api/admin/extension/settings/email
JSON body will have the same format.

Additional docs:
https://code.vmware.com/apis/1046/vmware-cloud-director/doc/doc/types/SmtpServerSettingsType.html