Rackspace Email & Apps API - User contributions [en]

Main Page

2018-01-30T18:42:02Z

Stev0560: /* Throttling */

== Introduction ==

The Rackspace Email Rest API provides most of the functions of the Control Panel through a REST-based [http://en.wikipedia.org/wiki/Web_service web API]. Whether it is adding a new customer account, adding mailboxes, or any other of the supported features the API allows your application to administer the changes regardless of your application's language or nature. For more information on RESTful web services refer to the following sites:

[http://www.peej.co.uk/articles/restfully-delicious.html Paul James's Homepage: A RESTful Web service, an example]

[http://en.wikipedia.org/wiki/Representational_State_Transfer#External_links Wikipedia: Representational State Transfer - External Links]

The API is accessible to all with access to Control Panel, including resellers, business customers, enterprise customers, and indirect customers. However, not all operations are available to non-resellers. See the [[Rest_API#Operations|Operations]] section for more details.

The Rackspace Email Soap API Homepage has been moved to [[Soap_API| here]].

== Operations ==

The following pages detail the operations that the API supports. The operations are grouped into sections based on the entity/object types that each operation interacts with. Non-resellers do not have access to all functions.

{| class="wikitable"
!Resource
!Example URI
!Business User Access
|-
| [[Customer_(Rest_API)| Customer]]
| /customers/123456789
| [[Customer_(Rest_API)#Create_Login_Tokens | Create Login Tokens]]
|-
| [[Admin_(Rest_API)| Admin]]
| /customers/123456789/admins/my_admin
| All
|-
| [[Domain_(Rest_API)| Domain]]
| /customers/123456789/domains/example.com
| [[Domain_(Rest_API)#Index| Index]], [[Domain_(Rest_API)#Show| Show]], [[Domain_(Rest_API)#Split Domain Routing| Split Domain Routing]], [[Domain_(Rest_API)#Archiving SSO Login URL| Archiving SSO Login URL]], [[Domain_(Rest_API)#Domain_Public_Folders_.28Reseller_Only.29|Domain Public Folders]], [[Domain_(Rest_API)#Domain Email Everyone| Email Everyone ]], [[Domain_(Rest_API)#Show_Domain_Catch-All_Address | Catch-All Address]]
|-
| [[Domain_Spam_(Rest_API)| Domain Spam Settings]]
| /customers/123456789/domains/example.com/spam/settings
| All
|-
| [[Rackspace_Mailbox_(Rest_API)| Rackspace Email Mailbox]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith
| All
|-
| [[Rackspace_Email_Mobile_Sync_(Rest_API)| Rackspace Email Mobile Sync]]
| /customers/123456789/domains/example.com/mobilesync
| All
|-
| [[Rackspace_Mailbox_Spam_(Rest_API)| Rackspace Email Mailbox Spam Settings]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith/spam
| All
|-
| [[Rackspace_Storage_Notification_(Rest_API)| Rackspace Storage Notification Settings]]
| /customers/123456789/domains/example.com/rs/storageNotification
| All
|-
| [[Rackspace_Alias(Rest_API)| Rackspace Email Alias]]
| /customers/123456789/domains/example.com/rs/mailboxes/john.smith/alias
| All
|-
| [[Exchange_Mailbox_(Rest_API)| Exchange Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
| All
|-
| [[Exchange_Mailbox_Spam_(Rest_API)| Exchange Mailbox Spam Settings]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith/spam
| All
|-
| [[Exchange_Contact_(Rest_API)| Exchange Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
| All
|-
| [[Exchange_Distribution_List_(Rest_API)| Exchange Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
| All
|-
| [[Exchange_Resource_Mailbox_(Rest_API)| Exchange Resource Mailbox]]
| /customers/123456789/domains/example.com/ex/resources/conference.room
| All
|-
| [[Exchange_Skype_For_Business_(Rest_API)| Exchange Skype For Business]]
| /customers/123456789/domains/example.com/ex/lync/users
| All
|-
| [[Exchange_Public_Folders_(Rest_API)| Exchange Public Folders]]
| /customers/123456789/domains/example.com/ex/publicFolders
| All
|-
| [[SharePoint_(Rest_API)| SharePoint]]
| /customers/123456789/sharepoint/settings
| [[SharePoint_(Rest_API)#Show | Show]]
|}

The examples shown in the operation pages are written in Ruby and extensively use the helper functions shown in the Ruby Examples below.

== Quick Start ==

'''What you need:'''
* A Rackspace Email and Apps Control Panel admin account
* A HTTP class library that supports TLS and the HTTP methods: GET, POST, PUT, DELETE.

'''Making your first API call, an Show Customer request:'''
# Obtain your API keys
#:* Login to [https://cp.rackspace.com Control Panel]
#:* Click the drop down in the top right next to your admin id/account number.
#:* Click Admins & Contacts
#:* Click API Keys
# Set up your client's HTTP request
#:* Set up your client to make calls to a URL beginning with <nowiki>https://api.emailsrvr.com/v1</nowiki>.
#:* Populate the Accept, User-Agent and X-Api-Signature HTTP request headers correctly. This is explained in detail [[#HTTP Headers|here]].
# Make a GET request to /customers/me.
#:* The complete URI will be <nowiki>https://api.emailsrvr.com/v1/customers/me/domains</nowiki>. Use your HTTP library to retrieve the HTTP response code, 'x-error-message' HTTP response header and HTTP response body so that they may be displayed to help debug and determine success.
'''From here:'''
* Learn about the operations you'll be implementing at the subpages [[#Operations|here]].

== Accessing the API ==

Your application should need to make HTTP requests over TLS (HTTPS) to our API servers. Most programming languages have this functionality built into their core libraries. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.

For some language's libraries, simply using an URL that starts with https:// will cause the library to use TLS. In some other libraries however some options specific to the library may have to be configured to utilize TLS.

All API calls should be directed to a URL in the following format:
<pre>https://api.emailsrvr.com/(version)/(resource)</pre>

Example:
<pre>https://api.emailsrvr.com/v1/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

{| class="wikitable"
!''Supported Versions''
!''URL''
!''Version Documentation''
|-
| v1 (current)
| <nowiki>https://api.emailsrvr.com/v1/</nowiki>
| http://api-wiki.apps.rackspace.com/api-wiki/index.php/Main_Page
|}

The API version number is a component of the URL that is used to access the API. For example, to access the root of the API, the URL is https://api.emailsrvr.com/v1/. Bug fixes and minor non-breaking changes will be made without changing the version number. When major features or breaking changes are introduced, the version number will be incremented. It is not yet determined how many versions are going to be supported at any one time.

'''Using the discontinued v0 API?'''

* If your client consumes v0 of the Admin REST API for Exchange Distribution Lists or Exchange Resource Mailboxes routes, the client must be updated to consume the new behavior in v1.
* If your client does not consume the v0 Admin REST API for Exchange Distribution Lists and Exchange Resource Mailboxes, you simply need to update the base URL (i.e. https://api.emailsrvr.com/v0/…) from v0 to v1. There were no changes to the behavior of the other entities in the API, only their location changed.

{| class="wikitable"
!''Non-breaking Changes''
!''Breaking Changes''
|-
| Adding new fields or attributes to form fields sent
| Changing or deleting any fields in form fields sent
|-
| Adding fields in returned data
| Changing or removing fields in returned data
|-
|
| Changing the URI of any resource
|}

=== Authentication ===

To gain access to the API, your request must include a properly constructed X-Api-Signature HTTP header. Details on what to put in the header are below. To construct the header, you must have the following keys that are generated from the [https://cp.rackspace.com/MyAccount/Administrators/ApiKeys API Keys] page.

{| class="wikitable"
!Key Name
!Description
!Example
|-
| User Key
| A public key that corresponds to your admin id
| ''eGbq9/2hcZsRlr1JV1Pi''
|-
| Secret Key
| A shared secret key
| ''QHOvchm/40czXhJ1OxfxK7jDHr3t''
|}

An unsuccessful authentication will result in a 403 HTTP code.

==== X-Api-Signature Header ====

Format is as follows:
<'''User Key'''>:<'''Timestamp'''>:<'''SHA1 Hash'''> 
Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:46VIwd66mOFGG8IkbgnLlXnfnkU=''

Remember to include the colons between the data strings!

 
'''User Key''': 
This is the public key issued by the Control Panel browser interface.

 
'''Timestamp''': 
The format is YYYYMMDDHHmmss. All values besides year are zero-padded to two spaces. For example, March 08th 2001 at 2:37.25pm would be ''20010308143725''.

{| class="wikitable"
|YYYY
|Four-digit year
|-
| MM
| Month
|-
| DD
| Day
|-
| HH
| Hour in 24h format
|-
| mm
| Minute
|-
| ss
| Second
|}

'''SHA1 Hash''':

A SHA1 (Secure Hash Algorithm) hash must be applied to a string with the following information:

<'''User Key'''><'''User Agent'''><'''Timestamp'''><'''Secret Key'''>

Note that the 'User Agent' must be the exact same as what is specified in the User-Agent HTTP header. Using the above example data, the string before hashing is: ''eGbq9/2hcZsRlr1JV1PiRackspace Management Interface20010308143725QHOvchm/40czXhJ1OxfxK7jDHr3t''

Resulting base-64 SHA1 Hash: ''46VIwd66mOFGG8IkbgnLlXnfnkU=''

Be sure to encode the binary hash, not the hex hash, into base-64. The resulting string should be 28 characters long.

== Using the API ==

=== Requests ===

HTTP requests should be sent to the server with the correct URL, HTTP method, HTTP headers and form data (if needed). The URL specifies the resource, the HTTP method specifies what operation is done on the resource, and form data is used to specify the details of the resource when the resource is added or edited.

The URLs, corresponding HTTP methods, and necessary form data for the desired operations are detailed in the [[#Operations|operation pages]].

If you're getting the HTTP status code 417 see [[Handling HTTP code 417: Expectation failed]]

==== URL ====

The URLs are specifies the resource or resource collection. Objects are organized in a tree collection, starting with customers at the top, then domains, then domain objects next (such as mailboxes, contacts, and distribution lists) and so on. The URLs of the resources and collections accessible are found on the operation pages.

==== HTTP Method ====

It is the HTTP method that specifies what operation will be done on the resource. For example, to get the details of a mailbox a HTTP GET will be done on /customers/12345678/domains/example.com/ex/mailboxes/john.smith. If the mailbox does not exist, a HTTP POST to the same URL with the necessary form data will add the mailbox. Then, a HTTP PUT to the same URL will edit mailbox. And to delete the mailbox, an HTTP DELETE would be used.

The types of operations a certain method performs is outlined below.

{| class="wikitable"
!''HTTP Method''
!''Operations''
!''Response''
|-
|rowspan=2|GET
|Index - returns a list of the resources
|rowspan=2|XML or JSON formatted data
|-
|Show - returns the details of the resource
|-
|POST
|Add - adds a new resource
|rowspan=3|Response code and error message (if applicable) only
|-
|PUT
|Edit - changes the details of the resource
|-
|DELETE
|Delete - deletes the resource
|}

==== HTTP Headers ====

All requests to the API must then include HTTP headers with the following information:

{| class="wikitable"
!''Header Name''
!''Description''
!''Example Header Value''
|-
| Accept
| The requested content type (required for Index and Show actions). Fill this with either 'text/xml' or 'application/json'. See [[#Formats|Response Formats]]
| ''text/xml''
|-
| User-Agent
| An identifier you choose for your client software
| ''Rackspace Management Interface''
|-
| X-Api-Signature
| An authentication string explained in detail [[#X-Api-Signature_Header|here]]
| ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''
|}

==== Form Data ====

When using Add and Edit operations, the details of the resource are sent to the API server via HTTP form data. Your HTTP library should include methods for sending form data along with an HTTP request. The library should by default send the data in the HTTP request body using the 'application/x-www-form-urlencoded' data format.

==== Index Filter/Search ====

The results of Index actions can be filtered/searched. The index URLs can take either one of the query strings: "?startswith=xx" or "?contains=xx," where "xx" is the key word. If the request specifies more than one of these two query strings, a 400 HTTP error will be returned. Different fields will be searched depending on the resource type, see below.

Note that "0-9" is a reserved key word for query string "startswith." It represents any result starting with numbers.

{| class="wikitable"
!''Index Actions''
!''Where the key word will be searched''
|-
| Customer
| Customer name, account number, reference number
|-
| Domain
| Domain name
|-
| Mailbox
| Mailbox name, mailbox display name, custom ID field
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|-
| Lync Users
| Mailbox name (NOTE: Does not support the startsWith search parameter)
|}

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The number of requests made are logged per minute. Calls that were made correctly with a user's API key, but not completed for any reason, including those exceeding the throttle limit, are included in this count.

If a user is over the throttling limit then a 403 HTTP code will be returned with an "Exceeded request limits" message.

{| class="wikitable"
!''Operation Category''
!''Request Limit''
|-
| GET
| 120 per minute
|-
| PUT, POST, DELETE
| 90 per minute
|-
| POST, PUT, DELETE on a domain
| 2 per minute
|-
| POST, DELETE on alternate domains
| 2 per minute
|-
| Enabling public folders for a domain
| 1 per 5 minutes
|}

==== Examples ====

Index of Exchange Mailboxes:
<pre>
Hypertext Transfer Protocol
GET /v1/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
</pre>

Adding New Exchange Mailbox:
<pre>
Hypertext Transfer Protocol
POST /v1/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Content-Length: 53
[Content length: 53]
Content-Type: application/x-www-form-urlencoded

Line-based text data: application/x-www-form-urlencoded
size=2048&displayName=John%20Smith&password=abcABC123

</pre>

=== Responses ===

==== HTTP Status Code ====

On a successfully executed request, a 200 HTTP Code is returned. If the request was unsuccessful however, an HTTP error code in the 400s or 500s will be returned.

==== HTTP Response Body ====

If the request is an Index or Show request, the request data will be returned in the format specified in the HTTP Body.

===== Formats =====

Requests for data (index and show requests) are returned with XML or JSON data based on what your application populates the [[#HTTP_Headers|HTTP Accept headers]] with.

For XML, populate the header with 'text/xml' (ex: Headers!["Accept"] = "text/xml"). The XML document returned will conform to a published XSD (XML Schema Document). There are many ways to parse the data in an XML document, but we have found that the [http://www.w3schools.com/XPath/default.asp XPath] tree-style traversal has served our purposes. In any case, your application will likely need to use a class library for your chosen method.

For JSON, populate the header with 'application/json' (ex: Headers!["Accept"] = "application/json"). As with XML, a library will likely be needed to parse the data.

==== HTTP Headers ====

The only data returned in the header is the error message (if any).

{| class="wikitable"
!''Header Name''
!''Description''
!''Example Header Value''
|-
| x-error-message
| The error message. See [[#Errors|Errors]].
| Missing required field: name
|}

==== Errors ====

See [[Errors]].

==== Paging ====

The results of Index actions are split into pages to lessen potentially high resource usage. The index URLs have a query string with parameters in the format "?size=xx&offset=xx." If a query parameter is omitted, the default value is used.

{| class="wikitable"
!''Query Parameter''
!''Default''
!''Maximum''
!''Notes''
|-
| size
| 50
| 250
| This is the number of elements per page.
|-
| offset
| 0
| N/A
| This is the number of items to offset away from the first item in the list.
|}

===== Example =====

A PHP Example of paging can be found [[PHP_Examples_(Rest_API)| here]].

==== Examples ====

<pre>
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: text/xml; charset=utf-8
Server: Microsoft-IIS/7.0
Date: Fri, 04 Dec 2009 19:08:11 GMT
Content-Length: 430

<?xml version="1.0" encoding="utf-8"?>
<domainList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainList">
<offset>0</offset>
<size>50</size>
<total>1</total>
<domains>
<domain>
<name>customer.com</name>
<accountNumber>123456</accountNumber>
<serviceType>rsemail</serviceType>
</domain>
</domains>
</domainList>
</pre>

<pre>
HTTP/1.1 404 Not Found
Cache-Control: private
Server: Microsoft-IIS/7.0
x-error-message: Customer Not Found
Date: Fri, 04 Dec 2009 19:13:59 GMT
Content-Length: 0
</pre>

<pre>
HTTP/1.1 400 Bad Request
Cache-Control: private
Server: Microsoft-IIS/7.0
x-error-message: Missing required field: type
Date: Fri, 04 Dec 2009 19:17:29 GMT
Content-Length: 0
</pre>

== Examples ==

=== Ruby ===

This examples is written in [http://www.ruby-lang.org/en/ Ruby]. To make the examples shorter, helper methods have been written. These methods are part of a NetMethods module. The contents of the NetMethods module is listed below.

<pre>
require 'server.rb'

server = Server.new

response = server.get '/customers', server.xml_format

#fields = Hash['serviceType' => 'exchange', 'exchangeMaxNumMailboxes' => '4']
#response = server.post '/customers/me/domains/newdomain.com', fields

puts response.code
puts response['x-error-message']
puts response.body
</pre>

<pre>
require 'test/unit/assertions'
require 'net/http'
require 'date'
require 'date/format'
require 'digest/sha1'
require 'base64'
require 'time'

class Server
include Test::Unit::Assertions

def initialize(server='api.emailsrvr.com', version_prefix='/v1', user_key='xxxxxxxxxxxxxxxxxxxx', secret_hash='xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
@server = server
@version_prefix = version_prefix
@user_key = user_key
@secret_hash = secret_hash
end

# Response Type Enums

def xml_format
'text/xml'
end

def json_format
'application/json'
end

#
# HTTP Request Verbs
#
def get(url_string, format)
uri = full_uri(url_string)
headers = prepared_headers
headers['Accept'] = format
request = Net::HTTP::Get.new(request_uri(uri), headers)
http_response = make_request request, uri
end

def delete(url_string)
uri = full_uri(url_string)
request = Net::HTTP::Delete.new(request_uri(uri), prepared_headers)
http_response = make_request request, uri
end

def put(url_string, fields_hash)
uri = full_uri(url_string)
request = Net::HTTP::Put.new(request_uri(uri), prepared_headers)
request.set_form_data(fields_hash)
http_response = make_request request, uri
end

def post(url_string, fields_hash)
uri = full_uri(url_string)
request = Net::HTTP::Post.new(request_uri(uri), prepared_headers)
request.set_form_data(fields_hash)
http_response = make_request request, uri
end

#
# HTTP Request Helpers
#
def make_request request, uri
response = Net::HTTP::start(uri.host, uri.port) do |http|
http.request request
end

response
end

def full_uri url_string
URI.parse('http://' + @server + @version_prefix + url_string)
end

def request_uri uri
request = uri.path
if ! uri.query.nil?
request = request + '?' + uri.query
end
request
end

def prepared_headers
headers = Hash.new
headers.merge! headers_auth_creds(@user_key, @secret_hash)
headers['Accept'] = xml_format
headers
end

def headers_auth_creds apiKey, secretKey
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.strftime('%Y%m%d%H%M%S')

data_to_sign = apiKey + userAgent + timestamp + secretKey

hash = Base64.encode64(Digest::SHA1.digest(data_to_sign))
signature = apiKey + ":" + timestamp + ":" + hash

headers = Hash['User-Agent' => userAgent, 'X-Api-Signature' => signature]
end
end
</pre>

=== C# ===

This examples is written in [http://msdn.microsoft.com/en-us/vcsharp/default.aspx C#].

<pre>
using System;
using System.IO;
using System.Net;
using System.Security.Cryptography;
using System.Text;

namespace RestApiClient
{
public class RestApiClient
{
private HttpWebRequest request;
private HttpWebResponse response;
private string baseUrl;
private string apiKey;
private string secretKey;

public RestApiClient(string baseUrl, string apiKey, string secretKey)
{
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public HttpWebResponse Get(string url, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "GET";
SignMessage();
AssignFormat(format);
return GetResponseContent();
}

public HttpWebResponse Post(string url, string data, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "POST";
SignMessage();
AssignFormat(format);
SendFormData(data);
return GetResponseContent();
}

public HttpWebResponse Put(string url, string data, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "PUT";
SignMessage();
AssignFormat(format);
SendFormData(data);
return GetResponseContent();
}

public HttpWebResponse Delete(string url, string format)
{
this.request = (System.Net.HttpWebRequest)HttpWebRequest.Create(this.baseUrl + url);
request.Method = "DELETE";
SignMessage();
AssignFormat(format);
return GetResponseContent();
}

private void SendFormData(string data)
{
UTF8Encoding encoding = new UTF8Encoding();
byte[] byteData = encoding.GetBytes(data);
this.request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = byteData.Length;
Stream requestStream = request.GetRequestStream();
requestStream.Write(byteData, 0, byteData.Length);
requestStream.Close();
}

private HttpWebResponse GetResponseContent()
{
try
{
return (HttpWebResponse)request.GetResponse();
}
catch (WebException e)
{
return (HttpWebResponse)e.Response;
}

}

private void SignMessage()
{
var userAgent = "C# Client Library";
this.request.UserAgent = userAgent;
var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmss");
var dataToSign = apiKey + userAgent + dateTime + secretKey;
var hash = SHA1.Create();
var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
var signature = Convert.ToBase64String(signedBytes);

request.Headers["X-Api-Signature"] = apiKey + ":" + dateTime + ":" + signature;
}

private void AssignFormat(string format)
{
this.request.Accept = format;
}
}
}
</pre>

=== PHP ===

The PHP Example can be found [[PHP_Examples_(Rest_API)| here]].

Customer (Rest API)

2017-12-15T18:24:05Z

Stev0560: /* v2 - Current */

__TOC__

== v1 - Current ==

=== Index (Reseller Only) ===

''URL'':

[GET] <nowiki>https://api.emailsrvr.com/v1/customers</nowiki>

''Description'':

This operation returns the list of customers that the authenticated user has access to.

''Filter/Search'':

Search parameter 'startswith' and 'contains' will try to find the result in customer name, account number and reference number. We also provide a separate query method ?referenceNumber=123456 that will return a Show on the exact customer whose reference number is as specified. This query method only returns details for sub-accounts.

''Example'':

<pre>
get '/customers?size=100&offset=10'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<customerList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:customerList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<customers>
<customer>
<name>API Customer 17</name>
<accountNumber>460182</accountNumber>
<referenceNumber>49</referenceNumber>
</customer>
<customer>
<name>API Customer 39</name>
<accountNumber>460181</accountNumber>
<referenceNumber>23</referenceNumber>
</customer>
<customer>
<name>API Customer 50</name>
<accountNumber>460183</accountNumber>
<referenceNumber>10</referenceNumber>
</customer>
</customers>
</customerList>
</pre>

''JSON Result Example'':

<pre>
{"offset":0,"size":50,"total":3,"customers":
[{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"},
{"name":"API Customer 39","accountNumber":"460181","referenceNumber":"23"},
{"name":"API Customer 50","accountNumber":"460183","referenceNumber":"10"}]}
</pre>

=== Show (Reseller Only) ===

''URL'':

[GET] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)</nowiki>

''Description'':

The show operation will return detailed information about the specified account.

''Remarks'':

To do the show operation on the account that is logged in instead of a customer's account, use "me" in the place of the customer account number i.e. <nowiki>'https://api.emailsrvr.com/v1/customers/me'</nowiki>.

The show operation only supports the GET HTTP verb.

''Reference Number''

The query string "referenceNumber=xx" searches for a customer with an exact reference number.

''Examples'':

<pre>
get '/customers/me'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<customer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:customer">
<name>API Customer 17</name>
<accountNumber>460182</accountNumber>
<referenceNumber>49</referenceNumber>
<addressLine1>555 Address</addressLine1>
<addressLine2>Suite 555</addressLine2>
<city>Austin</city>
<state>TX</state>
<zip>78703</zip>
<country>US</country>
<phone>1-555-555-5555</phone>
<email>user@example.com</email>
</customer>
</pre>

''JSON Result Example'':

<pre>
{
"name":"API Customer 17",
"accountNumber":"460182",
"referenceNumber":"49",
"addressLine1":"555 Address",
"addressLine2":"Suite 555",
"city":"Austin",
"state":"Texas",
"zip":"78703",
"country":"USA",
"phone":"1-555-555-5555",
"email":"user@example.com"
}
</pre>

''Example of querying with Reference Number''

<pre>
get '/customers?referenceNumber=49'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<customer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:customer">
<name>API Customer 17</name>
<accountNumber>460182</accountNumber>
<referenceNumber>49</referenceNumber>
<addressLine1>555 Address</addressLine1>
<addressLine2>Suite 555</addressLine2>
<city>Austin</city>
<state>TX</state>
<zip>78703</zip>
<country>US</country>
<phone>1-555-555-5555</phone>
<email>user@example.com</email>
</customer>
</pre>

=== Add/Edit (Reseller Only)===

''URL'':

Add: [POST] <nowiki>https://api.emailsrvr.com/v1/customers</nowiki>
Edit: [PUT] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)</nowiki>

''Description'':

Add or edit a new sub-account. Note that customer number is not known until the customer is added.

The <code>name</code> field must contain 100 characters or fewer. The <code>name</code> field cannot be null or empty and cannot begin or end with whitespace.

The <code>referenceNumber</code> must contain 20 characters or fewer.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| name
| string
| The customer's display name (required for Add)
|-
| referenceNumber
| string
| The reference number of this account
|-
| addressLine1
| string
| Street address for the account
|-
| addressLine2
| string
| Additional address information (building, suite, etc.)
|-
| city
| string
| Account city
|-
| state
| string
| Account state
|-
| zip
| string
| Account ZIP code
|-
| country
| string
| Account country
|-
| phone
| string
| Account phone number
|-
| email
| string
| Account email address
|}

''Example'':

<pre>
post '/customers',
{
'name' => 'Name'
}
</pre>

<pre>
put '/customers/999999',
{
'name' => 'NewName',
'referenceNumber' => '12345'
'addressLine1':'555 Address',
'addressLine2':'Suite 555',
'city':'Austin',
'state':'Texas',
'zip':'78703',
'country':'USA',
'phone':'1-555-555-5555',
'email':'user@example.com'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The name field was not specified
| 400 Bad Request
| Missing required field: name
|-
| The name field cannot be blank
| 400 Bad Request
| Required field name cannot be empty
|-
| Name cannot begin or end with whitespace
| 400 Bad Request
| Improper Customer Name: cannot begin or end with a space
|-
| Name must contain <= 100 characters
| 400 Bad Request
| Name too long: 100 characters or fewer
|-
| Reference number must contain <= 20 characters
| 400 Bad Request
| Reference number too long: 20 characters or fewer
|}

=== Enable/Disable (Reseller Only)===

''URL'':

<pre>
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/enable
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/disable
</pre>

''Description'':

Enables or disables the account and all services (mailboxes, sharepoint sites, etc).

''Example'':

<pre>
post '/customers/999999/disable'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| You are either trying to enable/disable an account which does not belong to you or the admin associated with your api key does not have the correct role(s) to perform this action.
| 403
| Not authorized
|-
| You have made too many recent requests to perform this action. You are allowed to perform this action only one time in a 5 minute sliding window.
| 403
| Exceeded request limits
|}

=== Delete (Reseller Only) ===

''URL'':

[DELETE] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)</nowiki>

''Description'':

Deletes the account.

''Example'':

<pre>
delete '/customers/999999'
</pre>

=== Create Login Tokens ===

''URL'':

[POST] <nowiki>https://api.emailsrvr.com/v1/customers/(customer account number)/loginToken</nowiki>

''Description'':

Generate a login token using which a customer can use to SSO into the Control Panel.

Login tokens can be generated for two kinds of users: virtual and non-virtual. The distinction between
the two users is that a virtual user gets the administrator's privileges when SSOed into the Control Panel.
On the other hand, the non-virtual user gets only as much privileges as are given to him/her when
his/her account was created.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| userName
| string
| The name for which login token needs to be created.
|-
| virtualUser
| string
| A flag indicating whether the user for whom the login token needs to be generated is virtual or non-virtual. Valid values: true/false. When set to true, the userName is treated as a virtual user. When set to false, the userName is treated as a non-virtual user. A non-virtual user must be an existing admin user.
|}

''Example'':

<pre>
post '/customers/460896/loginToken', {'userName' => 'dev_cust_limitedadmin', 'virtualUser' => 'true'}

</pre>

Create login token for virtual user 'dev_cust_limitedadmin'.

<pre>

<?xml version="1.0" encoding="utf-8"?>

<loginToken xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns="urn:xml:loginToken">

<user>dev_cust_limitedadmin_460896_vu</user>

<token>EEB0012D8DBC2CAC26E28365D44B537FFF0D79350</token>

<dateCreated>6/11/2010 10:53:46 AM</dateCreated>

</loginToken>
</pre>

The login token is valid for ten minutes after its creation. The "dateCreated" field indicates the time when the login token
is created.

Using the above created login token the customer with account number 460896 can SSO into the Control Panel using
the following URL:

<pre>
http://ControlPanelURL/TokenLogin.aspx?loginToken=EEB0012D8DBC2CAC26E28365D44B537FFF0D79350
</pre>

A customer can also use the login token to login on their private label control panel (E.g.: cp.mydomain.com/logintokens.aspx).

== v2 - Current ==

=== Company Invoices ===

The paths in this section allow you to view a list of invoices, and download a CSV of the line items of a particular invoice.

==== View Invoices ====

''Description'':

View a list of invoices for an account in reverse chronological order (most recent first).

''Request'':

<pre>
GET '/v2/customers/999999/invoices', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Size": 50,
"Offset": 0,
"Total": 1,
"Items": [{
"InvoiceId": "123",
"InvoiceDate": "2017-12-07T00:00:00",
"InvoiceType": "Billing",
"TotalDue": "1122.55",
"IsPaid": true,
"CsvAvailable": true
}]
}
</pre>

===== Request parameters =====

- ''Size'': The number of invoices returned to GET requests. The default value is 50.

- ''Offset'': Indicates an offset at which to return invoices to GET requests. The default value is 0.

- ''Total'': Indicates the total number of invoices for the account.

===== CsvAvailable =====

If CsvAvailable is true, then you can use the CSV path (see just below) to retrieve a CSV of line items for this invoice.

==== Invoice Line Items ====

''Description'':

Download a CSV of line items for a specific invoice. You must pass a valid invoice ID in the path.

''Request'':

<pre>
GET '/v2/customers/999999/invoices/123123', 'application/json'
</pre>
Where 123123 is the invoice ID.

NOTE! The content-type returned for this route will always be 'text/csv'.

NOTE! CSV files are only available for invoices starting around July 2017. If a CSV is not available, this route will return a 404.

''Response'':

<pre>
200 OK
Account No,Reference No,Domain,Product,Type,Service Start,Service End,Term Committed Usage,Current Usage,Usage Change,Months,Rate,Charge
1371592,"","MyDomain.com","Outlook",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,0,0
1371592,"","MyDomain.com","Hosted Exchange",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,7,140
1371592,"","MyDomain.com","Hosted Exchange ActiveSync",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,20,20,20,1,0,0
1371592,"","MyDomain.com","Hosted Exchange Extra Storage",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,150,150,150,1,0,0
1386010,"","MyOtherDomain","Office 365 Business Essentials",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,31,31,31,1,7,217
1386010,"","MyOtherDomain","Office 365 Business Essentials",Upgrade,11/6/2017 7:54:44 PM,11/30/2017 11:59:59 PM,29,31,2,0.81,7,11.34
1386010,"","MyOtherDomain","Office 365 Business Premium",Renewal,12/1/2017 12:00:00 AM,12/31/2017 11:59:59 PM,39,39,39,1,14,546
</pre>

=== Company contacts ===

The paths in this section allow you to manage company contacts. Company contacts have authorization to contact Support with questions about this account.

==== View contacts ====

''Description'':

View all contacts for an account.

''Request'':

<pre>
GET '/v2/customers/999999/contacts', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Size": 50,
"Offset": 0,
"Total": 1,
"Items": [{
"CustomerNumber": "999999",
"Email": "user@example.com",
"Id": "1",
"Name": "Contact first - Ellie",
"Phone": "1235555555",
"ReceivesAlerts": true,
"ReceivesBilling": true,
"ReceivesUpdates": true,
"SecurityAnswer": "A",
"SecurityQuestion": "Q"
}]
}
</pre>

===== Request parameters =====

- ''Size'': The number of contacts returned to GET requests. The default value is 50.

- ''Offset'': Indicates an offset at which to return contacts to GET requests. The default value is 0.

- ''Total'': Indicates the total number of contacts for the account.

===== Alerts, Billing, and Updates =====

- ''ReceivesAlerts'': Indicates whether a contact receives account alerts.

- ''ReceivesBilling'': Authorizes a contact to receive billing information and inquiries. An account must have at least one billing contact.

- ''ReceivesUpdates'': Indicates whether a contact receives account update notifications.

===== View a specific contact =====

''Description'':

View a specific contact by adding a contact's <code>ID</code> to the request path.

Locate a contact's <code>ID</code> in its <code>Items</code> array when [[view all contacts|viewing all contacts]].

''Request'':

<pre>
GET '/v2/customers/999999/contacts/4', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"CustomerNumber": "999999",
"Email": "user@example.com",
"Id": "4",
"Name": "Contact first - Ellie",
"Phone": "1235555555",
"ReceivesAlerts": true,
"ReceivesBilling": true,
"ReceivesUpdates": true,
"SecurityAnswer": "A",
"SecurityQuestion": "Q"
}
</pre>

===== View a range of contacts at an offset =====

''Description'':

Include ''Size'' and ''Offset'' in the URL of GET requests to view a range of contacts at an offset.

''Request'':

<pre>
GET '/v2/customers/999999/contacts?size=2&offset=2', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Size": 2,
"Offset": 2,
"Total": 4,
"Items": [{
"CustomerNumber": "999999",
"Email": "user3@example.com",
"Id": "3",
"Name": "Contact first - Ellie",
"Phone": "1235555555",
"ReceivesAlerts": true,
"ReceivesBilling": true,
"ReceivesUpdates": true,
"SecurityAnswer": "A",
"SecurityQuestion": "Q"
},
{
"CustomerNumber": "999999",
"Email": "user4@example.com",
"Id": "4",
"Name": "Contact after hours - Samir",
"Phone": "1235555555",
"ReceivesAlerts": false,
"ReceivesBilling": false,
"ReceivesUpdates": false,
"SecurityAnswer": "A",
"SecurityQuestion": "Q"
}]
}
</pre>

==== Add a contact ====

''Description'':

Create a new contact.

Creating a new contact requires all contact fields to be populated. See the following request body for a complete list.

''Request'':

<pre>
POST /v2/customers/9999/contacts/
{
"Email": "user@example.com",
"Name": "Best Contact",
"Phone": "1235555555",
"ReceivesAlerts": false,
"ReceivesBilling": false,
"ReceivesUpdates": false,
"SecurityAnswer": "A",
"SecurityQuestion": "Q"
}
</pre>

==== Update a contact ====

''Description'':

Update information for the contact you specify.

''Request'':

<pre>
PUT /v2/customers/999999/contacts/4
{
"Email": "user@example.com",
"Name": "Best Contact",
"Phone": "1235555555",
"ReceivesAlerts": false,
"ReceivesBilling": false,
"ReceivesUpdates": false,
"SecurityAnswer": "A",
"SecurityQuestion": "Q"
}
</pre>

''Response'':

<pre>
200 OK
</pre>

==== Delete a contact ====

''Description'':

Remove a contact from the account.

An account must include at least one contact for billing. Set <code>"ReceivesBilling" : "true"</code> for any contacts permitted to handle billing-related inquiries.

''Request'':

<pre>
DELETE /v2/customers/999999/contacts/4
</pre>

''Response'':

<pre>
200 OK
</pre>

==== Errors for GET requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct.
|}

==== Errors for DELETE requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Attempting to delete the last primary or billing contact
| 400 Bad Request
| There must be at least one billing contact and one primary contact. (A single contact can be both.)
|}

==== Errors for PUT and POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Unable to add a new contact or administrator.
| 400 Bad Request
| Contact/Administrator limit reached.
|-
| Missing contact name
| 400 Bad Request
| Contact name cannot be empty.
|-
| Missing or invalid email address
| 400 Bad Request
| Please enter a valid email address.
|-
| No security question specified
| 400 Bad Request
| Security question cannot be empty.
|-
| No security answer specified
| 400 Bad Request
| Security answer cannot be empty.
|-
| Admin does not have permission to add, change, or remove contacts
| 403 Not Authorized
| Unauthorized.
|}

Exchange Mailbox (Rest API)

2017-05-17T15:57:33Z

Stev0560: saveForwardedEmail

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] http://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes</nowiki>

''Description'':

Shows a list of mailboxes under the domain

''Filter/Search'':

Mailbox searches may be filtered by the 'enabled' flag using query methods ?enabled=true and ?enabled=false.

''Remarks'':

The show operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes'
</pre>

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<mailboxList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:mailboxList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<mailboxes>
<mailbox>
<name>apiexmailbox55</name>
<displayName>API Test</displayName>
</mailbox>
<mailbox>
<name>apiexmailbox6</name>
<displayName>API Test</displayName>
</mailbox>
<mailbox>
<name>apiexmailbox90</name>
<displayName>API Test</displayName>
</mailbox>
</mailboxes>
</mailboxList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"mailboxes":[{"name":"apiexmailbox55","displayName":"API Test"},{"name":"apiexmailbox6","displayName":"API Test"},{"name":"apiexmailbox90","displayName":"API Test"}]}

''Custom Fields'':

The result displays each mailbox's 'name' and 'displayName' as default. There is a query string 'fields' that allows the result to display more mailbox properties. The additional properties are: 'size', 'currentUsage', 'hasBlackBerryMobileService', 'hasActiveSyncMobileService'.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes?fields=size,currentUsage'
</pre>

=== Show ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)</nowiki>

''Description'':

The show operation will return detailed information about the specified mailbox.

''Remarks'':

The show operation only supports the GET HTTP verb.

The "samAccountName" is the logon name used to support clients and servers running older versions of the operating system.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<mailbox xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:mailbox">
<name>apiexmailbox90</name>
<displayName>API Test</displayName>
<size>2048</size>
<currentUsage>0</currentUsage>
<isHidden>false</isHidden>
<visibleInRackspaceEmailCompanyDirectory>false</visibleInRackspaceEmailCompanyDirectory>
<isPublicFolderAdmin>true</isPublicFolderAdmin>
<enabled>true</enabled>
<lastLogin>2/12/2010 1:00:00 AM</lastLogin>
<contactInfo>
<firstName>API</firstName>
<lastName>Test</lastName>
<jobTitle>Dev</jobTitle>
<company>My Company</company>
<department>R&D</department>
<businessNumber>111-1111</businessNumber>
<homeNumber>222-2222</homeNumber>
<mobileNumber>333-3333</mobileNumber>
<faxNumber>444-4444</faxNumber>
<pagerNumber>1234</pagerNumber>
<addressLine1>123 Main Street</addressLine1>
<city>Blacksburg</city>
<state>VA</state>
<zip>24060</zip>
<country>USA</country>
<notes>My Notes</notes>
<customID>0123456789</customID>
</contactInfo>
<emailForwardingAddress>apiexmailbox8@apidomain24.com</emailForwardingAddress>
<saveForwardedEmail>false</saveForwardedEmail>
<emailAddressList>
<emailAddress>
<address>apiexmailbox90@apidomain92.com</address>
<replyTo>true</replyTo>
</emailAddress>
</emailAddressList>
<hasBlackBerryMobileService>false</hasBlackBerryMobileService>
<hasActiveSyncMobileService>false</hasActiveSyncMobileService>
<samAccountName>apiexmailbox90_53B5B</samAccountName>
</mailbox>
</pre>

''Json Result Example'':

{"name":"apiexmailbox90", "displayName":"API Test", "size":2048, "currentUsage":0, "isHidden":false, "isPublicFolderAdmin":true, "enabled":true, "lastLogin":"2\/12\/2006 1:00:00 AM", "contactInfo":{"firstName":"API", "lastName":"Test", "jobTitle":"Dev", "company":"My Company", "department":"R&D", "businessNumber":"111-1111", "homeNumber":"222-2222", "mobileNumber":"333-3333", "faxNumber":"444-4444", "pagerNumber":"1234", "addressLine1":"123 Main Street", "city":"Blacksburg", "state":"VA", "zip":"24060", "country":"USA", "notes":"My Notes", "customID":"0123456789"}, "emailForwardingAddress":"apiexmailbox8@apidomain24.com", "saveForwardedEmail":false, "emailAddressList":[{"address":"apiexmailbox90@apidomain92.com", "replyTo":true}], "hasBlackBerryMobileService":false, "hasActiveSyncMobileService":false, "samAccountName":"apiexmailbox90_53B5B", "visibleInRackspaceEmailCompanyDirectory":false}

=== Add/Edit ===

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)
Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)</nowiki>

''Description'':

Adds/edits a mailbox using the specified form fields. All required fields must be supplied when adding. Other fields may be omitted.

{{RouteRequiresFormEncoded}}

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Display name (Required for Add)
|-
| password
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| isHidden
| boolean
| Indicates whether or not the mailbox is hidden from the Global Address List
|-
| isPublicFolderAdmin
| boolean
| Indicates whether or not the account is a public folder administrator
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| jobTitle
| string
| Job title
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| businessNumber
| string
| Business phone number
|-
| pagerNumber
| string
| Pager phone number
|-
| homeNumber
| string
| Home phone number
|-
| mobileNumber
| string
| Mobile phone number
|-
| faxNumber
| string
| Fax phone number
|-
| notes
| string
| Notes field
|-
| customID
| string
| A custom field that can be used to tie user mailboxes to external user systems
|-
| emailForwardingAddress
| string
| Forwarding email address (If this field is assigned an email address, then email forwarding will be turned on. If this field is not assigned or assigned an empty string, then email forwarding will be disabled.)
|-
| saveForwardedEmail
| boolean
| When true, copies of forwarded email are saved in this mailbox. When false, email is forwarded but not saved.
|-
| visibleInRackspaceEmailCompanyDirectory
| boolean
| Flag indicating whether the mailbox is visible in the company directory
|-
| enabled
| boolean
| Enable/Disable mailbox, input must be "true" or "false"
|-
| lastLogin '''''(read only)'''''
| string
| Date of last login, EST Time (in string format)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith',
{
'displayName' => 'Alex Smith',
'password' => 'Secret123!@#',
'size' => '2048'
}
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith',
{
'homeNumber' => '8005551234'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| New mailbox name (user name) doesn't meet the naming requirements
| 400
| Invalid user name
|-
| New mailbox display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| New mailbox password doesn't meet the password pattern requirements
| 400
| Password must be at least 8 characters long
|-
| New mailbox name (user name) already exists
| 400
| The email address john.doe@abc.com is already in use
|}

=== Delete ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)</nowiki>

''Description'':

Deletes the mailbox.

''Remarks'':

The mailbox and mailbox contents are deleted permanently.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith'
</pre>

=== Add Email Address ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/emailaddresses/(email address)</nowiki>

''Description'':

Adds a mailbox's email address.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/emailaddresses/alex@example.com', {}
</pre>

=== Delete Email Address ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/emailaddresses/(email address)</nowiki>

''Description'':

Deletes the email address.

''Remarks'':

The operation will fail if the email address does not exist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/emailaddresses/alex@example.com'
</pre>

=== Spam Settings ===

See [[Mailbox_Spam_(Rest_API)| Exchange Mailbox Spam Settings]].

=== Mailbox Permissions ===

Exchange mailboxes can be given permissions. A permission is defined as a tuple (mailbox, permissionType).

permissionType:= (SendAs | FullAccess | Both)

==== Index Permissions ====
''URL'':

<nowiki>[GET] http://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user)/permissions</nowiki>

''Description'':

Shows the current set of permissions granted on a user's mailbox.

''Example'':
<pre>
get '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions'
</pre>

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<permissionList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:permissionList">
<offset>0</offset>
<size>50</size>
<total>0</total>
<permissions>
<permission>
<emailAddress>joe.schmoe@enterpriseallservices.net</emailAddress>
<permissionType>fullAccess</permissionType>
</permission>
</permissions>
</permissionList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":0,"permissions":[{"emailAddress":"joe.schmoe@enterpriseallservices.net","permissionType":"fullAccess"}]}

''Comments'':
The above result shows the permission list for user Jane Doe's mailbox. The list contains one entry corresponding to
that of user Joe Schmoe with permission type of "FullAccess".

==== Adding Permission ====

''URL'':

<nowiki>[POST] http://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Grants user2 the specified permission on mailbox of user1.

{{RouteRequiresFormEncoded}}

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| permission
| string
| permissionType (Required)
|}

''Example'':
<pre>
post '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe', {'permission' => 'fullAccess'}
</pre>

''Comments'':
The above result shows that on the mailbox of user Jane Doe, the user John Doe has been granted the permission of type "fullAccess".

==== Editing Permission ====

''URL'':

<nowiki>[PUT] http://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Modifies permission granted to user2 on the mailbox of user1.

{{RouteRequiresFormEncoded}}

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| permission
| string
| permissionType (Required)
|}

''Example'':
<pre>
put '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe',
{'permission' => 'both'}
</pre>

''Comments'':
The permission granted to user John Doe on the mailbox of Jane Doe is modified to "both".

==== Deleting Permission ====

''URL'':

<nowiki>[DELETE] http://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Deletes permission granted to user2 on the mailbox of user1.

''Example'':
<pre>
delete '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe'
</pre>

''Comments'':
The permission granted to user John Doe on the mailbox of Jane Doe is deleted.

=== BlackBerry Mobile Service ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/blackberrymobileservices</nowiki>

''Description'':

Returns a list of mailboxes that has BlackBerry mobile service enabled.

''Remarks'':

The index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/blackberrymobileservices'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blackBerryMobileServiceList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:xml:blackBerryMobileServiceList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<mailboxes>
<mailbox>apiexmailbox36</mailbox>
<mailbox>apiexmailbox66</mailbox>
<mailbox>apiexmailbox85</mailbox>
</mailboxes>
</blackBerryMobileServiceList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"mailboxes":["apiexmailbox36","apiexmailbox66","apiexmailbox85"]}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/blackberrymobileservice</nowiki>

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

{{RouteRequiresFormEncoded}}

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| activationPassword
| string
| Activation password (Required)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/blackberrymobileservice',
{
'activationPassword' => '12345'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Mailbox already has BlackBerry Service
| 400
| User john.smith@example.com has BlackBerry Mobile Service already
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/blackberrymobileservice</nowiki>

''Description'':

Detaches a BlackBerry mobile service from a mailbox.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/blackberrymobileservice'
</pre>

=== ActiveSync Mobile Service ===

==== Index ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/activesyncmobileservices</nowiki>

''Description'':

Returns a list of mailboxes that have ActiveSync mobile service enabled.

''Remarks'':

The index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/activesyncmobileservices'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<activeSyncMobileServiceList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:xml:activeSyncMobileServiceList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<mailboxes>
<mailbox>apiexmailbox36</mailbox>
<mailbox>apiexmailbox66</mailbox>
<mailbox>apiexmailbox85</mailbox>
</mailboxes>
</activeSyncMobileServiceList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"mailboxes":["apiexmailbox36","apiexmailbox66","apiexmailbox85"]}

==== Show ====

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Returns the mailbox ActiveSync mobile service setup information to access Hosted Exchange 2007.

''Remarks'':

The index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<activeSyncMobileService xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:activeSyncMobileService">
<emailAddress>john.smith@example.com</emailAddress>
<serverAddress>mex07A.emailsrvr.com</serverAddress>
<userName>johnsmith1234</userName>
<domainAddress>mex07A.mlsrvr.com</domainAddress>
</activeSyncMobileService>
</pre>

''Json Result Example'':

{"emailAddress":"john.smith@example.com","serverAddress":"mex07A.emailsrvr.com","userName":"johnsmith1234","domainAddress":"mex07A.mlsrvr.com"}

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Mailbox has no ActiveSync service
| 404
| User john.smith@example.com has no active ActiveSync Mobile Service.
|}

==== Add ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Attaches a ActiveSync service to the mailbox.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', {}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Mailbox already has ActiveSync Service
| 400
| User john.smith@example.com has ActiveSync Mobile Service already
|}

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice'
</pre>