OX Facade API (1.6.8)

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
facade_accounts_crud new endpoints for create, update, deletion of accounts 1.0.12, 1.2.3, 1.4.0, 1.6.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

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
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

post /v1/auth/login
https://facade.open-xchange.com/services/api-facade/v1/auth/login

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
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

200

A JSON object.

307

Signals a redirect on login to another Mobile API Facade/middleware instance.

400

The request failed.

401

The Login failed.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "username": "string",
  • "password": "secret",
  • "clientId": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "session": "string",
  • "capabilities":
    [
    ],
  • "properties":
    {
    }
}

Invalidates the session

post /v1/auth/logout
https://facade.open-xchange.com/services/api-facade/v1/auth/logout

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
push
object (PushUnsubscribeRequestBody)

Responses

200

The session has been deleted.

403

The session could not be deleted.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "push":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

accounts

Returns the list of mail accounts

get /v1/accounts
https://facade.open-xchange.com/services/api-facade/v1/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

200

The list of ids of mail accounts.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accounts":
    [
    ]
}

Autoconfigure account by email address

post /v1/accounts/autoconfig
https://facade.open-xchange.com/services/api-facade/v1/accounts/autoconfig

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
mailAddress
required
string
password
required
string
forceInsecureConnection
boolean
Default: false

Responses

200

A template for the account to be used by the client with all needed server configurations.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "mailAddress": "string",
  • "password": "string",
  • "forceInsecureConnection": false
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "account":
    {
    }
}

Returns the list of mail account IDs

get /v1/accounts/ids
https://facade.open-xchange.com/services/api-facade/v1/accounts/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

200

The list of ids of mail accounts.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accounts":
    [
    ]
}

Return a specific mail account

get /v1/accounts/{accountId}
https://facade.open-xchange.com/services/api-facade/v1/accounts/{accountId}

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

200

The account data.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "account":
    {
    }
}

Return a specific mail account

get /v2/accounts
https://facade.open-xchange.com/services/api-facade/v2/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

200

The account data.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accounts":
    [
    ]
}

Creates a new mail account

post /v2/accounts
https://facade.open-xchange.com/services/api-facade/v2/accounts

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
id
string
accountName
required
string
personalName
string
login
string
password
string
primaryAddress
string
aliases
Array of object (AliasCto)
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
string
inboxFolderId
string
archiveFolderId
string
unifiedInboxEnabled
boolean

Responses

200

The account data.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "accountName": "string",
  • "personalName": "string",
  • "login": "string",
  • "password": "string",
  • "primaryAddress": "string",
  • "aliases":
    [
    ],
  • "mailProtocol": "imap",
  • "mailServer": "string",
  • "mailPort": 0,
  • "mailSecure": true,
  • "mailStartTLS": true,
  • "mailOauth": "string",
  • "mailDisabled": false,
  • "transportProtocol": "string",
  • "transportAuth": "string",
  • "transportServer": "string",
  • "transportPort": 0,
  • "transportLogin": "string",
  • "transportSecure": true,
  • "transportStartTLS": true,
  • "transportOauth": "string",
  • "transportDisabled": false,
  • "spamHandler": "string",
  • "rootFolder": "string",
  • "trashFolder": "string",
  • "sentFolder": "string",
  • "draftsFolder": "string",
  • "spamFolder": "string",
  • "confirmedSpamFolder": "string",
  • "confirmedHamFolder": "string",
  • "inboxFolderId": "string",
  • "archiveFolderId": "string",
  • "unifiedInboxEnabled": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "account":
    {
    }
}

Return a specific mail account

get /v2/accounts/{accountId}
https://facade.open-xchange.com/services/api-facade/v2/accounts/{accountId}

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

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

200

The account data.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "account":
    {
    }
}

Update a mail account

put /v2/accounts/{accountId}
https://facade.open-xchange.com/services/api-facade/v2/accounts/{accountId}

Updates a mail account and returns it again.

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.

Request Body schema: application/json
id
string
accountName
required
string
personalName
string
login
string
password
string
primaryAddress
string
aliases
Array of object (AliasCto)
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
string
inboxFolderId
string
archiveFolderId
string
unifiedInboxEnabled
boolean

Responses

200

