Exchange Public Folders (Rest API)

From Rackspace Email & Apps API
Jump to: navigation, search

v2 - Current

This resource supports enabling, adding, updating and removing public folders on a specified domain with both XML and JSON.

Data Model

Public Folder Domain Settings

Field Name Data Type Verbs Description
Enabled Boolean GET True if public folders are enabled, false otherwise
Limits Object GET Object containing information about the maximum number of public folders allowed on the domain
Usage Object GET Object containing information about the current number of public folders provisioned on the domain
Limits
Field Name Data Type Verbs Description
MaxFolderCount Integer GET Maximum number of public folders allowed on the domain
MaxFolderStorageSize Size GET Object containing information about the maximum storage size of public folders allowed on the domain
Usage
Field Name Data Type Verbs Description
CurrentFolderCount Integer GET Number of public folders provisioned on the domain

Public Folder

Field Name Data Type Verbs Description
Id* String GET Exchange identifier for and individual public folder.
Name String GET, POST, PUT Public folder name
Path String GET Path to public folder
ParentId String GET, POST, PUT Exchange identifier of the parent public folder
ParentPath String GET Path of the parent public folder
HasChildren Boolean GET True if the public folder has child folders, false otherwise
Type String GET, POST Type of public folder (Calendar, Contacts, Mail, Note, Task)
MailEnabled Boolean GET, POST, PUT True if the public folder is mail enabled, false otherwise
MailData Object GET, POST, PUT Object containing mail information about a mail enabled public folder. This field is only included for mail enabled public folders.
UsageStatistics Object GET Object containing usage statistics about a public folder
Status Object GET Status of a public folder.

*Various operations on a public folder can cause the Id to change over time.

Mail Data
Field Name Data Type Verbs Description
DisplayName String GET, POST, PUT Display name of mail enabled public folder
PrimarySmtpAddress String GET Primary SMTP address of mail enabled public folder
HiddenFromAddressLists Boolean GET, POST, PUT True if mail enabled public folder should be hidden from address lists, false otherwise
CreationTime String GET Date and time public folder was mail enabled formatted as ISO 8601
LastModificationTime String GET Date and time public folder mail data was last modified formatted as ISO 8601
Addresses Array of Addresses PUT, POST Array of address objects used to add or remove email addresses to a mail enabled public folder
Address
Field Name Data Type Verbs Description
Address String GET, POST, PUT Full email address being added or removed
Protocol String GET, POST, PUT Email protocol to be used. Note: Currently only supports smtp.
Primary Boolean GET, POST, PUT True should be set as primary email address, false otherwise. Note: Mail enabled public folders must have always have one primary address set at all times.
Action String PUT Specifies what action to perform on a given email address. Options are add, update or remove.
Usage Statistics
Field Name Data Type Verbs Description
CreationTime String GET Date and time public folder was created formatted as ISO 8601
LastModificationTime String GET Date and time public folder was last modified formatted as ISO 8601
TotalItemSize Size GET Object containing the total size of all items stored for the public folder
ItemCount Integer GET Total number of child folders for the public folder
Status
Field Name Data Type Verbs Description
State** String GET Status of a public folder. Can be ready, pending or error.
Operation String GET Represents the operation type that failed (create, update, delete). This field only applies to an Error status.
RequestId String GET Represents the request id of the operation that failed. This field only applies to an Error status.

**States

  • A ready state means that there are no scheduled operations for the object.
  • A pending state signifies the object is being modified. A public folder cannot be updated or deleted while it is in a pending state.
  • An error state represents that there was a problem with the previous operation. To clear an error, delete the related request using the RequestId field included in the Status object utilizing the Delete Public Folder Request route. Error information is only available for a short period time and will eventually be cleared resulting in the public folder returning to a ready state. Also note, that a public folder in an error state is still a fully functioning public folder that can be updated and deleted.

Exchange Response

Field Name Data Type Verbs Description
StatusCode Integer GET API response code of the related request
StatusToken String GET Unique token used to monitor the progress of an API request

Exchange Request

Field Name Data Type Verbs Description
Id Integer GET Unique identifier representing a request
Status String GET Current status of the request. Can be ready, pending or error.
Operation String GET Represents the operation type that failed (create, update, delete)
LastModified String GET Date and time request was last updated
Target Object GET An object representing details about the public folder being interacted with
Request Object GET A copy of the data sent with the original request
Error Object GET An object representing error details about the request. This object only exists when the request is in an error state.
Target
Field Name Data Type Verbs Description
Id Integer GET Represents the Id of the public folder being altered for the request
Type String GET Represents the type of request
Error
Field Name Data Type Verbs Description
StatusCode Integer GET The API response code of the request in error
Message String GET Details about the errored request

Size Model

