Mailbox API – Folders

Axigen Documentation

The Mailbox API is available starting with Axigen X4 (10.4).

List

Query parameters

Name

Type

Required

Values

Description

type

String

"all", "mails", "events", "tasks", "notes", "contacts"

The folder type

Default value: "all"

Note: “public_container”, “shared_namespace” and “shared_container” are not available for this property

accessMode

String

"all", "local", "public", "shared"

List only folders matching this access mode

Default value: "all"

syncTokenOnly

Boolean

When true, the endpoint should only return the syncToken without the folder list.

Default value: false

Response

List Delta

Query parameters

Name

Type

Required

Values

Description

accessMode

String

"all", "local", "public", "shared"

List only folders matching this access mode

Default value: "all"

syncToken

String

The synchronization token returned by the previous listing; if missing then an initial round of listing is started (all folders are reported as new items)

Default value: empty string

Response

Notes:

  • Order of events is important, so the client must process folder delta events in the order sent by the server

  • “newFolder” event contains all information of a FolderInstance plus ID validity and owning container ID

  • If a folder ID validity changes the client must discard any cached content data before the next folder mails synchronization process

  • In case of a “resetContainer” event the client must mark for deletion all folders with ‘containerID’ equal with the ‘id’ field of the event (not the ‘containerId’ !) and remove them from the folder tree (but not from content cache!). The folder identified by the event remains in the folder tree! If a ‘newFolder’ event is received for one of these folders, the folder is added in the appropriate place in the folder tree and the deletion mark is removed; the client should keep the cached content data (assuming ID validity has not changed) - treat the ‘newFolder’ event as a regular ‘changedFolder’ event from content point of view. When all synchronization events are processed any remaining folders marked for deletion will be removed from content cache (from folder tree they are already removed)

  • In case of a “removeContainer” event the client must remove all folders with ‘containerID’ equal with the ‘id’ field of the event from both folder tree and content cache (as if “removeFolder” events are received for all of them). Also the folder specified in the event will be removed from the folder tree

  • Synchronization tokens obtained using one access mode should not be used with another access mode, even though it is not illegal and should give proper response if the scope is enlarged (for example using a ‘local’ synchronization token with an ‘all’ access mode should report only the delta changes for local folders and all public and shared folders reported as “newFolder” events).

  • The client should compare the ‘syncToken' field for each “newFolder” or “changedFolder” events with its cached synchronization token in order to decide if content (emails) synchronization is necessary.

Create

Request body (JSON)

Name

Type

Required

Values

Description

name

String

*


The new folder name

type

String


"mails", "events", "tasks", "notes", "contacts"

The folder type

Default value: "mails" when parentId is not present or when it is equal to the root folder. Otherwise, the default value will be equal to the type of the parent folder.

Note: “public_container”, “shared_namespace” and “shared_container” are not available for this property

Note: if the parentId is sent and is not the root folder Id, then type should not be sent. In this case, if the type is sent and does not match the parent folder type, the request will result in a 400 error.

parentId

String

The parent folder ID

Default value: the folder container ID (root folder)

To create folders in the root folder, you can either omit the parentId property or use the folderContainerId provided in Account Info.

Response

If successful, the response will contain an instance of folder.

Update

URL parameters

Name

Type

Description

folderId

String

The folder id

Request body (JSON)

Name

Type

Required

Values

Description

name

String

*

The new folder name

Response

If successful, the response will contain an instance of folder.

Delete

Folder deletion takes into account the deleteToTrash account setting:

  • if deleteToTrash is true (which is default), then

    • if the folder is not already in Trash, deleting it will actually move it to Trash

    • otherwise, if the folder already in Trash, it's permanently deleted.

  • else

    • the folder is permanently deleted.

URL parameters

Name

Type

Description

folderId

String

The folder id

Response

If successful, the response will be empty.

Move

URL parameters

Name

Type

Description

folderId

String

The folder id

Request body (JSON)

Name

Type

Required

Values

Description

parentId

String

*

The new parent folder ID; the container ID (root folder) for top level folders.

Response

If successful, the response will contain an instance of folder.