Test an Outgoing Email Configuration

Test the settings of an outgoing (SMTP) mail server. SysAid opens a connection to the server and authenticates with the given credentials; it sends no email and saves nothing. The settings are taken from the request only - this operation does not read or change any stored email integration, so the failure counters of a stored integration are not reset by a successful test. When the test ran, the answer is always 200 with success, a machine-readable reason and a fixed message; a failed test (wrong host, port, encryption or credentials, a malformed emailAddress, an unreachable server) is success false, not an error status. The message is one fixed text per reason and never contains the host, the port, the submitted credentials or any text of the mail server. Whether the test passed is decided by SysAid's HTTP status, not by the language of its text; reason is refined only when the SysAid user speaks English, so for any other language a failed test has the reason unknown (a passed test is always success true). SysAid waits up to 10 seconds for each step of the SMTP exchange (connecting, then every reply), not for the test as a whole; the gateway gives up on the whole call after 40 seconds and answers 504, and SysAid may still be running the test then. A password that starts with crypt: and the placeholder ******** are rejected with 400, because neither is a password to try. The password is never logged. Requires a SysAid Admin session; SysAid administrators only. A request without a valid session is answered 401, and a signed-in user who is not a SysAid administrator is answered 403. Any other SysAid failure (the test could not be run) is answered 500, 502 or 504.

Body Params

The outgoing (SMTP) settings to test. Nothing is stored. Properties not listed here, including the id of a stored email integration, are ignored and never sent to SysAid. (The gateway strips them through its schema validation, which removes additional properties.)

string
enum
Defaults to smtp

The outgoing mail protocol. Only smtp is supported.

Allowed:
string
required
length between 1 and 255
^[A-Za-z0-9_]([A-Za-z0-9_-]*[A-Za-z0-9_])?(\.[A-Za-z0-9_]([A-Za-z0-9_-]*[A-Za-z0-9_])?)*$

The host name or IPv4 address of the SMTP server, without a port (the port is outgoingPort); anything else, such as smtp.company.com:25, is answered 400. IPv6 addresses are not supported.

integer
required
1 to 65535

The port of the SMTP server.

integer
enum

The connection encryption: 0 none, 1 SSL, 2 TLS, 3 TLS 1.2. When left out, no encryption (0) is used.

Allowed:
string

The user name for the SMTP server. Leave out when the server needs no authentication.

password

The password for the SMTP server. It is never returned or logged. A value that starts with crypt: or is exactly ******** is rejected with 400.

string
required
length ≥ 1

The address SysAid sends from, and the user name it authenticates to the SMTP server with (SysAid has no separate outgoing user in this test, so there is no fallback to guard against and no separate user field). It is not checked here; an address SysAid cannot use makes the test fail (success false).

Responses

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json