Field Name Data Type Verbs Description
Value Integer GET Numerical value
Unit String GET Unit of measure

Read Domain Settings

Verb GET
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/publicFolders/
Description Returns domain level settings for public folders on the domain.
Model Domain Settings

HTTP Codes

Code Condition
200 OK The information was successfully retrieved and Public Folders are currently enabled on the domain.
404 Not Found The domain does not exist or the domain does not have Exchange. Inspect the itemNotFondFault for more detail. 
Request:
GET https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders

Response:
200 OK
{
    "Enabled": true,
    "Limits": {
        "MaxFolderCount": 25,
        "MaxFolderStorageSize": {
            "Value": 250,
            "Unit": "MB"
        }
    },
    "Usage": {
        "CurrentFolderCount": 19
    }
}

Enable (JSON Only)

Verb POST
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/publicFolders
Description Use this route to enable public folders for the specified domain.
Note To enabled public folders on the domain, the body of the request must contain an empty JSON object. This route does not support XML.

HTTP Codes

Code Condition
202 Accepted The request has been accepted and will be processed.
404 Not Found The domain does not exist or the domain does not have Exchange. Inspect the itemNotFondFault for more detail. 
Request:
GET https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders
{}

Response:
202 Accepted
{
    "StatusCode": 202,
    "StatusToken": "54b9561a2c50b41e0833b437"
}

Create

Verb POST
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/publicFolders
Description Use this route to create a public folder.
Note Newly created public folders will not show up in the child listing until they are fully provisioned.

HTTP Codes

Code Condition
202 Accepted The request has been accepted and will be processed.
400 Bad Request The request has is not formatted correctly or missing required information. Inspect the validationFault response for more detail.
404 Not Found The domain does not exist or the domain does not have Exchange. Inspect the itemNotFondFault for more detail.
409 Conflict Duplicated creation request. Inspect the conflictFault response for more detail. 
Request:
POST https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders
{
  "Name" : "Mail Enabled Test Folder",
  "ParentId" : "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2",
  "Type" : "mail",
  "MailEnabled" : true,
  "MailData" : {
    "DisplayName" : "Mail Enabled Test Folder",
    "HiddenFromAddressLists" : false,
    "Addresses": [
      {
        "Address": "mailenabledtestfolder@example.com",
        "Protocol": "smtp",
        "Primary": true
      }
    ]
  }
}

Response:
202 Accepted
{
    "StatusCode": 202,
    "StatusToken": "54b9561a2c50b41e0833b437"
}

Read

Verb GET
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/publicFolders/{public_folder_id}
Description Use this route to get information about a public folder.
Model Public Folder

HTTP Codes

Code Condition
200 OK Returns a public folder.
404 Not Found The domain does not exist, the domain does not have Exchange or the request public folder does not exist. Inspect the itemNotFondFault for more detail. 
Request:
GET https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD6HpX-1SJxU-_bhN3jiR1fAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2jgAAAA2

Response:
200 OK
{
    "Id": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2jgAAAA2",
    "Name": "Mail Enabled Test Folder",
    "Path": "/Parent Folder/Mail Enabled Test Folder/",
    "ParentId": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2",
    "ParentPath": "/",
    "HasChildren": false,
    "Type": "mail",
    "MailEnabled": true,
    "MailData": {
        "DisplayName": "Mail Enabled Test Folder",
        "PrimarySmtpAddress": "mailenabledtestfolder@example.com",
        "HiddenFromAddressLists": false,
        "CreationTime": "2015-01-17T00:35:42Z",
        "LastModificationTime": "2015-01-17T00:36:44Z"
    },
    "UsageStatistics": {
        "CreationTime": "2015-01-16T18:35:33Z",
        "LastModificationTime": "2015-01-16T19:36:28Z",
        "TotalItemSize": {
            "Value": 0,
            "Unit": "MB"
        },
        "ItemCount": 0
    },
    "Status": {
       "State": "error",
       "Operation": "update",
       "RequestId": "54ad74692c50b41ffcaa418d"
    }
}

List Public Folder Children

Verb GET
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/publicFolders/{public_folder_id}/children
Description Use this route to list child folders.
Model Public Folder Listing

HTTP Codes

Code Condition
200 OK Returns a list of public folder children
404 Not Found The domain does not exist or the domain does not have Exchange. Inspect the itemNotFoundFault for more detail. 
Request:
GET https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2/children

