Overview

Universal Controller supports the following RESTful-based web services for Email Connection operations, which are listed alphabetically on this page.

Create an Email Connection
Delete an Email Connection
List Email Connections
Modify an Email Connection
Read an Email Connection

Formatting specifications for each web service, including details about property requirements, are provided.

Create an Email Connection

	Description
URI	http://host_name/uc/resources/emailconnection
HTTP Method	POST
Description	Creates an Email Connection.
Example URI	http://localhost:8080/uc/resources/emailconnection
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Create an Email Connection: Example Request, below.
Example Response	Status 200 /OK Successfully created the Email Connection with sysId {sysId}. Status 400 /Bad Request Create Email Connection failed. A duplicate value has been detected. Name must be unique.
Email Connection Properties	See Email Connection Properties, below.

Create an Email Connection: Example Request

XML Request

JSON Request

XML Request

<emailConnection exportReleaseLevel="7.3.0.0" exportTable="ops_email_connection" retainSysIds="true" version="3">
    <authentication>true</authentication>
    <authenticationType>Password</authenticationType>
    <defaultUser>jane.doe@stonebranch.com</defaultUser>
    <description />
    <emailAddr>jane.doe@stonebranch.com</emailAddr>
    <imap />
    <imapPort>143</imapPort>
    <imapSsl>false</imapSsl>
    <imapStarttls>false</imapStarttls>
    <name>Email Connection 1</name>
    <oauthClient />
    <opswiseGroups/>
    <smtp>smtp.gmail.com</smtp>
    <smtpPort>465</smtpPort>
    <smtpSsl>true</smtpSsl>
    <smtpStarttls>false</smtpStarttls>
    <sysId>3b2c5049632841189888c921f9584edf</sysId>
    <systemConnection>false</systemConnection>
    <trashFolder />
    <type>Outgoing</type>
</emailConnection>

JSON Request

{
  "authentication" : true,
  "authenticationType" : "Password",
  "defaultUser" : "jane.doe@stonebranch.com",
  "description" : null,
  "emailAddr" : "jane.doe@stonebranch.com",
  "exportReleaseLevel" : "7.3.0.0",
  "exportTable" : "ops_email_connection",
  "imap" : null,
  "imapPort" : 143,
  "imapSsl" : false,
  "imapStarttls" : false,
  "name" : "Email Connection 1",
  "oauthClient" : null,
  "opswiseGroups" : [ ],
  "retainSysIds" : true,
  "smtp" : "smtp.gmail.com",
  "smtpPort" : 465,
  "smtpSsl" : true,
  "smtpStarttls" : false,
  "sysId" : "3b2c5049632841189888c921f9584edf",
  "systemConnection" : false,
  "trashFolder" : null,
  "type" : "Outgoing",
  "version" : 3
}

Email Connection Properties