The account data.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "accountName": "string",
  • "personalName": "string",
  • "login": "string",
  • "password": "string",
  • "primaryAddress": "string",
  • "aliases":
    [
    ],
  • "mailProtocol": "imap",
  • "mailServer": "string",
  • "mailPort": 0,
  • "mailSecure": true,
  • "mailStartTLS": true,
  • "mailOauth": "string",
  • "mailDisabled": false,
  • "transportProtocol": "string",
  • "transportAuth": "string",
  • "transportServer": "string",
  • "transportPort": 0,
  • "transportLogin": "string",
  • "transportSecure": true,
  • "transportStartTLS": true,
  • "transportOauth": "string",
  • "transportDisabled": false,
  • "spamHandler": "string",
  • "rootFolder": "string",
  • "trashFolder": "string",
  • "sentFolder": "string",
  • "draftsFolder": "string",
  • "spamFolder": "string",
  • "confirmedSpamFolder": "string",
  • "confirmedHamFolder": "string",
  • "inboxFolderId": "string",
  • "archiveFolderId": "string",
  • "unifiedInboxEnabled": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "account":
    {
    }
}

Delete a mail account

delete /v2/accounts/{accountId}
https://facade.open-xchange.com/services/api-facade/v2/accounts/{accountId}

Deletes a mail account given it's ID. The primary mail account cannot get deleted.

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

200

The account was successfully deleted.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

config

Retrieves the configuration values for the user

get /v1/config
https://facade.open-xchange.com/services/api-facade/v1/config

This request returns an object with all the configuration values 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.

Responses

200

The configuration values wrappen in an object.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "deleteDraftOnTransport": true,
  • "purgeOnDeletion": true,
  • "maxUploadSize": 0,
  • "maxUploadAttachmentSize": 0,
  • "capabilities":
    [
    ],
  • "properties":
    {
    },
  • "multipleAccountsEnabled": false
}

contacts

Retrieves all contacts

get /v1/contacts
https://facade.open-xchange.com/services/api-facade/v1/contacts

This request returns a list of all contacts a user knowns. These might be real contacts or distribution lists.

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

200

The list of contacts is successfully returned.

Response samples

application/json
Copy
Expand all Collapse all
{ }

folders

Creates a folder

post /v1/folders
https://facade.open-xchange.com/services/api-facade/v1/folders

This request creates a new folder. You need to give it the ID of the parent folder and the name of the folder to create.

Not all names for folders are allowed, allowed names are middleware specific. Requests with not allowed names return a failure.

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
parentFolderId
required
string
Default: "default0/INBOX"
name
required
string

Responses

201

The folder has been successfully created.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "parentFolderId": "default0/INBOX",
  • "name": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "string",
  • "name": "string"
}

Updates a folder

put /v1/folders
https://facade.open-xchange.com/services/api-facade/v1/folders

This request updates a folder. You need can either rename an existing folder or move it to another parent folder.

Not all names for folders are allowed, allowed names are middleware specific. Requests with not allowed names return a failure.

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
folderId
required
string
Default: "default0/INBOX"
newParentFolderId
string
Default: "default0/INBOX"
newName
string

Responses

200

The folder has been successfully updated.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "newParentFolderId": "default0/INBOX",
  • "newName": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "string"
}

Deletes a folders

delete /v1/folders
https://facade.open-xchange.com/services/api-facade/v1/folders

This request deletes a given folder

Standard folders are not allowed to get deleted.

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
folderId
required
string
Default: "default0/INBOX"

Responses

200

The folder has been successfully created.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Returns all mail folders

get /v1/folders/mail
https://facade.open-xchange.com/services/api-facade/v1/folders/mail

This request returns all accounts together with the mail folders in them.

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.

Accept-Language
string
Default: "en-US"

The locale of the translatable strings for the response.

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.

If-None-Match
string

The caching key previously returned in an ETag header.

Responses

200

A JSON object.

304

The data don't changed since the last request.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "accounts":
    [
    ]
}

Checks if there are new mails in a given mail folders

get /v1/folders/mail/checknew
https://facade.open-xchange.com/services/api-facade/v1/folders/mail/checknew

This request does an EXAMINE call on the mail backend and checks if there are new mails in a specific folder. It returns the current UIDVALIDITY and NEXT value returned by the EXAMINE request.

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
folderId
required
string
Default: "default0/INBOX"
validity
required
string
next
required
string