Response:
200 OK
{
    "Sort": "asc",
    "Offset": 0,
    "Size": 50,
    "Total": 3,
    "Items": [
        {
            "Id": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2kAAAAA2",
            "Name": "Child Folder 1",
            "Path": "/Folder 1/Mail Enabled Test Folder/Child Folder 1/",
            "ParentId": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2jgAAAA2",
            "ParentPath": "/Folder 1/Mail Enabled Test Folder/",
            "HasChildren": false,
            "Type": "mail",
            "MailEnabled": false,
            "UsageStatistics": {
                "CreationTime": "2015-01-16T21:56:56Z",
                "LastModificationTime": "2015-01-16T21:56:56Z",
                "TotalItemSize": {
                    "Value": 0,
                    "Unit": "MB"
                },
                "ItemCount": 0
            },
            "Status": {
                "State": "ready"
            }
        },
        {
            "Id": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2lAAAAA2",
            "Name": "Child Folder 3",
            "Path": "/Folder 1/Mail Enabled Test Folder/Child Folder 3/",
            "ParentId": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2jgAAAA2",
            "ParentPath": "/Folder 1/Mail Enabled Test Folder/",
            "HasChildren": false,
            "Type": "calendar",
            "MailEnabled": false,
            "UsageStatistics": {
                "CreationTime": "2015-01-16T21:57:50Z",
                "LastModificationTime": "2015-01-16T21:57:50Z",
                "TotalItemSize": {
                    "Value": 0,
                    "Unit": "MB"
                },
                "ItemCount": 0
            },
            "Status": {
                "State": "ready"
            }
        },
        {
            "Id": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2kgAAAA2",
            "Name": "Mail Enabled Child Folder 2",
            "Path": "/Folder 1/Mail Enabled Test Folder/Mail Enabled Child Folder 2/",
            "ParentId": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2jgAAAA2",
            "ParentPath": "/Folder 1/Mail Enabled Test Folder/",
            "HasChildren": false,
            "Type": "mail",
            "MailEnabled": true,
            "MailData": {
                "DisplayName": "Mail Enabled Child Folder 2",
                "PrimarySmtpAddress": "child3@example.com",
                "HiddenFromAddressLists": true,
                "CreationTime": "2015-01-17T03:57:25Z",
                "LastModificationTime": "2015-01-17T03:57:54Z"
            },
            "UsageStatistics": {
                "CreationTime": "2015-01-16T21:57:20Z",
                "LastModificationTime": "2015-01-16T21:58:00Z",
                "TotalItemSize": {
                    "Value": 0,
                    "Unit": "MB"
                },
                "ItemCount": 0
            },
            "Status": {
                "State": "ready"
            }
        }
    ]
}

Public Folder Children Filtering

These fields are set as query parameters on the URL

Field Name Description
Offset Starting position of listing
Sort Sort direction by public folder name.
Size Maximum number of public folders to return

Update

Verb PUT
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/publicFolders/{public_folder_id}
Description Use this route to update a public folder.
Model Public Folder

HTTP Codes

Code Condition
202 Accepted The request has been accepted and will be processed.
400 Bad Request The request was invalid. Inspect the validationFault response for more detail.
404 Not Found The domain does not exist or the domain does not have Exchange. Inspect the itemNotFondFault for more detail.
409 Conflict There are existing pending requests for the public folder. Inspect the conflictFault for more detail. 
Request:
PUT https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2
{
  "Name" : "Mail Enabled Test Folder",
  "ParentId" : "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABcUVv_AAAAA2",
  "MailData" : {
    "DisplayName" : "Change Display Name",
    "HiddenFromAddressLists" : true,
    "Addresses": [
      {
        "Address": "mailenabledtestfolder@example.com",
        "Protocol": "smtp",
        "Primary": false,
        "Action": "Remove"
      },
      {
        "Address": "changed_display_name@example.com",
        "Protocol": "smtp",
        "Primary": true,
        "Action": "Add"
      }
    ]
  }
} 

Response:
202 Accepted
{
    "StatusCode": 202,
    "StatusToken": "54b9561a2c50b41e0833b437"
}

Move

  • Set the public folders ParentId to the Id of the new parent.
PUT https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2
{
  "ParentId" : "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABcUVv_AAAAA2"
}

Mail Enable

  • Set the MailEnabled property to true and include the MailData property information. There must be at least one email address included and one email address set as the primary.
PUT https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2
{
  "MailEnabled" : true,
  "MailData" : {
    "DisplayName" : "Some Display Name",
    "HiddenFromAddressLists" : true,
    "Addresses": [
      {
        "Address": "mailenabledtestfolder@example.com",
        "Protocol": "smtp",
        "Primary": true
      }
    ]
  }
}

Mail Disable

  • Set the MailEnabled property to false.
PUT https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2
{
  "MailEnabled" : false
}

Adding/Removing Email Addresses

  • To add or remove email addresses for a public folder, set the Action to Add or Remove.
  • If removing the primary email address, a new primary email address must be added as part of the same request.
  • Only email addresses on the primary domain or domain aliases are allowed.