Property	UI Field Name	Description	Specifications	Required
`authentication`	Authentication Required	Deprecated. If `type` = Outgoing; Specification for whether or not `defaultUser` and `password` are required.	Boolean; Valid values: true/false. Default is false.	N
`authenticationType`	Authentication	Method of authentication.	Valid values (case-insensitive): As String = None, As Value = 0 As String = Password, As Value = 1 As String = OAuth 2.0, As Value = 2	N
`authorized`	Is Authorized	If `authenticationType` = OAuth 2.0; Specification for whether or not the email connection is authorized.	Boolean; read only	N
`defaultPwd`	Password	If `type` = Outgoing and `authenticationType` = Password; Password that the Controller will use to connect to the server.		Y (if `type` is Outgoing and `authenticationType` is Password)
`defaultUser`	User Name	If `type` = Outgoing and `authenticationType` = Password or OAuth 2.0 or if `type` = Incoming and `authenticationType` = OAuth 2.0; User Name that the Controller will use to connect to the server.		Y (if `type` is Outgoing and `authenticationType` is Password or OAuth 2.0 or if `type` is Incoming and `authenticationType` is OAuth 2.0)
`description`	Description	Description of this record.		N
`emailAddr`	Email Address	If `type` = Outgoing; Email address of the sender.		Y
`exportReleaseLevel`	n/a	Universal Controller release that the record was exported from.	read only	N
`exportTable`	n/a	Record table information.	read only	N
`imap`	Incoming Mail Server (IMAP)	If `type` = Incoming; Name or IP address of the incoming email server.		Y
`imapPort`	IMAP Port	If `type` = Incoming; Port on the machine where the incoming email server resides.		Y
`imapSsl`	Enable SSL	If `type` = Incoming; Specification for whether or not SSL/TLS connectivity is enabled for your server.	Boolean; Valid values: true/false. Default is false.	N
`imapStarttls`	Enable STARTTLS	If `type` = Incoming; Specification for whether or not the use of the STARTTLS command (if supported by the server) is enabled to switch the connection to a TLS-protected connection before issuing any login commands. (An appropriate trust store must be configured so that the client will trust the server's certificate. )		N
`name`	Connection Name	Name used within the Controller to identify this Email Connection.		Y
`oauthClient`	OAuth Client	The OAuth client used to authorize the email connection.		Y (if `authenticationType` is OAuth 2.0)
`opswiseGroups`	Member of Business Services	Business Services that this record belongs to. XML <opswiseGroups> <opswiseGroup>group1</opswiseGroup> <opswiseGroup>group2</opswiseGroup> </opswiseGroups> JSON "opswiseGroups": ["group1","group2"]		N
`smtp`	Outgoing Mail Server (SMTP)	If `type` = Outgoing; Name or IP address of the outgoing email server.		Y
`smtpPort`	SMTP Port	If `type` = Outgoing; Port on the machine where the outgoing email server resides.		Y
`smtpSsl`	Enable SSL	If `type` = Outgoing; Specification for whether or not SSL/TLS connectivity is enabled for your server.	Boolean; Valid values: true/false. Default is false.	N
`smtpStarttls`	Enable STARTTLS	If `type` = Outgoing; Specification for whether or not the use of the STARTTLS command (if supported by the server) is enabled to switch the connection to a TLS-protected connection before issuing any login commands. (An appropriate trust store must be configured so that the client will trust the server's certificate. )		N
`sysId`	n/a	System ID field in the database for this Email Connection record.	Persisted only if retainSysIds is set to true.	N
`systemConnection`	Use for System Notifications	If `type` = Outgoing; Specification for whether or not this Email Connection is to be used for system notifications.	Boolean; Valid values: true/false. Default is false.	Y
`trashFolder`	Trash Folder	If `type` = Incoming; Folder to use for deleted emails.		N
`type`	Connection Type	Type of Email Connection. Note: You cannot modify the type after the Email Connection has been created.	Valid Values: As String = Outgoing, As Value = 1 As String = Incoming, As Value = 2 Default is Outgoing (1)	Y

Delete an Email Connection

	Description
URI	http://host_name/uc/resources/emailconnection
HTTP Method	DELETE
Description	Deletes an Email Connection.
URI Parameters	See Delete an Email Connection: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/emailconnection?connectionname=Test4
Example Response	Status 200 /OK Email Connection deleted successfully. Status 400 /Bad Request Mutual exclusion violation. Cannot specify `connectionname` and `connectionid` at the same time. Status 404 /Not Found An Email Connection with {name/id} "test" does not exist.

Delete an Email Connection: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`connectionid`	ID used within the Controller to identify this Email Connection.	String; URI parameter.	Y (unless `connectionname` is specified)	`connectionname`
`connectionname`	Name used within the Controller to identify this Email Connection.	String; URI parameter.	Y (unless `connectionid` is specified)	`connectionid`

List Email Connections

	Description
URI	http://host_name/uc/resources/emailconnection/list
HTTP Method	GET
Description	Retrieves information on all Email Connections.
Example URI	http://localhost:8080/uc/resources/emailconnection/list
Authentication	HTTP Basic
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example Response	See List Email Connections: Example Response, below.
Email Connection Properties	See Email Connection Properties.

List Email Connections: Example Response

XML Response

JSON Response

XML Request

<emailConnection exportReleaseLevel="7.3.0.0" exportTable="ops_email_connection" retainSysIds="true" version="3">
    <authentication>true</authentication>
    <authenticationType>Password</authenticationType>
    <authorized>false</authorized>
    <defaultUser>jane.doe@stonebranch.com</defaultUser>
    <description />
    <emailAddr>jane.doe@stonebranch.com</emailAddr>
    <imap />
    <imapPort>143</imapPort>
    <imapSsl>false</imapSsl>
    <imapStarttls>false</imapStarttls>
    <name>Email Connection 1</name>
    <oauthClient />
    <opswiseGroups/>
    <smtp>smtp.gmail.com</smtp>
    <smtpPort>465</smtpPort>
    <smtpSsl>true</smtpSsl>
    <smtpStarttls>false</smtpStarttls>
    <sysId>3b2c5049632841189888c921f9584edf</sysId>
    <systemConnection>false</systemConnection>
    <trashFolder />
    <type>Outgoing</type>
</emailConnection>

JSON Request

{
  "authentication" : true,
  "authenticationType" : "Password",
  "authorized" : false,
  "defaultUser" : "jane.doe@stonebranch.com",
  "description" : null,
  "emailAddr" : "jane.doe@stonebranch.com",
  "exportReleaseLevel" : "7.3.0.0",
  "exportTable" : "ops_email_connection",
  "imap" : null,
  "imapPort" : 143,
  "imapSsl" : false,
  "imapStarttls" : false,
  "name" : "Email Connection 1",
  "oauthClient" : null,
  "opswiseGroups" : [ ],
  "retainSysIds" : true,
  "smtp" : "smtp.gmail.com",
  "smtpPort" : 465,
  "smtpSsl" : true,
  "smtpStarttls" : false,
  "sysId" : "3b2c5049632841189888c921f9584edf",
  "systemConnection" : false,
  "trashFolder" : null,
  "type" : "Outgoing",
  "version" : 3
}

Modify an Email Connection

	Description
URI	http://host_name/uc/resources/emailconnection
HTTP Method	PUT
Description	Modifies the Email Connection specified by the `sysId`.
Example URI	http://localhost:8080/uc/resources/emailconnection
Consumes Content-Type	application/xml, application/json
Produces Content-Type	n/a
Example Request	See Modify an Email Connection: Example Request, below.
Email Connection Properties	See Email Connection Properties.
Example Response	Status 200 /OK Successfully updated the Email Connection with sysId <sysId> to version <version>.

Modify an Email Connection: Example Request

XML Request

JSON Request

XML Request

<emailConnection>
    <authentication>true</authentication>
    <defaultPwd>abc1</defaultPwd>
    <defaultUser>user1</defaultUser>
    <description>description</description>
    <emailAddr>jane.doe@stonebranch.com</emailAddr>
    <imap />
    <imapPort />
    <imapSsl>true</imapSsl>
    <imapStarttls>false</imapStarttls>
    <name>Email Connection 1</name>
    <opswiseGroups />
    <smtp>server1</smtp>
    <smtpPort>4567</smtpPort>
    <smtpSsl>true</smtpSsl>
    <smtpStarttls>false</smtpStarttls>
    <sysId>62701879a6264107bb757a952bcc65cc</sysId>
    <systemConnection>true</systemConnection>
    <trashFolder />
    <type>Outgoing</type>
</emailConnection>

JSON Request

{
    "authentication": true,
    "defaultPwd": "abc1",
    "defaultUser": "user1",
    "description": "description",
    "emailAddr": "jane.doe@stonebranch.com",
    "imap": null,
    "imapPort": null,
    "imapSsl": true,
    "imapStarttls": null,
    "name": "Email Connection 1",
    "opswiseGroups": null,
    "smtp": "server1",
    "smtpPort": 4567,
    "smtpSsl": true,
    "smtpStarttls": false,
    "systemConnection": true,
    "sysId": "62701879a6264107bb757a952bcc65cc",
    "trashFolder": null,
    "type": "Outgoing"
}

Read an Email Connection

URI	http://host_name/uc/resources/emailconnection
HTTP Method	GET
Description	Retrieves information on a specific Email Connection.
URI Parameters	See Read an Email Connection: URI Parameters, below.
Example URI	http://localhost:8080/uc/resources/emailconnection?connectionname=Test4
Consumes Content-Type	n/a
Produces Content-Type	application/xml, application/json
Example Response	See Read an Email Connection: Example Response, below.
Email Connection Properties	See Email Connection Properties.

Read an Email Connection: URI Parameters

Parameter	Description	Specifications	Required	Mutually Exclusive With
`connectionid`	ID used within the Controller to identify this Email Connection.	String; URI parameter.	Y (unless `connectionname` is specified)	`connectionname`
`connectionname`	Name used within the Controller to identify this Email Connection.	String; URI parameter.	Y (unless `connectionid` is specified)	`connectionid`

Read an Email Connection: Example Response

XML Response

JSON Response

XML Request

<emailConnection exportReleaseLevel="7.3.0.0" exportTable="ops_email_connection" retainSysIds="true" version="3">
    <authentication>true</authentication>
    <authenticationType>Password</authenticationType>
    <authorized>false</authorized>
    <defaultUser>jane.doe@stonebranch.com</defaultUser>
    <description />
    <emailAddr>jane.doe@stonebranch.com</emailAddr>
    <imap />
    <imapPort>143</imapPort>
    <imapSsl>false</imapSsl>
    <imapStarttls>false</imapStarttls>
    <name>Email Connection 1</name>
    <oauthClient />
    <opswiseGroups/>
    <smtp>smtp.gmail.com</smtp>
    <smtpPort>465</smtpPort>
    <smtpSsl>true</smtpSsl>
    <smtpStarttls>false</smtpStarttls>
    <sysId>3b2c5049632841189888c921f9584edf</sysId>
    <systemConnection>false</systemConnection>
    <trashFolder />
    <type>Outgoing</type>
</emailConnection>

JSON Request

{
  "authentication" : true,
  "authenticationType" : "Password",
  "authorized" : false,
  "defaultUser" : "jane.doe@stonebranch.com",
  "description" : null,
  "emailAddr" : "jane.doe@stonebranch.com",
  "exportReleaseLevel" : "7.3.0.0",
  "exportTable" : "ops_email_connection",
  "imap" : null,
  "imapPort" : 143,
  "imapSsl" : false,
  "imapStarttls" : false,
  "name" : "Email Connection 1",
  "oauthClient" : null,
  "opswiseGroups" : [ ],
  "retainSysIds" : true,
  "smtp" : "smtp.gmail.com",
  "smtpPort" : 465,
  "smtpSsl" : true,
  "smtpStarttls" : false,
  "sysId" : "3b2c5049632841189888c921f9584edf",
  "systemConnection" : false,
  "trashFolder" : null,
  "type" : "Outgoing",
  "version" : 3
}

Universal Controller 7.6.x

Email Connection Web Services

Overview

Create an Email Connection

Create an Email Connection: Example Request

Email Connection Properties

Delete an Email Connection

Delete an Email Connection: URI Parameters

List Email Connections

List Email Connections: Example Response

Modify an Email Connection

Modify an Email Connection: Example Request

Read an Email Connection

Read an Email Connection: URI Parameters

Read an Email Connection: Example Response