Responses

200

There are new mails available. A JSON object with the new UIDVALIDITY and NEXT is returned.

304

There are no new mails available. A JSON object with the old UIDVALIDITY and NEXT is returned.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "validity": "string",
  • "next": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "validity": "string",
  • "next": "string"
}

Deletes all mails in a given folder

delete /v1/folders/clear
https://facade.open-xchange.com/services/api-facade/v1/folders/clear

This request deletes all mails in a given folder and depending on configuration moves to the trash folder. If the trash folder is cleared the mails are permanently deleted.

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
folderId
required
string
Default: "default0/INBOX"

Responses

200

The mails in the given folder are deleted.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

mails

Returns stubs for a specific mail folder

post /v1/mails/stubs
https://facade.open-xchange.com/services/api-facade/v1/mails/stubs

All mails are returned in pre-calculated MailThreadCto objects.

When using this request a field validity containing the IMAP UIDVALIDITY value and a field next containing the IMAP NEXT value.

With the validity the client can make sure the folder he retrieved with the given folder ID is still the same folder. If the validity in the response is different to a previously retrieved validity this means this is a new completely new folder with the same name and ID. All clients need to delete all local data about this folder and completely sync it again.

The clients also need to store next value locally. If the newly retrieved next value is different to a previously retrieved value this means that the folder contains new mails which are not retrieved yet.

State changes (flags, color) are only available in the retrieved stubs. There is no indicator that these changed. All stubs need to be checked for changed.

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.

If-None-Match
string

The caching key previously returned in an ETag 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
folderId
required
string
Default: "default0/INBOX"
threaded
boolean
Default: true

Responses

200

A JSON object.

304

The data don't changed since the last request.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "threaded": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "threads":
    [
    ]
}

Returns new stubs for a specific mail folder

post /v1/mails/stubs/new
https://facade.open-xchange.com/services/api-facade/v1/mails/stubs/new

All mails are returned in pre-calculated MailThreadCto objects.

When using this request a field validity containing the IMAP UIDVALIDITY value and a field next containing the IMAP NEXT value.

With the validity the client can make sure the folder he retrieved with the given folder ID is still the same folder. If the validity in the response is different to a previously retrieved validity this means this is a new completely new folder with the same name and ID. All clients need to delete all local data about this folder and completely sync it again.

The clients also need to store next value locally. If the newly retrieved next value is different to a previously retrieved value this means that the folder contains new mails which are not retrieved yet.

State changes (flags, color) are only available in the retrieved stubs. There is no indicator that these changed. All stubs need to be checked for changed.

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.

If-None-Match
string

The caching key previously returned in an ETag 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
folderId
required
string
Default: "default0/INBOX"
lastReceivedDate
required
integer <int64>
Default: 0
threaded
boolean
Default: true

Responses

200

A JSON object.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "lastReceivedDate": 0,
  • "threaded": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "threads":
    [
    ]
}

Returns envelope data for specific mails

post /v1/mails/envelopes
https://facade.open-xchange.com/services/api-facade/v1/mails/envelopes
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

A JSON object.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "mails":
    [
    ]
}

Returns new envelope data for a specific folder

post /v1/mails/envelopes/new
https://facade.open-xchange.com/services/api-facade/v1/mails/envelopes/new
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
folderId
required
string
Default: "default0/INBOX"
lastReceivedDate
required
integer <int64>
Default: 0
threaded
boolean
Default: true

Responses

200

A JSON object.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "lastReceivedDate": 0,
  • "threaded": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "mails":
    [
    ]
}

Returns all mail data for specific mails

post /v1/mails/complete
https://facade.open-xchange.com/services/api-facade/v1/mails/complete
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
folderId
required
string
Default: "default0/INBOX"
mailId
required
string
maximumTeaserLength
integer

Responses

200

A JSON object.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailId": "string",
  • "maximumTeaserLength": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "mails":
    [
    ]
}

mail actions

Deletes mails in a specific folder

delete /v1/mails/delete
https://facade.open-xchange.com/services/api-facade/v1/mails/delete
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string
purge
boolean
Default: false

Responses

200

The mails are deleted.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ],
  • "purge": false
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "trashFolderId": "string",
  • "mailIds":
    [
    ]
}

Moves mails to a specific folder

