Test an Incoming Email Configuration

Test the settings of an incoming (IMAP or POP3) mail server. SysAid opens a connection to the server and authenticates with the given credentials. It saves nothing and reads no message. For IMAP, SysAid opens the INBOX read-write and closes it with an expunge, so messages in it that are already marked deleted are removed; for POP3 nothing in the mailbox changes. The settings are taken from the request only - this operation does not read or change any stored email integration, so the error counters and alerts of a stored integration are not reset by a successful test (no id is ever sent to SysAid). When the test ran, the answer is always 200 with success, a machine-readable reason and a fixed message; a failed test (wrong server, encryption or credentials, an unreachable server) is success false, not an error status. The message is one fixed text per reason and never contains the server, 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). timeout is reported for IMAP only, because SysAid reports every POP3 connection or read failure, a timeout included, as connection_failed (after about 10 seconds). SysAid waits up to 10 seconds for each step of the 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 incoming (IMAP or POP3) 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
required

The incoming mail protocol.

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_])?)*(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?$

The host name or IPv4 address of the mail server, with an optional :port from 1 to 65535 in the same value, for example imap.company.com:993; anything else is answered 400. IPv6 addresses are not supported. Without a port SysAid uses the protocol's default for the chosen encryption: with SSL (1) or TLS 1.2 (3), 993 for IMAP and 995 for POP3; with TLS (2), 143 for IMAP and 110 for POP3; with no encryption (0) the mail library's own default (143 and 110).

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
required
length ≥ 1

The user name for the mail server. Required, because SysAid's mail library falls back to the operating-system user of the SysAid server when it is empty.

password

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

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