Request:
PUT https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2
{
  "MailData" : {
    "Addresses": [
        {
          "Address": "mailenabledtestfolder@example.com",
          "Protocol": "smtp",
          "Primary": false,
          "Action": "Remove"
        },
        {
          "Address": "other@example.com",
          "Protocol": "smtp",
          "Primary": true,
          "Action": "Add"
        }
      ]
   }
}

Delete

Verb DELETE
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/publicFolders/{public_folder_id}
Description Use this route to delete a public folder.
Model Public Folder

HTTP Codes

Code Condition
202 Accepted The request has been accepted and will be processed.
404 Not Found The domain does not exist or the domain does not have Exchange. Inspect the itemNotFoundFault for more detail.
409 Conflict A request already exists to delete the public folder. Inspect the conflictFault for more detail. 
Request:
DELETE https://api.emailsrvr.com/v2/domains/example.com/ex/publicFolders/AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABgxHHlgAAAA2

Response:
202 Accepted
{
    "StatusCode": 202,
    "StatusToken": "54b9561a2c50b41e0833b437"
}

Public Folder Requests

Read

Verb GET
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/requests/publicFolders/{request_id}
Description Use this route to get a public folder request
Model Exchange Request

HTTP Codes

Code Condition
200 OK Returns public folder request
404 Not Found The domain does not exist, the domain does not have Exchange or the request id does not exist. Inspect the itemNotFoundFault for more detail. 
Request:
GET https://api.emailsrvr.com/v2/domains/example.com/ex/requests/publicFolders/54ad74692c50b41ffcaa418d

Response:
200 OK
{
    "Id": "54ad74692c50b41ffcaa418d",
    "Status": "error",
    "Operation": "update",
    "LastModified": "2015-01-07T18:01:21Z",
    "Target": {
        "Id": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABcUVuOAAAAA2",
        "Type": "publicfolder"
    },
    "Request": {
        "id": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABcUVuOAAAAA2",
        "parentId": "AQEuAAAD1WUW8Zz97kKsRBRlco1SyAEAOLcEK87Q0Uaq-FAXzNm3JgABcUVv_AAAAA2"
    },
    "Error": {
        "StatusCode": 400,
        "Message": "Some error message."
    }
}

List

Verb GET
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/requests/publicFolders
Description Use this route to get a list public folder requests for a domain
Model Exchange Request

HTTP Codes

Code Condition
200 OK Returns a list of public folder requests
404 Not Found The domain does not exist or the domain does not have Exchange. Inspect the itemNotFoundFault for more detail. 
Request:
GET https://api.emailsrvr.com/v2/domains/example.com/ex/requests/publicFolders

Response:
200 OK
{
    "Offset": 0,
    "Size": 100,
    "Total": 3,
    "Items": [
        {
            "Id": "54b989372c50b40db494f2cd",
            "Status": "completed",
            "Operation": "create",
            "LastModified": "2015-01-16T21:58:02Z",
            "Target": {
                "Id": "AQEuAAAD6HpX-1SJxU-_bhN3jiR1fAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2kgAAAA2",
                "Type": "publicfolder"
            }
        },
        {
            "Id": "54b989492c50b40db494f2ce",
            "Status": "completed",
            "Operation": "create",
            "LastModified": "2015-01-16T21:57:52Z",
            "Target": {
                "Id": "AQEuAAAD6HpX-1SJxU-_bhN3jiR1fAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2lAAAAA2",
                "Type": "publicfolder"
            }
        },
        {
            "Id": "54b989202c50b40db494f2cc",
            "Status": "completed",
            "Operation": "create",
            "LastModified": "2015-01-16T21:56:58Z",
            "Target": {
                "Id": "AQEuAAAD6HpX-1SJxU-_bhN3jiR1fAEAOLcEK87Q0Uaq-FAXzNm3JgABlUc2kAAAAA2",
                "Type": "publicfolder"
            }
        }
    ]
}
Public Folder Request Filtering

These fields are set as query parameters on the URL

Field Name Description
Operation Filter by operation (create, update, delete)
Status Filter by status (completed, pending, error)
Offset Starting position of listing
Size Maximum number of public folders to return

Delete

Verb DELETE
URL Format /v2/customers/{customer account number}/domains/{domain name}/ex/requests/publicFolders/{request_id}
Description Use this route to delete a public folder request

HTTP Codes

Code Condition
204 No Content The request has been accepted and will be processed.
404 Not Found The domain does not exist, the domain does not have Exchange or the request id does not exist. Inspect the itemNotFoundFault for more detail. 
Request:
DELETE https://api.emailsrvr.com/v2/domains/example.com/ex/requests/publicFolders/54b9561a2c50b41e0833b437

Response:
204 No Content
Retrieved from "http://api-wiki.apps.rackspace.com/api-wiki/index.php?title=Exchange_Public_Folders_(Rest_API)&oldid=582"