# Mail REST API

For email-based notifications, configure an SMTP server. The REST API described here allows system administrators to manage that configuration. The base URL must be configured before starting.

## 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                                                                                                                 |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------|
| `hostname`            | The hostname or IP address of the SMTP server to use for outgoing mail.                                                  |
| `port`                | The port number on which the SMTP server accepts mail requests.                                                            |
| `username`            | The username is needed to authenticate to the SMTP server.                                                                 |
| `password`            | The password is always null (never included in the response) for the GET operation.                                       |
| `passwordIsIncluded`  | Always _false_ for the GET operation.                                                                                      |
| `sslEnabled`          | A boolean flag denotes whether the connection to the SMTP server should use SSL/TLS right from the start.                |
| `startTlsEnabled`     | A boolean flag denoting whether the connection to the SMTP server should attempt to upgrade to SSL/TLS using the STARTTLS command. |
| `systemEmail`         | The email address used as `From` header in mails sent by IQ Server.                                                       |

## 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 a payload, using the same properties 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.com
```

A 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 `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 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 the`hostname`or`port`is changed, 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 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/mail
```

A 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

The email configuration can be removed using the delete request:

```
DELETE /api/v2/config/mail
```

For example:

```
curl -u admin:admin123 -X DELETE http://localhost:8070/api/v2/config/mail
```

The request responds with HTTP status code 204 when the email configuration is removed. If no mail server was configured, the HTTP status code 404 is returned instead.