post /v1/mails/move
https://facade.open-xchange.com/services/api-facade/v1/mails/move
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string
targetFolderId
required
string

Responses

200

On success this endpoint returns the list of new IDs for the moved mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ],
  • "targetFolderId": "string"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "mailIds":
    [
    ]
}

Sets colors of mails

post /v1/mails/color
https://facade.open-xchange.com/services/api-facade/v1/mails/color
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
folderId
required
string
Default: "default0/INBOX"
color
required
integer
mailIds
required
Array of string

Responses

200

The color has been set to all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "color": 0,
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

mail flag actions

Sets the 'answered' flag for a set of mails in a specific folder

post /v1/mails/flags/answered
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/answered
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been set in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Clears the 'answered' flag for a set of mails in a specific folder

delete /v1/mails/flags/answered
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/answered
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been cleared in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Sets the 'deleted' flag for a set of mails in a specific folder

post /v1/mails/flags/deleted
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/deleted
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been set in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Clears the 'deleted' flag for a set of mails in a specific folder

delete /v1/mails/flags/deleted
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/deleted
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been cleared in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Sets the 'draft' flag for a set of mails in a specific folder

post /v1/mails/flags/draft
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/draft
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been set in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Clears the 'draft' flag for a set of mails in a specific folder

delete /v1/mails/flags/draft
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/draft
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been cleared in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Sets the 'flagged' flag for a set of mails in a specific folder

post /v1/mails/flags/flagged
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/flagged
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been set in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Clears the 'flagged' flag for a set of mails in a specific folder

delete /v1/mails/flags/flagged
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/flagged
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been cleared in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Sets the 'forwarded' flag for a set of mails in a specific folder

post /v1/mails/flags/forwarded
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/forwarded
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been set in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Clears the 'forwarded' flag for a set of mails in a specific folder

delete /v1/mails/flags/forwarded
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/forwarded
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been cleared in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Sets the 'unread' flag for a set of mails in a specific folder

post /v1/mails/flags/unread
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/unread
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been set in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Clears the 'unread' flag for a set of mails in a specific folder

delete /v1/mails/flags/unread
https://facade.open-xchange.com/services/api-facade/v1/mails/flags/unread
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
folderId
required
string
Default: "default0/INBOX"
mailIds
required
Array of string

Responses

200

The flag has been cleared in all respective mails.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "folderId": "default0/INBOX",
  • "mailIds":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

manifest

Returns a manifest about the public available server configuration

get /v1/manifest
https://facade.open-xchange.com/services/api-facade/v1/manifest

Responses

200

The manifest data.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "allowOnlyUsernameForLogin": false
}

users

Returns user data for the current user

get /v1/users/current
https://facade.open-xchange.com/services/api-facade/v1/users/current

Returns information about the currently logged in user. This contains things like display name, email address, avatar image url, etc.

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.

If-None-Match
string

The caching key previously returned in an ETag header.

Responses

200

A JSON object.

304

The data don't changed since the last request.

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "firstName": "string",
  • "lastName": "string",
  • "displayName": "string",
  • "image": "string",
  • "imageType": "string"
}

version

Retrieve version information about the running system

get /v1/version
https://facade.open-xchange.com/services/api-facade/v1/version

Responses

200

The version information.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "version": "string",
  • "commitHash": "string",
  • "middlewareVersion": "string"
}

push

Subscribe to push events

post /v1/push/subscribe
https://facade.open-xchange.com/services/api-facade/v1/push/subscribe
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
transport
required
string
Enum:"apn" "gcm" "wns"
token
required
string
topics
required
Array of string
Items Enum:"ox:mail:new" "ox:mail:*"

Responses

200

Subscribing was successful

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "transport": "apn",
  • "token": "string",
  • "topics":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}

Unsubscribe from push events

post /v1/push/unsubscribe
https://facade.open-xchange.com/services/api-facade/v1/push/unsubscribe
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
transport
required
string
Enum:"apn" "gcm" "wns"
token
required
string
topics
Array of string
Items Value:"mail"

Responses

200

Unsubscribing was successful

400

The request failed.

401

The Session is invalid.

500

An internal server error occured.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "transport": "apn",
  • "token": "string",
  • "topics":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error": "string",
  • "message": "string",
  • "categories":
    [
    ]
}