Email Connection Web Services

Owned by Former user (Deleted)
Last updated: Jan 25, 2023 by Stonebranch (Deactivated)
8 min read

Overview

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

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 retainSysIds="true">
    <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,
    "retainSysIds": true,
    "smtp": "server1",
    "smtpPort": 4567,
    "smtpSsl": true,
    "smtpStarttls": false,
    "systemConnection": true,
    "sysId": "62701879a6264107bb757a952bcc65cc",
    "trashFolder": null,
    "type": "Outgoing"
}

Email Connection Properties

Property

UI Field Name

Description

Specifications

Required

authentication

Authentication Required

If type = Outgoing; Specification for whether or not defaultUser and password are required.

Boolean; Valid values: true/false. Default is false.

N

defaultPwd

Password

If authentication = true; Password that the Controller will use to connect to the server.

  • If defaultPwd is omitted in the request, it will be ignored.
  • If defaultPwd is provided in the request, it will be updated.

N

defaultUser

User Name

If authentication = true; User name that the Controller will use to connect to the server.


N

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 onlyN

exportTable

n/aRecord table information.read onlyN

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

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 Response
<emailConnections>
    <emailConnection exportReleaseLevel="7.2.0.0" exportTable="ops_email_connection" version="7">
        <authentication>true</authentication>
        <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>
    <emailConnection exportReleaseLevel="7.2.0.0" exportTable="ops_email_connection" version="2">
        <authentication>true</authentication>
        <defaultUser>user2</defaultUser>
        <description>description</description>
        <emailAddr>john.doe@stonebranch.com</emailAddr>
        <imap />
        <imapPort />
        <imapSsl>true</imapSsl>
        <imapStarttls>false</imapStarttls>
        <name>Email Connection 2</name>
        <opswiseGroups />
        <smtp>server2</smtp>
        <smtpPort>4568</smtpPort>
        <smtpSsl>true</smtpSsl>
        <smtpStarttls>false</smtpStarttls>
        <sysId>62701879a6264107bb757a952bcc65cc</sysId>
        <systemConnection>true</systemConnection>
        <trashFolder />
        <type>Outgoing</type>
    </emailConnection>
<emailConnections>
 JSON Response
{
    "authentication": true,
    "defaultUser": "user1",
    "description": "description",
    "emailAddr": "jane.doe@stonebranch.com",
    "exportReleaseLevel": "7.2.0.0",
    "exportTable": "ops_email_connection",
    "imap": null,
    "imapPort": null,
    "imapSsl": true,
    "imapStarttls": null,
    "name": "Email Connection 1",
    "opswiseGroups": null,
    "retainSysIds": true,
    "smtp": "server1",
    "smtpPort": 4567,
    "smtpSsl": true,
    "smtpStarttls": false,
    "systemConnection": true,
    "sysId": "62701879a6264107bb757a952bcc65cc",
    "trashFolder": null,
    "type": "Outgoing"
}
{
    "authentication": true, 
    "defaultUser": "user2",
    "description": "description", 
    "emailAddr": "john.doe@stonebranch.com", 
    "exportReleaseLevel": "7.2.0.0",
    "exportTable": "ops_email_connection",
    "imap": null, 
    "imapPort": null, 
    "imapSsl": true, 
    "imapStarttls": null, 
    "name": "Email Connection 1", 
    "opswiseGroups": null, 
    "retainSysIds": true, 
    "smtp": "server2", 
    "smtpPort": 4568, 
    "smtpSsl": true, 
    "smtpStarttls": false, 
    "systemConnection": true, 
    "sysId": "62701879a6264107bb757a952bcc65cc", 
    "trashFolder": null, 
    "type": "Outgoing"
}

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 Response
<emailConnection exportReleaseLevel="7.2.0.0" exportTable="ops_email_connection" retainSysIds="true" version="1">
    <authentication>true</authentication>
    <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 Response
{
    "authentication": true,
    "defaultUser": "user1",
    "description": "description",
    "emailAddr": "jane.doe@stonebranch.com",
    "exportReleaseLevel": "7.2.0.0",
    "exportTable": "ops_email_connection",
    "imap": null,
    "imapPort": null,
    "imapSsl": true,
    "imapStarttls": null,
    "name": "Email Connection 1",
    "opswiseGroups": null,
    "retainSysIds": true,
    "smtp": "server1",
    "smtpPort": 4567,
    "smtpSsl": true,
    "smtpStarttls": false,
    "systemConnection": true,
    "sysId": "62701879a6264107bb757a952bcc65cc",
    "trashFolder": null,
    "type": "Outgoing",
    "version": 1
}