Mail REST API
For IQ Server to be able to provide email-based notifications, an SMTP server needs to be configured. The REST API described here allows system administrators to manage that configuration:
Warning: For mail notifications to function correctly, the Base URL must be already configured.
Query Current Mail Configuration
To inspect the currently configured SMTP server, you can make a GET request to the following path:
GET /api/v2/config/mail
Below is an example request to a local IQ Server using the built-in administrator account and the cURL tool:
curl -u admin:admin123 http://localhost:8070/api/v2/config/mail
If no mail integration is configured, the request yields HTTP status code 404. Otherwise, a JSON document with the following properties is returned:
Property | Description |
|---|---|
| The hostname or IP address of the SMTP server to use for outgoing mail. |
| The port number on which the SMTP server accepts mail requests. |
| The username needed to authenticate to the SMTP server. |
| The password is always null (never included in the response) for the GET operation. |
| Always false for the GET operation. |
| A boolean flag denoting whether the connection to the SMTP server should use SSL/TLS right from the start. |
| A boolean flag denoting whether the connection to the SMTP server should attempt to upgrade to SSL/TLS using the STARTTLS command. |
| The email address used as |
Test Mail Configuration
To test a mail configuration without changing the current mail configuration, you can make a POST request to the following path:
POST /api/v2/config/mail/test/{recipientEmail}The request requires a JSON document as payload, using the same properties as already described above. The properties hostname, port and systemEmail are required.
The system will send a test mail to the address specified by recipientEmail using the mail configuration provided in the JSON document.
If the password is specified in the input data, then passwordIsIncluded must be set to true. If passwordIsIncluded is set to true and the password is not included, then the password is null, which means "no password".
For test operations, if the password should be loaded from the mail configuration already stored in IQ Server, then the password can be omitted and passwordIsIncluded set to false. However, this is allowed only when the hostname and port match the stored mail configuration. If the hostname or port is different, then the password must be included and passwordIsIncluded must be set to true. The passwordIsIncluded flag is only used for test/update operations and it is not part of the mail configuration itself.
The next example demonstrates such a request:
curl -u admin:admin123 -H "Content-Type: application/json" -X POST -d '{"hostname": "smtp.server", "port": 587, "username": "MyUsername", "password": "MySecret", "passwordIsIncluded": true, "startTlsEnabled": true, "systemEmail": "noreply@smtp.server"}' http://localhost:8070/api/v2/config/mail/test/johndoe@example.comA successful test of the configuration is signaled by HTTP status code 204, indicating the email was sent. If any required JSON property is missing or otherwise invalid, HTTP status code 400 is returned.
Configure Mail Integration
To enable or update the integration with an SMTP server, you can make a PUT request to the following path:
PUT /api/v2/config/mail
The request requires a JSON document as payload, using the same properties as already described above. The properties hostname, port and systemEmail are required.
If the password is specified in the input data, then passwordIsIncludedmust be set to true. If passwordIsIncluded is set to true and the password is not included, then the password is null, which means "no password".
For update operations, if the password should remain unchanged, then the password can be omitted and passwordIsIncluded set to false. However, this is allowed only when the hostname and port are not changed. If thehostnameorportis changed, then the password must be included and passwordIsIncluded must be set to true. The passwordIsIncludedflag is only used for test/update operations and it is not part of the mail configuration itself.
The next example demonstrates such a request:
curl -u admin:admin123 -H "Content-Type: application/json" -X PUT -d '{"hostname": "smtp.server", "port": 587, "username": "MyUsername", "password": "MySecret", "passwordIsIncluded": true, "startTlsEnabled": true, "systemEmail": "noreply@smtp.server"}' http://localhost:8070/api/v2/config/mailA successful update of the configuration is signaled by HTTP status code 204. If any required JSON property is missing or otherwise invalid, HTTP status code 400 is returned.
Disable Mail Integration
If IQ Server does not employ mail-based notifications, the mail configuration can be entirely removed using the request:
DELETE /api/v2/config/mail
For example:
curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/config/mail
If a mail server was configured, the request responds with HTTP status code 204. If no mail server was configured to begin with, the HTTP status code 404 is returned instead.