OX Facade API (1.14.1)

Download OpenAPI specification:Download

Data formats

Some data formats need some clarification and are not obvious from the API itself.

Timestamps

Timestamps are in milliseconds since 01/01/1970 UTC +0:00.

URLs

URLs can be either an absolute URL or an absolute URL path. In case of an absolute URL path the client is expected to prepend the configured scheme and hostname.

User agents

To be able to distinguish different mail clients in the facade all clients must send a specific user agent. This user agent is build up with a branding identifier, an OS identifier, a string identifying the type of client, a version of the client, version information about the operating system running on and the name of the device running on.

The complete user agent has the format:

{branding name}.{OS identifier}.Mail/{client version} (OS: {OS version}; device: {device identifier})

The default branding name is OpenXchange.

The OS specific identifier is a short string as described in the following table.

Platform OS identifier
Android Android
iOS iOS
OS X OSX
Windows Windows
Windows 10 Mobile WP
Swagger Swagger

If your client is not listed in the above table please contact the facade developers.

Version numbers are in semantic versioning scheme.

Examples are

OpenXchange.Android.Mail/1.0+1234 (OS: 7.0; device: Samsung/GT9700)
OpenXchange.iOS.Mail/1.0.6 (OS: 10.0.3; device: iPhone 7 Plus)

Logging

To be able to track users and requests among different components (app, Mobile API Facade, middleware) the clients can use the headers 'X-Context-ID', 'X-User-ID' and 'X-Tracking-ID'. These headers should be included in all requests, excpet the authentication request cannot include 'X-Context-ID' and 'X-User-ID' as these values are not yet known. The values for 'X-Context-ID' and 'X-User-ID' are returned in the login request and are the respective values of contextId and userId attributes. The value 'X-Tracking-ID' is a client generated unique token per request. It's recommended to use a string representation of a UUID.

Capabilities

The Mobile API Facade returns the capabilities configured in the Middleware on successful login and on the configuration endpoint. In addition to these capabilities the Mobile API Facade also defines its own set to signal availability of specific features. To make sure we don't get naming conflicts capabilities only known to the Mobile API Facade they are prefixed with 'facade_'.

The following capabilities are specific to the Mobile API Facade:

Name Description Versions
facade_accounts_sync new endpoints for syncing multiple accounts 1.0.9, 1.2.0, 1.4.0, 1.6.0, 1.8.0
facade_accounts_crud new endpoints for create, update, deletion of accounts 1.0.12, 1.2.3, 1.4.0, 1.6.0, 1.8.0
facade_multiple_accounts_enabled multiple accounts support is enabled on the Mobile API Facade 1.0.13, 1.2.4, 1.4.2, 1.6.0, 1.8.0

Error codes

In general the errors are delegated from the middleware to the facade. The facade wraps them in a common format and sends them to the client. The error codes for errors returned by the middleware can be found at https://oxpedia.org/wiki/index.php?title=Error_list.

The facade itself provides the following error codes:

Code Information
1 Invalid credentials
2 Missing header
3 Missing parameter
4 Missing cookie
5 Invalid User-Agent header
6 Too many sessions
7 Account not found
8 Empty array not allowed
9 Invalid account data
10 Redirect to another AppSuite server
11 Database update...try again later
12 Password of secondary mail account changed
13 Permission denied
900 Client too old
999 Internal server error

The response is a JSON string with two string fields:

  • error (contains the error code created by the middleware or the facade)
  • message (further information regarding the occured error)

authentication

Authenticates the user

This request performs the authentication for the user.

header Parameters
X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

Request Body schema: application/json

A JSON object.

username
required
string
password
required
string
Default: "secret"
clientId
string

String to identify the client. This must be an a string with only ascii characters and/or digits.

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "secret",
  • "clientId": "string"
}

Response samples

Content type
application/json
{
  • "session": "string",
  • "capabilities": [
    ],
  • "properties": {
    }
}

Invalidates the session

This request performs the logout for the user.

header Parameters
X-Session
required
string

A session ID previously obtained from the login module.

X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

X-Tracking-ID
string

The tracking ID the client generated to be able to track request from client to middleware. To be able to track requests through the Mobile API Facade to the middleware properly it must be unique per request. Its advised to use a UUID in its string representation.

X-Context-ID
string

The context ID of the logged in user.

X-User-ID
string

The user ID of the logged in user.

Request Body schema: application/json

A JSON object.

object (PushUnsubscribeRequestBody)

Responses

Request samples

