Create an Email Integration

Create an email integration (an email account SysAid sends from, receives from, or both). The answer is 201 with the id of the new integration only; read it back with Get an Email Integration. Passwords and OAuth 2.0 client secrets are write-only and never returned or logged. lastModifiedDate is set by the gateway at the time of the request; id, dates and any property not listed in the request body are ignored. A create is not idempotent - repeating a request creates another integration. Creating with defaultOutgoing true makes the new integration the only default outgoing account. While SysAid blocks basic authentication for Microsoft (the disable-ms-basic-auth feature flag), an outgoing host or an incoming server on office365.com, outlook.com or exchange.microsoft.com is refused with 400; Microsoft accounts need OAuth 2.0 sign-in, which is set up in SysAid. A text value that sanitizing makes longer than SysAid can store is refused with 400 rather than cut. In rare cases SysAid stores the integration and still fails the request (when demoting the previous default outgoing account fails), which is answered 500; list the integrations before retrying. 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. A SysAid failure is answered 500 or 502.

Body Params

The settings of the new email integration. Only name and emailAddress are required; configure the outgoing (SMTP) direction, the incoming (IMAP or POP3) direction, or both. A boolean left out is false and a number left out is 0. Properties not listed here, such as id, lastModifiedDate or SysAid's stored ciphertext, are ignored and never sent to SysAid. (The gateway strips them through its schema validation, which removes additional properties.) Text values other than user names, passwords and client secrets are sanitized like every other Connect input; passwords and client secrets reach SysAid unchanged. A password or client secret that starts with crypt:, is exactly ********, is blank or is longer than 160 bytes in UTF-8 is rejected with 400.

string
required
length between 1 and 120

The display name of the email integration.

string
length ≤ 120

The purpose of the email integration.

string
required
length between 1 and 255

The email address of the integration, the From address of outgoing mail and the monitored address of incoming mail.

boolean

Whether this becomes the default outgoing (send-from) email account. When true, every other integration stops being the default.

boolean

Whether SysAid sends email through this integration.

string
enum

The outgoing mail protocol. Only smtp is supported.

Allowed:
string
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). IPv6 addresses are not supported.

integer
1 to 65535

The port of the SMTP server.

integer
enum

The encryption of the SMTP connection: 0 none, 1 SSL, 2 TLS, 3 TLS 1.2.

Allowed:
string
length ≤ 255

The user name for the SMTP server. Sent to SysAid unchanged.

password
length between 1 and 160

The password for the SMTP server. Write-only; never returned or logged.

string
length ≤ 255

The character encoding of outgoing email.

string
enum

The content type of outgoing email bodies.

Allowed:
string
enum

The OAuth 2.0 provider of the outgoing direction. SysAid signs in with OAuth 2.0 only for an integration whose protocol is OAuth 2.0, which this operation does not set, so the OAuth 2.0 settings are stored but not used until the integration is switched to OAuth 2.0 in SysAid.

Allowed:
string
length ≤ 255

The Azure AD tenant ID of the outgoing direction, for the microsoft provider.

string
length ≤ 255

The OAuth 2.0 client (application) ID of the outgoing direction.

password
length between 1 and 160

The OAuth 2.0 client secret of the outgoing direction. Write-only; never returned or logged.

boolean

Whether SysAid checks the mailbox of this integration for incoming email.

string
enum

The incoming mail protocol.

Allowed:
string
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 incoming mail server, with an optional :port, for example imap.company.com:993. IPv6 addresses are not supported.

integer
enum

The encryption of the incoming connection: 0 none, 1 SSL, 2 TLS, 3 TLS 1.2.

Allowed:
string
length ≤ 255

The user name for the incoming mail server. Sent to SysAid unchanged.

password
length between 1 and 160

The password for the incoming mail server. Write-only; never returned or logged.

string
enum

The OAuth 2.0 provider of the incoming direction. SysAid keeps the incoming OAuth 2.0 settings only for an incoming protocol of OAuth 2.0, which this operation does not set, so with imap or pop3 SysAid does not store them.

Allowed:
string
length ≤ 255

The Azure AD tenant ID of the incoming direction, for the microsoft provider.

string
length ≤ 255

The OAuth 2.0 client (application) ID of the incoming direction.

password
length between 1 and 160

The OAuth 2.0 client secret of the incoming direction. Write-only; never returned or logged.

boolean

Whether the service record ID is searched for in the subject from its end towards its start.

boolean

Whether the service record ID is also searched for in the body of an incoming email.

integer
0 to 2147483647

The ID of the status set on an existing service record when a new email arrives for it; 0 leaves the status unchanged.

string
length ≤ 255

A comma-separated list of status IDs. Incoming emails for a service record in one of these statuses are ignored.

string
length ≤ 4000

A regular expression. Incoming emails whose subject matches it are ignored.

string
length ≤ 1000

A comma-separated list of sender addresses whose incoming emails are ignored.

string
length ≤ 1000

A comma-separated list of sender addresses; when set, only incoming emails from them are processed.

string
length ≤ 255

The address ignored incoming emails are forwarded to.

string
length ≤ 255

The address that receives a copy of every processed incoming email.

boolean

Whether duplicate incoming emails are deleted automatically.

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