Content type
application/json
{
  • "push": {
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": "string",
  • "categories": [
    ]
}

accounts

Returns the list of mail accounts

This returns a list of mail accounts.

header Parameters
X-Session
required
string

A session ID previously obtained from the login module.

X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

X-Tracking-ID
string

The tracking ID the client generated to be able to track request from client to middleware. To be able to track requests through the Mobile API Facade to the middleware properly it must be unique per request. Its advised to use a UUID in its string representation.

X-Context-ID
string

The context ID of the logged in user.

X-User-ID
string

The user ID of the logged in user.

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Autoconfigure account by email address

This request takes an email address and a password and tries to find the server settings needed.

header Parameters
X-Session
required
string

A session ID previously obtained from the login module.

X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

X-Tracking-ID
string

The tracking ID the client generated to be able to track request from client to middleware. To be able to track requests through the Mobile API Facade to the middleware properly it must be unique per request. Its advised to use a UUID in its string representation.

X-Context-ID
string

The context ID of the logged in user.

X-User-ID
string

The user ID of the logged in user.

Request Body schema: application/json

A JSON object.

mailAddress
required
string
password
required
string
forceInsecureConnection
boolean
Default: false

Responses

Request samples

Content type
application/json
{
  • "mailAddress": "string",
  • "password": "string",
  • "forceInsecureConnection": false
}

Response samples

Content type
application/json
{
  • "account": {
    }
}

Returns the list of mail account IDs

This returns a list of ids of mail accounts. To retrieve the actual mail account data these informations need to be requests subsequently.

Names/ids are given by the middleware. The main/primary account is usually named '0'.

header Parameters
X-Session
required
string

A session ID previously obtained from the login module.

X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

X-Tracking-ID
string

The tracking ID the client generated to be able to track request from client to middleware. To be able to track requests through the Mobile API Facade to the middleware properly it must be unique per request. Its advised to use a UUID in its string representation.

X-Context-ID
string

The context ID of the logged in user.

X-User-ID
string

The user ID of the logged in user.

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Return a specific mail account

This returns a specific mail account with all its information and the related folders including the info about the standard forlders.

path Parameters
accountId
required
string

The id of the requested account of the current user

header Parameters
X-Session
required
string

A session ID previously obtained from the login module.

X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

X-Tracking-ID
string

The tracking ID the client generated to be able to track request from client to middleware. To be able to track requests through the Mobile API Facade to the middleware properly it must be unique per request. Its advised to use a UUID in its string representation.

X-Context-ID
string

The context ID of the logged in user.

X-User-ID
string

The user ID of the logged in user.

Responses

Response samples

Content type
application/json
{
  • "account": {
    }
}

Returns a list of mail accounts

This returns a list of mail accounts with all its information and the related folders including the info about the standard folders.

header Parameters
X-Session
required
string

A session ID previously obtained from the login module.

X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

X-Tracking-ID
string

The tracking ID the client generated to be able to track request from client to middleware. To be able to track requests through the Mobile API Facade to the middleware properly it must be unique per request. Its advised to use a UUID in its string representation.

X-Context-ID
string

The context ID of the logged in user.

X-User-ID
string

The user ID of the logged in user.

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ]
}

Creates a new mail account

This creates a mail account and returns it again.

header Parameters
X-Session
required
string

A session ID previously obtained from the login module.

X-User-Agent
required
string
Default: OpenXchange.Swagger.Mail/2.0.0 (device: unknown, OS: unknown)

A user agent string. Has to be named 'User-Agent' in clients but not all web browsers allow setting this header.

X-Tracking-ID
string

The tracking ID the client generated to be able to track request from client to middleware. To be able to track requests through the Mobile API Facade to the middleware properly it must be unique per request. Its advised to use a UUID in its string representation.

X-Context-ID
string

The context ID of the logged in user.

X-User-ID
string

The user ID of the logged in user.

Request Body schema: application/json

A JSON object.

id
string
accountName
required
string
personalName
string
login
string
password
string
primaryAddress
string
Array of objects (AliasCto) [ items ]
forceInsecureConnection
boolean
Default: false
ignoreInvalidTransport
boolean
Default: false
mailProtocol
required
string
Enum: "imap" "pop3"
mailServer
required
string
mailPort
integer
mailSecure
boolean
mailStartTLS
boolean
mailOauth
string
mailDisabled
boolean
Default: false
transportProtocol
string
transportAuth
string
transportServer
string
transportPort
integer
transportLogin
string
transportSecure
boolean
transportStartTLS
boolean
transportOauth
string
transportDisabled
boolean
Default: false
spamHandler
string
rootFolder
string
trashFolder
string
sentFolder
string
draftsFolder
string
spamFolder
string
confirmedSpamFolder
string
confirmedHamFolder
<