Rackspace Email & Apps API - User contributions [en]

Exchange Mailbox (Rest API)

2010-05-03T16:14:41Z

Kevin.lin: Removed Spam settings to its own page.

Domain (Rest API)

2010-05-03T16:12:08Z

Kevin.lin: Moved spam settings to its own page. Added public folders, deprecated good mobile.

Customer (Rest API)

2010-05-03T16:06:15Z

Kevin.lin: Added customerNumber search field.

__TOC__

== Index (Reseller Only) ==

''URL'':

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

''Description'':

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

''Filter/Search'':

Searching will return results based on the name, account number and reference number fields. We also provide a separate query method ?referenceNumber=123456 that will return a Show on the exact customer whose reference number is as specified.

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/CustomerList.xsd CustomerList.xsd]

''Example'':

<pre>
get '/customers?size=100&page=1', 'text/xml'
</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/v0/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/v0/customers/me'</nowiki>.

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Customer.xsd Customer.xsd]

''Reference Number''

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

''Examples'':

<pre>
get '/customers/me', 'text/xml'
</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>
</customer>
</pre>

''JSON Result Example'':

<pre>
{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"}
</pre>

''Example of querying with Reference Number''

<pre>
get '/customers?referenceNumber=49', 'text/xml'
</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>
</customer>
</pre>

== Add/Edit (Reseller Only)==

''URL'':

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

''Description'':

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

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

''Example'':

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

<pre>
put '/customers/999999', 'text/xml',
{
'name' => 'NewName',
'referenceNumber' => '12345'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The name field was not specified
| 400
| Missing required field: name
|-
| The name field cannot be blank
| 400
| Required field name cannot be empty
|-
| Names cannot start with a space
| 400
| Improper Customer Name
|}

== Delete (Reseller Only) ==

''URL'':

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

''Description'':

Deletes the account.

''Example'':

<pre>
delete '/customers/999999', 'text/xml'
</pre>

Rest API

2010-05-03T15:59:32Z

Kevin.lin: Large sync.

== Recent Changes ==

'''03/28/10 '''
{|
|
New features:
* Rest API can be accessed by Business Users. However, not all operations are available.
* Domain Public Folders can be enabled now.
|
|}

{|
|
Deprecated:
* Good Mobile Service is no longer supported.
|
|}

'''03/14/10 '''
{|
|
New features:
* Index/Add/Edit/Delete Mailbox Permissions.
|
|}

{|
|
Known Issues:
* Domain public folders can't be enabled using Rest API at this moment. The next release (on 03/21/2010) will fix this problem.
|
|}

'''01/31/10 '''
{|
|
New features:
* Index/Show/Add/Edit/Delete Resource Mailboxes.
* Index/Add/Delete Resource Mailbox Admins.
|
|}

'''11/22/09 '''
{|
|
New features:
*Index/Add/Delete Alternate Domains.
*Show/Edit Domain Spam Settings.
*Index/Add/Delete Domain Blacklist/Safelist.
*Show/Edit Split Domain Routing.
*Show Mailbox ActiveSync Setup Info.
|
|}

== Introduction ==

The Email & Apps Control Panel 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.

== 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
| None
|-
| [[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|Domain Public Folders ]]
|-
| [[Domain_(Rest_API)| Domain Spam Settings]]
| /customers/123456789/domains/example.com/spam
| 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
|}

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
#:* Click on My Account at the top of the [https://apps.rackspace.com/?cp Control Panel web interface]. Under the Administrators heading there will be an link for the API keys page.
# Set up your client's HTTP request
#:* Set up your client to make calls to a URL beginning with <nowiki>https://api.emailsrvr.com/v0</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/v0/customers/me</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 will need to make HTTP requests to remote servers. Most programming languages have this function provided in its class library. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.


Calls without [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS] (formerly SSL) will complete successfully but it is HIGHLY RECOMMENDED that TLS always be used. Interception of unencrypted communication will allow a third party to have complete access to all functions available via the API.

For some language libraries just using an URL 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/v0/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

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

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/v0/. 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.

{| 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 that are generated from the [https://apps.rackspace.com/?cp Control Panel Web interface]. The key generation page can be found by clicking 'My Account' at the top, then 'Generate API Keys' in the Administrators section.

{| 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
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The current limit is 60 requests 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.

==== Examples ====

Index of Exchange Mailboxes:
<pre>
Hypertext Transfer Protocol
GET /v0/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 /v0/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 ====

In the event of an error, the error message will be returned the HTTP header '''x-error-message''' and an HTTP Status Code in the '''400'''s or '''500'''s will be returned.

Note: Every language's HTTP library provides methods for retrieving HTTP response codes and response headers.

Below are some errors that are common to many operations. Each operation also has some specific errors which are outlined with the operation.

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
|Format is invalid
|400
|When requesting an index or show on a resource the 'Accept' header should be either 'text/xml' or 'application/json'
|-
|Expectation Failed: See [[Handling HTTP code 417: Expectation failed]]
|417
|(none)
|-
|Customer account number is invalid
|404
|Invalid account number
|-
|Domain is not found
|404
|<domain name> not found
|-
|Mailbox is not found
|404
|Mailbox not found
|-
|Required form field is missing
|400
|Missing required field: <required field>
|-
|Required form field has null or empty string input
|400
|Required field <required field> cannot be empty
|-
|Integer form field has non-integer input
|400
|Invalid format for <field>, input must be an integer
|-
|Boolean form field has non-boolean input
|400
|Invalid format for <field>, input must be True or False
|-
|Form data has an unrecognized field
|400
|Unrecognized field: <field>
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== 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.
|}

==== 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='/v0', 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.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = 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);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

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

Rest API

2010-05-03T15:49:36Z

Kevin.lin: /* Operations */ Double-spacing fix.

== Recent Changes ==

'''03/28/10 '''
{|
|
New features:
* Rest API can be accessed by Business Users. However, not all operations are available.
* Domain Public Folders can be enabled now.
|
|}

{|
|
Deprecated:
* Good Mobile Service is no longer supported.
|
|}

'''03/14/10 '''
{|
|
New features:
* Index/Add/Edit/Delete Mailbox Permissions.
|
|}

{|
|
Known Issues:
* Domain public folders can't be enabled using Rest API at this moment. The next release (on 03/21/2010) will fix this problem.
|
|}

'''01/31/10 '''
{|
|
New features:
* Index/Show/Add/Edit/Delete Resource Mailboxes.
* Index/Add/Delete Resource Mailbox Admins.
|
|}

'''11/22/09 '''
{|
|
New features:
*Index/Add/Delete Alternate Domains.
*Show/Edit Domain Spam Settings.
*Index/Add/Delete Domain Blacklist/Safelist.
*Show/Edit Split Domain Routing.
*Show Mailbox ActiveSync Setup Info.
|
|}

== Introduction ==

The Email & Apps Control Panel 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]

== 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
| None
|-
| [[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|Domain Public Folders ]]
|-
| [[Domain_(Rest_API)| Domain Spam Settings]]
| /customers/123456789/domains/example.com/spam
| 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
|}

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

== Accessing the API ==

Your application will need to make HTTP requests to remote servers. Most programming languages have this function provided in its class library. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.


Calls without [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS] (formerly SSL) will complete successfully but it is HIGHLY RECOMMENDED that TLS always be used. Interception of unencrypted communication will allow a third party to have complete access to all functions available via the API.

For some language libraries just using an URL 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/v0/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

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

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/v0/. 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.

{| 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 that are generated from the Control Panel Web interface.

{| 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'''>:<'''Signature'''> 
Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

 
'''Signature''':

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 URLs, corresponding HTTP Methods, and necessary form data for the desired operations are detailed in the [[#Operations|operation pages]].

==== 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 consistent and is outlined in the table 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''
|-
| Accept
| The requested content type (required regardless of type of operation). 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=''
|}

==== 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
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

'''Reference Number'''

For the customer object only, the query string "referenceNumber=xx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The current limit is 60 requests 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.

==== Examples ====

Example requests:
<pre>
Index of Exchange Mailboxes:

Hypertext Transfer Protocol
GET /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Request Method: GET
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml

Adding New Exchange Mailbox:

Hypertext Transfer Protocol
POST /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Request Method: POST
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
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 ===

On a successfully executed request, a 200 HTTP Code is returned. Requested data is also returned if the operation was a Show or Index action. If the request is unsuccessful, then an error HTTP Code is returned with a message detailing the error. The errors and their corresponding codes are detailed on the operation pages.

==== 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 extract data from 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 library with the functions necessary for whichever method you choose to use to extract data.

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.

==== Errors ====

If a request is not sucessfully completed an HTTP error code in the 400s or 500s will be returned. An error code of 500 generally indicates an error with our servers whereas an error code in the 400s is generally an error with the data sent to the server. In such cases the HTTP response will return a header named 'x-error-message'. Below are some errors that are common to many operations. Each operation also has some specific errors which are outlined with the operation.

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
|Format is invalid
|400
|When requesting an index or show on a resource the 'Accept' header should be either 'text/xml' or 'application/json'
|-
|Customer account number is invalid
|404
|Invalid account number
|-
|Domain is not found
|404
|<domain name> not found
|-
|Mailbox is not found
|404
|Mailbox not found
|-
|Required form field is missing
|400
|Missing required field: <required field>
|-
|Required form field has null or empty string input
|400
|Required field <required field> cannot be empty
|-
|Integer form field has non-integer input
|400
|Invalid format for <field>, input must be an integer
|-
|Boolean form field has non-boolean input
|400
|Invalid format for <field>, input must be True or False
|-
|Form data has an unrecognized field
|400
|Unrecognized field: <field>
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== 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.
|}

== 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>
module NetMethods
def get(url_string, format)
url = URI.parse('https://' + server_host + server_port + version + url_string)
@response = Net::HTTP::start(url.host, url.port) do |http|
sign_request
assign_format(format)
@request = Net::HTTP::Get.new(url.path, @headers)

http.request(@request)
end
end

def post(url_string, format, fields_hash)
url = URI.parse('https://' + server_host + server_port + version + url_string)

sign_request
assign_format(format)
@request = Net::HTTP::Post.new(url.path, @headers)

@request.set_form_data(fields_hash)
@response = Net::HTTP::start(url.host, url.port) do |http|
http.request(@request)
end
end

def assign_format (format)
@headers['Accept'] = format
end

def sign_request
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S')
apiKey = 'XXXXXXXXXXXXXXXXXXXX'
secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

data_to_sign = apiKey + userAgent + timestamp + secretKey

signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))

@headers = Hash.new
@headers['User-Agent'] = userAgent
@headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature
end

def server_host
'api.emailsrvr.com'
end

def server_port
':80'
end

def version
'/v0'
end
end
</pre>

=== C# ===

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

<pre>
using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = 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);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

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

Exchange Distribution List (Rest API)

2010-05-03T15:40:43Z

Kevin.lin: moved Distribution List (Rest API) to Exchange Distribution List (Rest API)

__TOC__

=== Index ===

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

''Description'':

This operation returns a list of distribution lists associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/DistributionlistList.xsd DistributionlistList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists?size=100&page=1&contains=mailing', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<distributionlistList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:xml:distributionlistList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<distributionlists>
<distributionlist>
<name>apiexgroup4</name>
<displayName>API Test Group</displayName>
</distributionlist>
<distributionlist>
<name>apiexgroup62</name>
<displayName>API Test Group</displayName>
</distributionlist>
<distributionlist>
<name>apiexgroup64</name>
<displayName>API Test Group</displayName>
</distributionlist>
</distributionlists>
</distributionlistList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"distributionlists":[{"name":"apiexgroup4","displayName":"API Test Group"},{"name":"apiexgroup62","displayName":"API Test Group"},{"name":"apiexgroup64","displayName":"API Test Group"}]}

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Distribution List is not found
| 404
| Distribution List not found
|}

=== Show ===

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

''Description'':

Returns the distribution list's details.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Distributionlist.xsd Distributionlist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

''XML Result Example''

<pre>
<?xml version="1.0" encoding="utf-8"?>
<distributionlist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contact">
<name>apiexgroup64</name>
<displayName>API Test Group</displayName>
<isHidden>false</isHidden>
<emailAddressList>
<emailAddress>
<address>apiexgroup64@apidomain36.com</address>
<replyTo>true</replyTo>
</emailAddress>
</emailAddressList>
<memberList>
<member>apiexmailbox30@apidomain36.com</member>
<member>apiexmailbox7@apidomain36.com</member>
<member>apiexmailbox99@apidomain36.com</member>
</memberList>
</distributionlist>
</pre>

''Json Result Example'':

{"name":"apiexgroup64","displayName":"API Test Group","isHidden":false,"emailAddressList":[{"address":"apiexgroup64@apidomain36.com","replyTo":true}],"memberList":["apiexmailbox30@apidomain36.com","apiexmailbox7@apidomain36.com","apiexmailbox99@apidomain36.com"]}

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Add/Edit ===

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

''Description'':

Adds/edits the distribution list with the specified information. Required fields must be supplied when adding. Others are optional.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Distribution list display name (Required)
|-
| isHidden
| boolean
| Whether or not the distribution list is hidden from the Global Address List (Defaults to false)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'name' => 'all.employees',
'displayName' => 'Employees'
},
'text/xml'
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'displayName' => 'Example.com Employees'
},
'text/xml',
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| New distribution list name already exists
| 400
| The email address john.doe@abc.com is already in use
|-
| New distribution list name doesn't meet the naming requirements
| 400
| Invalid user name
|-
| New distribution list display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Distribution list is not found
| 404
| Distribution List not found
|-
| Display name doesn't meet the naming requirements
| 400
| Invalid display name
|}

=== Delete ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)</nowiki>

''Description'':

Deletes the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Email Addresses ===

This refers to the email addresses a distribution list can appear as.

==== Add Email Address ====

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

''Description'':

Adds an email address that the distribution list is associated with to the list. This address' domain name must be the same as the domain the distribution list is under.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/emailaddresses/alex@example.com', {}, 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Distribution list is not found
| 404
| Distribution list not found
|}

==== Delete Email Address ====

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

''Description'':

Deletes the email address that is tied to the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/emailaddresses/alex@example.com', 'text/xml'
</pre>

=== Member ===

This refers to the recipients of the distribution list.

==== Add Member ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)/members/(member name)</nowiki>

''Description'':

Adds an email address to the distribution list.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| New member is not found
| 400
| No user with the email address jane.doe exists
|}

==== Delete Member ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)/members/(member name)</nowiki>

''Description'':

Delete an email address from the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| Member is not found
| 400
| Invalid group member name
|}

Distribution List (Rest API)

2010-05-03T15:40:43Z

Kevin.lin: moved Distribution List (Rest API) to Exchange Distribution List (Rest API)

#REDIRECT [[Exchange Distribution List (Rest API)]]

Exchange Contact (Rest API)

2010-05-03T15:40:11Z

Kevin.lin: moved Contact (Rest API) to Exchange Contact (Rest API)

__TOC__

=== Index ===

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

''Description'':

Returns a list of contacts under the domain.

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ContactList.xsd ContactList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts?size=100&page=1&contains=john', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<contactList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contactList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<contacts>
<contact>
<name>apiexcontact66</name>
<displayName>API Test</displayName>
<externalEmail>externalemail58@yahoo.com</externalEmail>
</contact>
<contact>
<name>apiexcontact73</name>
<displayName>API Test</displayName>
<externalEmail>externalemail98@yahoo.com</externalEmail>
</contact>
<contact>
<name>apiexcontact81</name>
<displayName>API Test</displayName>
<externalEmail>externalemail46@yahoo.com</externalEmail>
</contact>
</contacts>
</contactList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"contacts":[{"name":"apiexcontact66","displayName":"API Test","externalEmail":"externalemail58@yahoo.com"},{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com"},{"name":"apiexcontact81","displayName":"API Test","externalEmail":"externalemail46@yahoo.com"}]}

=== Show ===

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

''Description'':

Returns the contact's details.

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Contact.xsd Contact.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<contact xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contact">
<name>apiexcontact73</name>
<displayName>API Test</displayName>
<externalEmail>externalemail98@yahoo.com</externalEmail>
<isHidden>false</isHidden>
<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>
</contactInfo>
</contact>
</pre>

''Json Result Example'':

{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com","isHidden":false,"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"}}

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Contact is not found
| 404
| Contact not found
|}

=== Add/Edit ===

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)

Edit: [PUT] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)</nowiki>

''Description'':

Adds or edits the contact's details as specified. If the contact does not exist, use Add, if it does, use Edit.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Name of contact when displayed (Required for add)
|-
| externalEmail
| string
| Email address (Required for add)
|-
| isHidden
| boolean
| Whether the contact is hidden from the Global List
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| jobTitle
| string
| Job title
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| businessNumber
| string
| Business phone number
|-
| homeNumber
| string
| Home phone number
|-
| mobileNumber
| string
| Mobile phone number
|-
| faxNumber
| string
| Fax number
|-
| pagerNumber
| string
| Pager number
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| notes
| string
| Notes field
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml',
{
'displayName' => 'Johnny Customer',
'externalEmail' => 'jonny@apple.com'
}
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml',
{
'externalEmail' => 'jonnysNewEmail@microsoft.com',
'company' => 'Microsoft',
'businessnumber' => '425 555 5555'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Contact is not found
| 404
| No user with the email address jane.doe@abc.com exists
|-
| New display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| New display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| New contact name (user name) already exists
| 400
| The email address john.doe@abc.com is already in use
|-
| New contact name (user name) is reserved by Exchange
| 400
| user name reserved
|}

=== Delete ===

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

''Description'':

Deletes the contact.

''Remarks'':

Contact is deleted immediately without verification and data is lost permanently.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Contact is not found
| 404
| No user with the email address jane.doe@abc.com exists
|}

Contact (Rest API)

2010-05-03T15:40:11Z

Kevin.lin: moved Contact (Rest API) to Exchange Contact (Rest API)

#REDIRECT [[Exchange Contact (Rest API)]]

Exchange Mailbox Spam (Rest API)

2010-05-03T15:39:41Z

Kevin.lin: Created page with '__TOC__ == Spam Settings == === Show === ''URL'': <nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name) /ex/mailboxes…'

__TOC__

== Spam Settings ==

=== Show ===

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

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/MailboxSpamSetting.xsd MailboxSpamSetting.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<MailboxSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:MailboxSpamSettings">
<filterLevel>on</filterLevel>
<sendToDomainQuarantine>false</sendToDomainQuarantine>
<quarantineOwner />
</MailboxSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","sendToDomainQuarantine":false,"quarantineOwner":""}

=== Edit ===

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

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

== Blacklist ==

=== Index ===

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

''Description'':

This operation returns email address blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Blacklist.xsd Blacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blacklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blacklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

=== Add ===

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

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@spam.com', {},'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

=== Delete ===

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

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the blacklist
|}

== IP Blacklist ==

=== Index ===

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

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpBlacklist.xsd IpBlacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist', 'text/xml'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

=== Add ===

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

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/216.12.34.1', {},'text/xml'
</pre>

=== Delete ===

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

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

== Safelist ==

=== Index ===

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

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Safelist.xsd Safelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

=== Add ===

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

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', {},'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

=== Delete ===

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

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

== IP Safelist ==

=== Index ===

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

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpSafelist.xsd IpSafelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

=== Add ===

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

''Description'':

Adds an IP to the ipsafelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', {},'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Delete ===

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

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

Rest API

2010-05-03T15:38:58Z

Kevin.lin: /* Operations */ Going to new title structure

== Recent Changes ==

'''03/28/10 '''
{|
|
New features:
* Rest API can be accessed by Business Users. However, not all operations are available.
* Domain Public Folders can be enabled now.
|
|}

{|
|
Deprecated:
* Good Mobile Service is no longer supported.
|
|}

'''03/14/10 '''
{|
|
New features:
* Index/Add/Edit/Delete Mailbox Permissions.
|
|}

{|
|
Known Issues:
* Domain public folders can't be enabled using Rest API at this moment. The next release (on 03/21/2010) will fix this problem.
|
|}

'''01/31/10 '''
{|
|
New features:
* Index/Show/Add/Edit/Delete Resource Mailboxes.
* Index/Add/Delete Resource Mailbox Admins.
|
|}

'''11/22/09 '''
{|
|
New features:
*Index/Add/Delete Alternate Domains.
*Show/Edit Domain Spam Settings.
*Index/Add/Delete Domain Blacklist/Safelist.
*Show/Edit Split Domain Routing.
*Show Mailbox ActiveSync Setup Info.
|
|}

== Introduction ==

The Email & Apps Control Panel 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]

== 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
| None
|-
| [[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|Domain Public Folders ]]
|-
| [[Domain_(Rest_API)| Domain Spam Settings]]
| /customers/123456789/domains/example.com/spam
| 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
|}

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

== Accessing the API ==

Your application will need to make HTTP requests to remote servers. Most programming languages have this function provided in its class library. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.


Calls without [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS] (formerly SSL) will complete successfully but it is HIGHLY RECOMMENDED that TLS always be used. Interception of unencrypted communication will allow a third party to have complete access to all functions available via the API.

For some language libraries just using an URL 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/v0/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

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

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/v0/. 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.

{| 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 that are generated from the Control Panel Web interface.

{| 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'''>:<'''Signature'''> 
Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

 
'''Signature''':

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 URLs, corresponding HTTP Methods, and necessary form data for the desired operations are detailed in the [[#Operations|operation pages]].

==== 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 consistent and is outlined in the table 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''
|-
| Accept
| The requested content type (required regardless of type of operation). 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=''
|}

==== 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
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

'''Reference Number'''

For the customer object only, the query string "referenceNumber=xx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The current limit is 60 requests 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.

==== Examples ====

Example requests:
<pre>
Index of Exchange Mailboxes:

Hypertext Transfer Protocol
GET /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Request Method: GET
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml

Adding New Exchange Mailbox:

Hypertext Transfer Protocol
POST /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Request Method: POST
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
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 ===

On a successfully executed request, a 200 HTTP Code is returned. Requested data is also returned if the operation was a Show or Index action. If the request is unsuccessful, then an error HTTP Code is returned with a message detailing the error. The errors and their corresponding codes are detailed on the operation pages.

==== 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 extract data from 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 library with the functions necessary for whichever method you choose to use to extract data.

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.

==== Errors ====

If a request is not sucessfully completed an HTTP error code in the 400s or 500s will be returned. An error code of 500 generally indicates an error with our servers whereas an error code in the 400s is generally an error with the data sent to the server. In such cases the HTTP response will return a header named 'x-error-message'. Below are some errors that are common to many operations. Each operation also has some specific errors which are outlined with the operation.

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
|Format is invalid
|400
|When requesting an index or show on a resource the 'Accept' header should be either 'text/xml' or 'application/json'
|-
|Customer account number is invalid
|404
|Invalid account number
|-
|Domain is not found
|404
|<domain name> not found
|-
|Mailbox is not found
|404
|Mailbox not found
|-
|Required form field is missing
|400
|Missing required field: <required field>
|-
|Required form field has null or empty string input
|400
|Required field <required field> cannot be empty
|-
|Integer form field has non-integer input
|400
|Invalid format for <field>, input must be an integer
|-
|Boolean form field has non-boolean input
|400
|Invalid format for <field>, input must be True or False
|-
|Form data has an unrecognized field
|400
|Unrecognized field: <field>
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== 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.
|}

== 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>
module NetMethods
def get(url_string, format)
url = URI.parse('https://' + server_host + server_port + version + url_string)
@response = Net::HTTP::start(url.host, url.port) do |http|
sign_request
assign_format(format)
@request = Net::HTTP::Get.new(url.path, @headers)

http.request(@request)
end
end

def post(url_string, format, fields_hash)
url = URI.parse('https://' + server_host + server_port + version + url_string)

sign_request
assign_format(format)
@request = Net::HTTP::Post.new(url.path, @headers)

@request.set_form_data(fields_hash)
@response = Net::HTTP::start(url.host, url.port) do |http|
http.request(@request)
end
end

def assign_format (format)
@headers['Accept'] = format
end

def sign_request
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S')
apiKey = 'XXXXXXXXXXXXXXXXXXXX'
secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

data_to_sign = apiKey + userAgent + timestamp + secretKey

signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))

@headers = Hash.new
@headers['User-Agent'] = userAgent
@headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature
end

def server_host
'api.emailsrvr.com'
end

def server_port
':80'
end

def version
'/v0'
end
end
</pre>

=== C# ===

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

<pre>
using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = 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);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

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

Exchange Mailbox (Rest API)

2010-05-03T15:30:17Z

Kevin.lin: moved Mailbox (Rest API) to Exchange Mailbox (Rest API)

__TOC__

== Index ==

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Remarks'':

The show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/MailboxList.xsd MailboxList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes', 'text/xml'
</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"}]}

== Show ==

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Mailbox.xsd Mailbox.xsd]

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', 'text/xml'
</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>
<isPublicFolderAdmin>true</isPublicFolderAdmin>
<enabled>true</enabled>
<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>
</contactInfo>
<emailForwardingAddress />
<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,"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"},"emailForwardingAddress":"","emailAddressList":[{"address":"apiexmailbox90@apidomain92.com","replyTo":true}],"hasBlackBerryMobileService":false,"hasActiveSyncMobileService":false,"samAccountName":"apiexmailbox90_53B5B"}

== Add/Edit ==

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)
Edit: [PUT] https://api.emailsrvr.com/v0/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.

{| 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
|-
| 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.)
|-
| enabled
| string
| Enable/Disable mailbox, input must be "true" or "false"
|}

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

<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith', 'text/xml',
{
'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/v0/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', 'text/xml'
</pre>

== Add Email Address ==

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/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', 'text/xml'
</pre>

== Delete Email Address ==

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/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', 'text/xml'
</pre>

== 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/v0/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', 'text/xml'
</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/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Grants user2 the specified permission on mailbox of user1.

{| 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'}, 'text/xml'
</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/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Modifies permission granted to user2 on the mailbox of user1.

{| 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'}, 'text/xml'
</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/v0/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', 'text/xml'
</pre>

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

== Spam ==

=== Index Blacklist ===

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

''Description'':

This operation returns email address blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Blacklist.xsd Blacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blacklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blacklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

=== Index IP Blacklist ===

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

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpBlacklist.xsd IpBlacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist', 'text/xml'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

=== Index Safelist ===

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

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Safelist.xsd Safelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

=== Index IP Safelist ===

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

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpSafelist.xsd IpSafelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

=== Add Blacklist ===

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

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@spam.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

=== Add IP Blacklist ===

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

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/216.12.34.1', 'text/xml'
</pre>

=== Add Safelist ===

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

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

=== Add IP Safelist ===

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

''Description'':

Adds an IP to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Delete Blacklist ===

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

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the blacklist
|}

=== Delete IP Blacklist ===

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

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

=== Delete Safelist ===

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

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

=== Delete IP Safelist ===

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

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

=== Show Spam Setting ===

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

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/MailboxSpamSetting.xsd MailboxSpamSetting.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<MailboxSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:MailboxSpamSettings">
<filterLevel>on</filterLevel>
<sendToDomainQuarantine>false</sendToDomainQuarantine>
<quarantineOwner />
</MailboxSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","sendToDomainQuarantine":false,"quarantineOwner":""}

=== Edit Spam Setting ===

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

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

== BlackBerry Mobile Service ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/BlackberryMobileServiceList.xsd BlackberryMobileServiceList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/blackberrymobileservices', 'text/xml'
</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/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/blackberrymobileservice</nowiki>

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

{| 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', 'text/xml',
{
'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/v0/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', 'text/xml'
</pre>

== ActiveSync Mobile Service ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ActiveSyncMobileServiceList.xsd ActiveSyncMobileServiceList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/activesyncmobileservices', 'text/xml'
</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/v0/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. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ActiveSyncMobileService.xsd ActiveSyncMobileService.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', 'text/xml'
</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/v0/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', 'text/xml', {}
</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/v0/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', 'text/xml'
</pre>

Mailbox (Rest API)

2010-05-03T15:30:17Z

Kevin.lin: moved Mailbox (Rest API) to Exchange Mailbox (Rest API)

#REDIRECT [[Exchange Mailbox (Rest API)]]

Main Page

2010-03-29T17:58:04Z

Kevin.lin: Syncing to latest.

__NOTOC__
== The Rackspace Email API ==

The Rackspace Email [http://en.wikipedia.org/wiki/Api API] comprises a robust set of web services designed to allow businesses to fully integrate administrative email functions into their own applications. Based on [http://en.wikipedia.org/wiki/SOAP SOAP], functions in the API allow programs written in many different languages to perform operations such as [[AddUser()|adding mailboxes]] and changing settings. The API can also be used to provide [[LoginUserWebmail()|single sign on]] functionality in concert with other web applications. The Webmail API runs on the same robust server platform that supports our high-availability [http://www.rackspace.com/email_hosting webmail] and email services.

----------------
== API System Upgrades, March 2009 ==

On March 7th the [[webmail|Webmail User API]] will be updated to use the most recent and robust systems at Rackspace Email. No changes to code written by Rackspace Email customers should be needed to take advantage of the update. If desired, code may be updated to use the latest URI found in the [[webmail|Webmail User API]] documentation, though the old URI will be automatically redirected to the new URI by Rackspace Email on March 7th.

RISKS: After extensive testing Rackspace Email has concluded that there is a risk for customers using programming libraries that send the HTTP EXPECT header with their requests. This update moves the API to a much more robust and scalable system, but the system will return errors if this header is included in a request.

An excellent discussion around turning off EXPECT headers for .NET and PHP may be found in this [http://groups.google.com/group/twitter-development-talk/browse_thread/thread/7c67ff1a2407dee7?pli=1 thread] about Twitter.

----------------
=== Rackspace Email API ===
* [[webmail|Webmail User API]] - provides a short list of webmail user functions

* [[business|Business API]] - provides a list of functions designed for single business/domain usage

* [[reseller|Reseller API]] - provides a complete list of functions for multiple domains and sub-accounts

* [[Rest_API|Rest API]] - the RESTful API with functions for customers, domains and Exchange services

=== Code Examples ===

{|
|
*[[Perl]]
|
*[[PHP]]
|-
|
*[[ASP]]
|
*[[C#]]
|-
|
*[[ColdFusion]]
|
*[[Ruby]]
|-
|
* [[HTML]] (not part of the API, strictly speaking)
|}

=== Getting Started Screencast ===
[http://www.mailtrust.com/api-wiki/screencasts/api-pings.htm Screencast] of accessing two of our SOAP API's from PHP using Ubuntu linux.

=== Result Codes ===
Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

Main Page

2010-03-29T15:25:25Z

Kevin.lin: Spacing change

__NOTOC__
== The Rackspace Email API ==

The Rackspace Email [http://en.wikipedia.org/wiki/Api API] comprises a robust set of web services designed to allow businesses to fully integrate administrative email functions into their own applications. Based on [http://en.wikipedia.org/wiki/SOAP SOAP], functions in the API allow programs written in many different languages to perform operations such as [[AddUser()|adding mailboxes]] and changing settings. The API can also be used to provide [[LoginUserWebmail()|single sign on]] functionality in concert with other web applications. The Webmail API runs on the same robust server platform that supports our high-availability [http://www.rackspace.com/email_hosting webmail] and email services.

----------------
== API System Upgrades, March 2009 ==

On March 7th the [[webmail|Webmail User API]] will be updated to use the most recent and robust systems at Rackspace Email. No changes to code written by Rackspace Email customers should be needed to take advantage of the update. If desired, code may be updated to use the latest URI found in the [[webmail|Webmail User API]] documentation, though the old URI will be automatically redirected to the new URI by Rackspace Email on March 7th.

RISKS: After extensive testing Rackspace Email has concluded that there is a risk for customers using programming libraries that send the HTTP EXPECT header with their requests. This update moves the API to a much more robust and scalable system, but the system will return errors if this header is included in a request.

An excellent discussion around turning off EXPECT headers for .NET and PHP may be found in this [http://groups.google.com/group/twitter-development-talk/browse_thread/thread/7c67ff1a2407dee7?pli=1 thread] about Twitter.

----------------
=== Rackspace Email API ===
* [[webmail|Webmail User API]] - provides a short list of webmail user functions

* [[business|Business API]] - provides a list of functions designed for single business/domain usage

* [[reseller|Reseller API]] - provides a complete list of functions for multiple domains and sub-accounts

* [[beta|Beta API]] - a list of functions in public beta testing

=== Code Examples ===

{|
|
*[[Perl]]
|
*[[PHP]]
|-
|
*[[ASP]]
|
*[[C#]]
|-
|
*[[ColdFusion]]
|
*[[Ruby]]
|-
|
* [[HTML]] (not part of the API, strictly speaking)
|}

=== Getting Started Screencast ===
[http://www.mailtrust.com/api-wiki/screencasts/api-pings.htm Screencast] of accessing two of our SOAP API's from PHP using Ubuntu linux.

=== Result Codes ===
Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

This is a Rackspace Cloud Sites-hosted wiki.

PHP Examples (Rest API)

2010-03-29T15:25:00Z

Kevin.lin: Sync to latest.

=== PHP ===

<pre>
<?php
class WebMethods
{
const VERSION = 'v0';
const SERVER_HOST = 'api.emailsrvr.com';

public function get($url_string, $format)
{
$url = $this->getUrl($url_string);
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);
$session = curl_init($url);
curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);

echo $response;
}

public function post($url_string, $fields, $format)
{
$url = $this->getUrl($url_string);
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);
$session = curl_init($url);

curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_POST, true);
curl_setopt($session, CURLOPT_POSTFIELDS, $fields);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);

echo $response;
}

public function put($url_string, $fields, $format)
{
$url = $this->getUrl($url_string);
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);
$session = curl_init($url);

curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_CUSTOMREQUEST, 'PUT');
curl_setopt($session, CURLOPT_POSTFIELDS, $fields);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);

echo $response;
}

public function delete($url_string, $format)
{
$url = $this->getUrl($url_string);
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);
$session = curl_init($url);

curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_CUSTOMREQUEST, 'DELETE');
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);

echo $response;
}

public function signRequest(&$headers)
{
$user_agent = 'Api Test';
$time_stamp = 'YYYYMMDDHHmmss';
$api_key = 'XXXXXXXXXXXXXXXXXXXX';
$secret_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

$data_to_sign = $api_key . $user_agent . $time_stamp . $secret_key;
$signature = base64_encode(sha1($data_to_sign, true));

$headers[] = "User-Agent: $user_agent";
$headers[] = "X-Api-Signature: $api_key:$time_stamp:$signature";
}

public function assignFormat(&$headers, $format)
{
$headers[] = "Accept: $format";
}

public function getUrl($url_string)
{
$url = 'http://' . self::SERVER_HOST . '/' . self::VERSION . $url_string;
return $url;
}
}
?>
</pre>

<pre>
<?php
require_once 'WebMethods.php';

$client = new WebMethods();

$url = '/customers';
$form = 'name=new customer&referenceNumber=1000';
$format = 'text/xml';

$client->post($url, $form, $format);
?>
</pre>

Resource Mailbox (Rest API)

2010-03-29T15:24:33Z

Kevin.lin: Sync to latest

__TOC__

=== Index ===

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

''Description'':

This operation returns a list of resource mailboxes associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ResourceList.xsd ResourceList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/resources?size=100&page=1&contains=conference', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<resourceList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:resourceList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<resources>
<resource>
<name>apiexresource43</name>
<displayName>API Test</displayName>
<type>room</type>
</resource>
<resource>
<name>apiexresource5</name>
<displayName>API Test</displayName>
<type>equipment</type>
</resource>
<resource>
<name>apiexresource85</name>
<displayName>API Test</displayName>
<type>room</type>
</resource>
</resources>
</resourceList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"resources":[{"name":"apiexresource43","displayName":"API Test","type":"room"},{"name":"apiexresource5","displayName":"API Test","type":"equipment"},{"name":"apiexresource85","displayName":"API Test","type":"room"}]}

=== Show ===

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

''Description'':

Returns the resource's details.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Resource.xsd Resource.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/resource/conference.room', 'text/xml'
</pre>

''XML Result Example''

<pre>
<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
<resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:resource">
<name>apiexresource43</name>
<displayName>API Test</displayName>
<type>room</type>
</resource>
</pre>

''Json Result Example'':

{"name":"apiexresource43","displayName":"API Test","type":"room"}

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Resource is not found
| 404
| Resource not found
|-
| Entity is found but it's not a resource mailbox
| 404
| Mailbox is not a resource.
|}

=== Add/Edit ===

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

''Description'':

Adds/edits the resource with the specified information. Required fields must be supplied when adding. Others are optional.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Resource display name (Required for add)
|-
| type
| string
| The resource type, 'room' or 'equipment' (Required for add, not available for edit)
|-
| password
| string
| The password to change the settings of the mailbox or add/remove admins (Required for add)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/resources/conference.room',
{
'displayName' => 'Conference Room'
'type' => 'room'
'password' => 'abcDEF123'
},
'text/xml'
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/resources/all.employees',
{
'displayName' => 'Conference Room A'
'password' => 'ABCd4321'
},
'text/xml',
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| New resource mailbox already exists
| 400
| The email address conference.room@abc.com is already in use
|-
| New resource mailbox name doesn't meet the naming requirements
| 400
| Invalid resource name
|-
| New display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Invalid resource mailbox type
| 400
| Invalid Resource Type. The input must be: room/equipment.
|}

=== Delete ===

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

''Description'':

Deletes the resource.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/resources/all.employees', 'text/xml'
</pre>

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Resource is not found
| 404
| Resource not found
|-
| Entity is found but it's not a resource mailbox
| 404
| Mailbox is not a resource.
|}

=== Admins ===

This refers to the admins that can manage the resource.

==== Index Admin ====

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

''Description'':

Gets the list of resource admins.

''Remarks'':

The Index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ResourceAdminList.xsd ResourceAdminList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/resources/conference.room/admins', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<resourceAdminList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:resourceAdminList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<admins>
<admin>apiexmailbox70@apidomain90.com</admin>
<admin>apiexmailbox87@apidomain90.com</admin>
<admin>apiexmailbox89@apidomain90.com</admin>
</admins>
</resourceAdminList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"admins":["apiexmailbox70@apidomain90.com","apiexmailbox87@apidomain90.com","apiexmailbox89@apidomain90.com"]}

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Resource is not found
| 404
| Resource not found
|-
| Entity is found but it's not a resource mailbox
| 404
| Mailbox is not a resource.
|}

==== Add Admin ====

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/resources/(resource name)/admins/(admin name)</nowiki>

''Description'':

Adds an admin to the resource.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/resources/conference.room/admins/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Resource not found
| 404
| Resource not found
|}

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Resource is not found
| 404
| Resource not found
|-
| Entity is found but it's not a resource mailbox
| 404
| Mailbox is not a resource.
|-
| Admin is already on the resource admin list.
| 400
| User is already on the resource admin list.
|}

==== Delete Admin ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/resources/(resource name)/admins/(admin name)</nowiki>

''Description'':

Removes the admin from the resource.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/resources/conference.room/admins/john.smith', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Resource is not found
| 404
| Resource not found
|-
| Entity is found but it's not a resource mailbox
| 404
| Mailbox is not a resource.
|-
| Admin is not found on the resource admin list.
| 400
| User is not on the resource admin list.
|}

Exchange Mailbox (Rest API)

2010-03-29T15:23:36Z

Kevin.lin: Sync to latest

Domain (Rest API)

2010-03-29T15:23:07Z

Kevin.lin: Sync to latest

__TOC__

== Index ==

''URL'':

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

''Description'':

This operation returns a list of domains under the account. If a customer account is specified, then a list of domains under that specific account will be returned.

''Remarks'':

To retrieve a list of domains owned by the account that is logged in, use "me" as the customer account number i.e. <nowiki>'https://api.emailsrvr.com/v0/customers/me/domains'</nowiki>. To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number.

The index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/DomainList.xsd DomainList.xsd]

''Example'':

<pre>
get '/customers/all/domains?size=100&page=1', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?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>3</total>
<domains>
<domain>
<name>apidomain53.com</name>
<accountNumber>100000</accountNumber>
<serviceType>both</serviceType>
</domain>
<domain>
<name>apidomain66.com</name>
<accountNumber>100001</accountNumber>
<serviceType>both</serviceType>
</domain>
<domain>
<name>apidomain68.com</name>
<accountNumber>100002</accountNumber>
<serviceType>both</serviceType>
</domain>
</domains>
</domainList>
</pre>

''Json Result Example'':

<pre>
{"offset":0,"size":50,"total":3,"domains":
[{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both"},
{"name":"apidomain66.com","accountNumber":"100001","serviceType":"both"},
{"name":"apidomain68.com","accountNumber":"100002","serviceType":"both"}]}
</pre>

== Show ==

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)</nowiki>

''Description'':

The show operation will return detailed information about the specified domain name.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Domain.xsd Domain.xsd]

''Example'':

<pre>
get '/customers/999999/domains/example.com', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<domain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domain">
<name>apidomain21.com</name>
<accountNumber>100000</accountNumber>
<serviceType>both</serviceType>
<exchangeBaseMailboxSize>2048</exchangeBaseMailboxSize>
<exchangeUsedStorage>0</exchangeUsedStorage>
<exchangeTotalStorage>18432</exchangeTotalStorage>
<exchangeExtraStorage>10240</exchangeExtraStorage>
<exchangeMaxNumMailboxes>4</exchangeMaxNumMailboxes>
<rsEmailBaseMailboxSize>2048</rsEmailBaseMailboxSize>
<rsEmailMaxNumberMailboxes>4</rsEmailMaxNumberMailboxes>
<rsEmailExtraStorage>10240</rsEmailExtraStorage>
<rsEmailUsedStorage>0</rsEmailUsedStorage>
<aliases />
<archivingServiceEnabled>false</archivingServiceEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
<goodMobileServiceEnabled>true</goodMobileServiceEnabled>
<goodMobileLicenses>4</goodMobileLicenses>
</domain>
</pre>

''Json Result Example'':
<pre>
{"name":"apidomain21.com","accountNumber":"100000","serviceType":"both",
"exchangeBaseMailboxSize":2048,"exchangeUsedStorage":0,"exchangeTotalStorage":18432,
"exchangeExtraStorage":10240,"exchangeMaxNumMailboxes":4,"rsEmailBaseMailboxSize":2048,
"rsEmailMaxNumberMailboxes":4,"rsEmailExtraStorage":10240,"rsEmailUsedStorage":0,
"aliases":[],"archivingServiceEnabled":false,"blackBerryMobileServiceEnabled":true,
"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,"activeSyncLicenses":4,
"goodMobileServiceEnabled":true,"goodMobileLicenses":4}
</pre>

== Add/Edit (Reseller Only) ==

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

''Description'':

Adds/edits a new domain to the account with the data specified. To add a domain to your own account, use your own account id.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| serviceType
| string
| Domain service type. "rsemail" = "Rackspace Email Only". "exchange" = "Exchange Only". "both" = "Rackspace Email and Exchange"
|-
| exchangeExtraStorage
| int
| Exchange service extra storage in megabytes
|-
| exchangeMaxNumMailboxes
| int
| Maximum number of mailboxes allowed under the domain Exchange service. Required for Adding Exchange service
|-
| rsEmailBaseMailboxSize
| int
| Rackspace Email base mailbox size in megabytes
|-
| rsEmailMaxNumberMailboxes
| int
| Maximum number of mailboxes allowed under the domain Rackspace Email service. Required for Adding Rackspace Email service
|-
| rsEmailExtraStorage
| int
| Rackspace Email service extra storage in megabytes
|-
| blackBerryMobileServiceEnabled
| boolean
| Enable or disable domain BlackBerry Mobile service
|-
| blackBerryLicenses
| int
| Maximum number of mailboxes allowed to have BlackBerry Mobile service. 0 means unlimited
|-
| activeSyncMobileServiceEnabled
| boolean
| Enable or disable domain ActiveSync Mobile service
|-
| activeSyncLicenses
| int
| Maximum number of mailboxes allowed to have ActiveSync Mobile service. 0 means unlimited
|-
| goodMobileServiceEnabled
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses
| int
| Maximum number of mailboxes allowed to have Good Mobile service. 0 means unlimited
|-
| archivingServiceEnabled
| boolean
| Enable or disable domain archiving service
|-
|}

''Example'':

<pre>
post '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '5',
'extraStorage' => '1024'
}
</pre>

<pre>
put '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '25',
'extraStorage' => '2048'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| New domain name doesn't meet the naming requirements
| 400
| Invalid domain name
|-
| New domain name already exists
| 400
| abc.com already exists as a domain or alternate domain
|}

== Move (Reseller Only) ==

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v0/customers/
(new customer account number)/domains/(domain name)</nowiki>

''Description'':

Moves the domain to another customer account.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| moveDomain
| boolean
| Indicate whether or not moving the domain
|}

''Remarks'':

Note 'Move Domain' and 'Edit Domain' share the same URI and HTTP verb. When the domain doesn't belong to the customer and 'moveDomain' is set to 'true', API will take the request as a 'Move Domain' call.

''Example'':

<pre>
put '/customers/123456/domains/newcompany.com', 'text/xml',
{
'moveDomain' => 'true'
}
</pre>

== Delete (Reseller Only) ==

''URL'':

<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)</nowiki>

''Description'':

Deletes the domain.

''Remarks'':

The domain and all the mailboxes, mailbox contents, groups, and contacts are deleted permanently.

''Example'':

<pre>
delete '/customers/12345678/domains/newcompany.com', 'text/xml'
</pre>

== Spam ==

=== Index Blacklist ===

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

''Description'':

This operation returns the email address blacklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Blacklist.xsd Blacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/blacklist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blacklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blacklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

=== Index IP Blacklist ===

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

''Description'':

This operation returns IP blacklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpBlacklist.xsd IpBlacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipblacklist', 'text/xml'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

=== Index Safelist ===

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

''Description'':

This operation returns email address safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Safelist.xsd Safelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/safelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

=== Index IP Safelist ===

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

''Description'':

This operation returns IP safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpSafelist.xsd IpSafelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipsafelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

=== Add Blacklist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/blacklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blacklist/anyone@spam.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

=== Add IP Blacklist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Add Safelist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

=== Add IP Safelist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Delete Blacklist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/blacklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the list
|}

=== Delete IP Blacklist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipblacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

=== Delete Safelist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the list
|}

=== Delete IP Safelist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipsafelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the list
|}

=== Show Spam Setting ===

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

''Description'':

This operation returns the spam settings associated with the domain.

''Remarks'':

The Show operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/DomainSpamSetting.xsd DomainSpamSetting.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/settings', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<domainSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:DomainSpamSettings">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toAddress</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress>someone@mail.com</spamForwardingAddress>
</rsEmailSettings>
<exchangeSettings>
<forwardToDomainQuarantine>on</forwardToDomainQuarantine>
<quarantineOwner>someone@mail.com</quarantineOwner>
<defaultQuarantineOwner>someone@mail.com</defaultQuarantineOwner>
</exchangeSettings>
</domainSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","rsEmailSettings":{"spamHandling":"toAddress","hasFolderCleaner":false,"spamFolderAgeLimit":0,"spamFolderNumLimit":0,"spamForwardingAddress":"someone@mail.com"},"exchangeSettings":{"forwardToDomainQuarantine":"on","quarantineOwner":"someone@mail.com","defaultQuarantineOwner":"someone@mail.com"}}

=== Edit Spam Setting ===

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/settings</nowiki>

''Description'':

Edits the domain Spam Settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| overrideUserSettings
| boolean
| Set this flag to "true" to override preferences for all users regardless of their own preferences. Otherwise, it sets preferences only for users who have not set their own.
|-
| rsEmail.spamHandling
| string
| Change settings for Rackspace Email Handling. For the options, see the table below.
|-
| rsEmail.hasFolderCleaner
| boolean
| Turns on/off Spam Folder Cleaner. Requires "rsEmail.spamHandling" to be set to "toFolder".
|-
| rsEmail.spamFolderAgeLimit
| int
| The number of days that email stays the "Spam" folder before being deleted. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamFolderNumLimit
| int
| The max number of emails that will be kept in the "Spam" folder. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamForwardingAddress
| string
| The address that spams will be forwarded to. Requires "rsEmail.spamHandling" to be set to "toAddress".
|-
| exchange.forwardToDomainQuarantine
| string
| Change settings for Exchange Handling. For the options, see the table below.
|-
| exchange.quarantineOwner
| string
| The address that domain quarantine notifications will be sent to.
|-
| exchange.removeQuarantineOwner
| boolean
| Set this flag to "true" to remove domain quarantine owner.
|-
| exchange.defaultQuarantineOwner
| string
| The address that quarantine notifications will be sent to. This applies to new users and users that have not changed their settings to override.
|-
| exchange.removeDefaultQuarantineOwner
| boolean
| Set this flag to "true" to remove default domain quarantine owner.
|}

Rackspace Email Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| toFolder
| Deliver to Spam folder
|-
| delete
| Delete the email immediately
|-
| labelSubject
| Include "[SPAM]" at the beginning of the subject line
|-
| toAddress
| Deliver to the email address that is specified by "rsEmail.spamForwardingAddress"
|}

Exchange Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| on
| Send all spam to domain quarantine
|-
| off
| Send spam to recipient's quarantine
|-
| nonuser
| Send non-user spam (Contacts, Resources, etc.) to domain quarantine
|}

''Example'':

<pre>
put '/customers/me/domains/example.com/spam/settings', 'text/xml',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for Filter Level
| 400
| Invalid FilterLevel: high. Input must be: on/off/exclusive
|-
| Invalid input for RSEmail SpamHandling
| 400
| Invalid RSEmail SpamHandling: nonuser. Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid input for Exchange ForwardToDomainQuarantine
| 400
| Invalid input for Exchange ForwardToDomainQuarantine: delete. Input must be: on/off/nonuser
|}

== Alternate Domains ==

=== Index (Reseller Only) ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/
domains/(domain name)/alternatedomains</nowiki>

''Description'':

This operation returns a list of Domain Aliases and Accepted Domains for the domain. The type of the alternate domain is indicated by the 'type' data field. The XML schema for the returned data is [http://api.emailsrvr.com/v0/Schemas/DomainSplitRouting.xsd DomainAlternateList.xsd]

''Example'':

<pre>
get '/customers/12345678/domains/test.com/alternatedomains', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<alternateDomainList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainAlternateList">
<alternateDomains>
<alternateDomain>
<name>domainalias.com</name>
<type>DomainAlias</type>
</alternateDomain>
<alternateDomain>
<name>accepteddomain.com</name>
<type>AcceptedDomain</type>
</alternateDomain>
</alternateDomains>
</alternateDomainList>
</pre>

''Json Result Example'':

<pre>{"alternateDomains":[{"name":"domainalias.com","type":"DomainAlias"},{"name":"accepteddomain.com","type":"AcceptedDomain"}]}</pre>

=== Add (Reseller Only) ===

''URL'':
<nowiki>
[POST] https://api.emailsrvr.com/v0/customers/(customer account number)
/domains/(domain name)/alternatedomains/(alternate domain name)
</nowiki>

''Description'':

Adds either a Domain Alias or Accepted Domain to the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| type
| string
| Alternate domain type. Send "DomainAlias" for a domain alias, and "AcceptedDomain" for an accepted domain. (Required)
|-
| createForExistingRecipients
| boolean
| Whether the alternate addresses should be created for existing mailboxes when adding an Accepted Domain. Sending this field in the request when the type is Domain Alias will throw an error. This defaults to false.
|-
|}

''Example'':

<pre>
post '/customers/123456/domains/example.com/alternatedomains/accepteddomain.com', 'text/xml',
{
'type' => 'AcceptedDomain'
'createForExistingRecipients' => 'true'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| New domain name doesn't meet the naming requirements
| 400
| Invalid domain name
|-
| Alternate domain already exists
| 400
| abc.com already exists as a domain or alternate domain
|-
| The 'createForExistingRecipients' field was sent with either data, or as a null field. It should not be included in the form data at all.
| 400
| Invalid Alternate Domain Setting: createForExistingRecipients is an invalid setting for Domain Aliases
|-
| The only valid values for 'type' are 'DomainAlias' and 'AcceptedDomain', for a Domain Alias and Accepted Domain respectively.
| 400
| Invalid Alternate Domain type
|}

=== Delete (Reseller Only) ===

''URL'':

<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/
domains/(domain name)/alternatedomains/(alternate domain name)</nowiki>

''Description'':

Deletes the alternate domain.

''Example'':

<pre>
delete '/customers/12345678/domains/example.com/alternatedomains/accepteddomain.com'
</pre>

== Split Domain Routing ==

=== Show Settings ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain)/splitdomainrouting</nowiki>

''Description'':
Shows the current external email server. The XML schema document for the output of this command is [http://api.emailsrvr.com/v0/Schemas/DomainSplitRouting.xsd DomainSplitRouting.xsd]

''Example'':

<pre>
get '/customers/12345678/domains/company.com/splitdomainrouting', 'text/xml'
</pre>

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<splitDomainRouting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:splitDomainRouting">
<externalServer>email.externalserver.com</externalServer>
</splitDomainRouting>
</pre>

''JSON Result Example'':
<pre>
{"externalServer":"email.externalserver.com"}
</pre>

=== Edit Settings ===

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain)/splitdomainrouting</nowiki>

''Description'':

This command sets the external email server. This command will return a success when the verification passes. Since this involves communication to the external server the request may take some time. If the verification fails a 400 return code will be sent back with the verification's error message.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| externalServer
| string
| The address of the external email server. To turn off split domain routing send 'none'. (Required)
|-
| verificationAddress
| string
| An email address part of your domain or one of the alternate domains that the external server is already set up to handle. (Required only when turning on split domain routing, Do not send this field if turning off.)
|-
|}

''Example'':

<pre>
put '/customers/12345678/domains/company.com/splitdomainrouting', 'text/xml',
{
'externalServer' => 'email.externalserver.com',
'verificationAddress' => 'externalaccount@company.com',
}
</pre>

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The SMTP host could not be found.
| 400
| One of the verification error messages.
|}

== Archiving SSO Login URL ==

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain)/archivingSSOLoginURL</nowiki>

''Description'':

Gets the domain archiving service SSO login URL.

''Remarks'':

The retrieved URL can be used in browser to access the domain archiving control panel.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/archivingSSOLoginURL', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| No archiving service
| 404
| Domain abc.com has no archiving service enabled
|}

== Domain Public Folders (Reseller Only) ==

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

''Description'':

Enables the Exchange Public Folders feature on the domain. Once enabled, it cannot be disabled.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| enabled
| string
| Whether to enable public folders. Once enabled, it cannot be disabled.
|}

''Example'':

<pre>
put '/customers/12345678/domains/company.com/ex/publicFolders', 'text/xml',
{
'enabled' => 'true'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Public folders cannot be turned off after it's been turned on.
| 400
| Public Folders cannot be disabled once enabled
|}

Customer (Rest API)

2010-03-29T15:22:37Z

Kevin.lin: Sync to latest.

__TOC__

== Index (Reseller Only) ==

''URL'':

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

''Description'':

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

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/CustomerList.xsd CustomerList.xsd]

''Example'':

<pre>
get '/customers?size=100&page=1', 'text/xml'
</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/v0/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/v0/customers/me'</nowiki>.

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Customer.xsd Customer.xsd]

''Example'':

<pre>
get '/customers/me', 'text/xml'
</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>
</customer>
</pre>

''JSON Result Example'':

<pre>
{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"}
</pre>

== Add/Edit (Reseller Only) ==

''URL'':

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

''Description'':

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

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

''Example'':

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

<pre>
put '/customers/999999', 'text/xml',
{
'name' => 'NewName',
'referenceNumber' => '12345'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The name field was not specified
| 400
| Missing required field: name
|-
| The name field cannot be blank
| 400
| Required field name cannot be empty
|-
| Names cannot start with a space
| 400
| Improper Customer Name
|}

== Delete (Reseller Only) ==

''URL'':

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

''Description'':

Deletes the account.

''Example'':

<pre>
delete '/customers/999999', 'text/xml'
</pre>

Rest API

2010-03-29T15:22:08Z

Kevin.lin: Syncing to latest.

== Recent Changes ==

'''03/28/10 '''
{|
|
New features:
* Rest API can be accessed by Business Users. However, not all operations are available.
* Domain Public Folders can be enabled now.
|
|}

{|
|
Deprecated:
* Good Mobile Service is no longer supported.
|
|}

'''03/14/10 '''
{|
|
New features:
* Index/Add/Edit/Delete Mailbox Permissions.
|
|}

{|
|
Known Issues:
* Domain public folders can't be enabled using Rest API at this moment. The next release (on 03/21/2010) will fix this problem.
|
|}

'''01/31/10 '''
{|
|
New features:
* Index/Show/Add/Edit/Delete Resource Mailboxes.
* Index/Add/Delete Resource Mailbox Admins.
|
|}

'''11/22/09 '''
{|
|
New features:
*Index/Add/Delete Alternate Domains.
*Show/Edit Domain Spam Settings.
*Index/Add/Delete Domain Blacklist/Safelist.
*Show/Edit Split Domain Routing.
*Show Mailbox ActiveSync Setup Info.
|
|}

== Introduction ==

The Email & Apps Control Panel 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]

== 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
| None
|-
| [[Domain_(Rest_API)| Domain]]
| /customers/123456789/domains/example.com
| [[Domain_(Rest_API)#Index| Index]], [[Domain_(Rest_API)#Show| Show]],[[Domain_(Rest_API)#Spam| Domain Spam]], [[Domain_(Rest_API)#Split Domain Routing| Split Domain Routing]], [[Domain_(Rest_API)#Archiving SSO Login URL| Archiving SSO Login URL]]
|-
| [[Mailbox_(Rest_API)| Exchange Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
| All
|-
| [[Contact_(Rest_API)| Exchange Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
| All
|-
| [[Distribution_List_(Rest_API)| Exchange Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
| All
|-
| [[Resource_Mailbox_(Rest_API)| Exchange Resource Mailbox]]
| /customers/123456789/domains/example.com/ex/resources/conference.room
| All
|}

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

== Accessing the API ==

Your application will need to make HTTP requests to remote servers. Most programming languages have this function provided in its class library. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.


Calls without [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS] (formerly SSL) will complete successfully but it is HIGHLY RECOMMENDED that TLS always be used. Interception of unencrypted communication will allow a third party to have complete access to all functions available via the API.

For some language libraries just using an URL 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/v0/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

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

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/v0/. 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.

{| 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 that are generated from the Control Panel Web interface.

{| 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'''>:<'''Signature'''> 
Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

 
'''Signature''':

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 URLs, corresponding HTTP Methods, and necessary form data for the desired operations are detailed in the [[#Operations|operation pages]].

==== 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 consistent and is outlined in the table 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''
|-
| Accept
| The requested content type (required regardless of type of operation). 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=''
|}

==== 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
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

'''Reference Number'''

For the customer object only, the query string "referenceNumber=xx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The current limit is 1500 requests over 5 minutes. 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.

==== Examples ====

Example requests:
<pre>
Index of Exchange Mailboxes:

Hypertext Transfer Protocol
GET /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Request Method: GET
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml

Adding New Exchange Mailbox:

Hypertext Transfer Protocol
POST /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Request Method: POST
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
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 ===

On a successfully executed request, a 200 HTTP Code is returned. Requested data is also returned if the operation was a Show or Index action. If the request is unsuccessful, then an error HTTP Code is returned with a message detailing the error. The errors and their corresponding codes are detailed on the operation pages.

==== 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 extract data from 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 library with the functions necessary for whichever method you choose to use to extract data.

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.

==== Errors ====

If a request is not sucessfully completed an HTTP error code in the 400s or 500s will be returned. An error code of 500 generally indicates an error with our servers whereas an error code in the 400s is generally an error with the data sent to the server. In such cases the HTTP response will return a header named 'x-error-message'. Below are some errors that are common to many operations. Each operation also has some specific errors which are outlined with the operation.

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
|Format is invalid
|400
|When requesting an index or show on a resource the 'Accept' header should be either 'text/xml' or 'application/json'
|-
|Customer account number is invalid
|404
|Invalid account number
|-
|Domain is not found
|404
|<domain name> not found
|-
|Mailbox is not found
|404
|Mailbox not found
|-
|Required form field is missing
|400
|Missing required field: <required field>
|-
|Required form field has null or empty string input
|400
|Required field <required field> cannot be empty
|-
|Integer form field has non-integer input
|400
|Invalid format for <field>, input must be an integer
|-
|Boolean form field has non-boolean input
|400
|Invalid format for <field>, input must be True or False
|-
|Form data has an unrecognized field
|400
|Unrecognized field: <field>
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== 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.
|}

== 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>
module NetMethods
def get(url_string, format)
url = URI.parse('https://' + server_host + server_port + version + url_string)
@response = Net::HTTP::start(url.host, url.port) do |http|
sign_request
assign_format(format)
@request = Net::HTTP::Get.new(url.path, @headers)

http.request(@request)
end
end

def post(url_string, format, fields_hash)
url = URI.parse('https://' + server_host + server_port + version + url_string)

sign_request
assign_format(format)
@request = Net::HTTP::Post.new(url.path, @headers)

@request.set_form_data(fields_hash)
@response = Net::HTTP::start(url.host, url.port) do |http|
http.request(@request)
end
end

def assign_format (format)
@headers['Accept'] = format
end

def sign_request
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S')
apiKey = 'XXXXXXXXXXXXXXXXXXXX'
secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

data_to_sign = apiKey + userAgent + timestamp + secretKey

signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))

@headers = Hash.new
@headers['User-Agent'] = userAgent
@headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature
end

def server_host
'api.emailsrvr.com'
end

def server_port
':80'
end

def version
'/v0'
end
end
</pre>

=== C# ===

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

<pre>
using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = 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);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

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

Main Page

2010-03-22T18:59:56Z

Kevin.lin: Moved Cloud Sites note to bottom.

__NOTOC__

== The Rackspace Email API ==

The Rackspace Email [http://en.wikipedia.org/wiki/Api API] comprises a robust set of web services designed to allow businesses to fully integrate administrative email functions into their own applications. Based on [http://en.wikipedia.org/wiki/SOAP SOAP], functions in the API allow programs written in many different languages to perform operations such as [[AddUser()|adding mailboxes]] and changing settings. The API can also be used to provide [[LoginUserWebmail()|single sign on]] functionality in concert with other web applications. The Webmail API runs on the same robust server platform that supports our high-availability [http://www.rackspace.com/email_hosting webmail] and email services.

----------------
== API System Upgrades, March 2009 ==

On March 7th the [[webmail|Webmail User API]] will be updated to use the most recent and robust systems at Rackspace Email. No changes to code written by Rackspace Email customers should be needed to take advantage of the update. If desired, code may be updated to use the latest URI found in the [[webmail|Webmail User API]] documentation, though the old URI will be automatically redirected to the new URI by Rackspace Email on March 7th.

RISKS: After extensive testing Rackspace Email has concluded that there is a risk for customers using programming libraries that send the HTTP EXPECT header with their requests. This update moves the API to a much more robust and scalable system, but the system will return errors if this header is included in a request.

An excellent discussion around turning off EXPECT headers for .NET and PHP may be found in this [http://groups.google.com/group/twitter-development-talk/browse_thread/thread/7c67ff1a2407dee7?pli=1 thread] about Twitter.

----------------
=== Rackspace Email API ===
* [[webmail|Webmail User API]] - provides a short list of webmail user functions

* [[business|Business API]] - provides a list of functions designed for single business/domain usage

* [[reseller|Reseller API]] - provides a complete list of functions for multiple domains and sub-accounts

* [[beta|Beta API]] - a list of functions in public beta testing

=== Code Examples ===

{|
|
*[[Perl]]
|
*[[PHP]]
|-
|
*[[ASP]]
|
*[[C#]]
|-
|
*[[ColdFusion]]
|
*[[Ruby]]
|-
|
* [[HTML]] (not part of the API, strictly speaking)
|}

=== Getting Started Screencast ===
[http://www.mailtrust.com/api-wiki/screencasts/api-pings.htm Screencast] of accessing two of our SOAP API's from PHP using Ubuntu linux.

=== Result Codes ===
Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

This is a Rackspace Cloud Sites-hosted wiki.

Exchange Distribution List (Rest API)

2009-11-30T20:06:25Z

Kevin.lin: Updated to latest live version.

Exchange Contact (Rest API)

2009-11-30T20:05:21Z

Kevin.lin: Updated to latest live version.

MediaWiki:Sidebar

2009-11-30T20:03:58Z

Kevin.lin: Changed casing of 'REST'

Exchange Mailbox (Rest API)

2009-11-30T20:01:28Z

Kevin.lin: Update to latest live version.

__TOC__

== Index ==

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Remarks'':

The show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/MailboxList.xsd MailboxList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes', 'text/xml'
</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"}]}

== Show ==

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Mailbox.xsd Mailbox.xsd]

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', 'text/xml'
</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>
<isPublicFolderAdmin>true</isPublicFolderAdmin>
<enabled>true</enabled>
<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>
</contactInfo>
<emailForwardingAddress />
<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,"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"},"emailForwardingAddress":"","emailAddressList":[{"address":"apiexmailbox90@apidomain92.com","replyTo":true}],"hasBlackBerryMobileService":false,"hasActiveSyncMobileService":false,"samAccountName":"apiexmailbox90_53B5B"}

== Add/Edit ==

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)
Edit: [PUT] https://api.emailsrvr.com/v0/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.

{| 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
|-
| 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.)
|-
| enabled
| string
| Enable/Disable mailbox, input must be "true" or "false"
|}

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

<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith', 'text/xml',
{
'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/v0/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', 'text/xml'
</pre>

== Add Email Address ==

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/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', 'text/xml'
</pre>

== Delete Email Address ==

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/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', 'text/xml'
</pre>

== Spam ==

=== Index Blacklist ===

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

''Description'':

This operation returns email address blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Blacklist.xsd Blacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blacklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blacklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

=== Index IP Blacklist ===

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

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpBlacklist.xsd IpBlacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist', 'text/xml'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

=== Index Safelist ===

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

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Safelist.xsd Safelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

=== Index IP Safelist ===

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

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpSafelist.xsd IpSafelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

=== Add Blacklist ===

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

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@spam.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

=== Add IP Blacklist ===

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

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/216.12.34.1', 'text/xml'
</pre>

=== Add Safelist ===

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

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

=== Add IP Safelist ===

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

''Description'':

Adds an IP to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Delete Blacklist ===

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

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the blacklist
|}

=== Delete IP Blacklist ===

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

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

=== Delete Safelist ===

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

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

=== Delete IP Safelist ===

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

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

=== Show Spam Setting ===

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

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/MailboxSpamSetting.xsd MailboxSpamSetting.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<MailboxSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:MailboxSpamSettings">
<filterLevel>on</filterLevel>
<sendToDomainQuarantine>false</sendToDomainQuarantine>
<quarantineOwner />
</MailboxSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","sendToDomainQuarantine":false,"quarantineOwner":""}

=== Edit Spam Setting ===

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

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

== BlackBerry Mobile Service ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/BlackberryMobileServiceList.xsd BlackberryMobileServiceList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/blackberrymobileservices', 'text/xml'
</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/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/blackberrymobileservice</nowiki>

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

{| 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', 'text/xml',
{
'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/v0/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', 'text/xml'
</pre>

== ActiveSync Mobile Service ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ActiveSyncMobileServiceList.xsd ActiveSyncMobileServiceList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/activesyncmobileservices', 'text/xml'
</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/v0/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. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ActiveSyncMobileService.xsd ActiveSyncMobileService.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', 'text/xml'
</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/v0/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', 'text/xml', {}
</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/v0/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', 'text/xml'
</pre>

Domain (Rest API)

2009-11-30T18:20:04Z

Kevin.lin: Updated to latest live version.

__TOC__

== Index ==

''URL'':

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

''Description'':

This operation returns a list of domains under the account. If a customer account is specified, then a list of domains under that specific account will be returned.

''Remarks'':

To retrieve a list of domains owned by the account that is logged in, use "me" as the customer account number i.e. <nowiki>'https://api.emailsrvr.com/v0/customers/me/domains'</nowiki>. To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number.

The index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/DomainList.xsd DomainList.xsd]

''Example'':

<pre>
get '/customers/all/domains?size=100&page=1', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?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>3</total>
<domains>
<domain>
<name>apidomain53.com</name>
<accountNumber>100000</accountNumber>
<serviceType>both</serviceType>
</domain>
<domain>
<name>apidomain66.com</name>
<accountNumber>100001</accountNumber>
<serviceType>both</serviceType>
</domain>
<domain>
<name>apidomain68.com</name>
<accountNumber>100002</accountNumber>
<serviceType>both</serviceType>
</domain>
</domains>
</domainList>
</pre>

''Json Result Example'':

<pre>
{"offset":0,"size":50,"total":3,"domains":
[{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both"},
{"name":"apidomain66.com","accountNumber":"100001","serviceType":"both"},
{"name":"apidomain68.com","accountNumber":"100002","serviceType":"both"}]}
</pre>

== Show ==

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)</nowiki>

''Description'':

The show operation will return detailed information about the specified domain name.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Domain.xsd Domain.xsd]

''Example'':

<pre>
get '/customers/999999/domains/example.com', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<domain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domain">
<name>apidomain21.com</name>
<accountNumber>100000</accountNumber>
<serviceType>both</serviceType>
<exchangeBaseMailboxSize>2048</exchangeBaseMailboxSize>
<exchangeUsedStorage>0</exchangeUsedStorage>
<exchangeTotalStorage>18432</exchangeTotalStorage>
<exchangeExtraStorage>10240</exchangeExtraStorage>
<exchangeMaxNumMailboxes>4</exchangeMaxNumMailboxes>
<rsEmailBaseMailboxSize>2048</rsEmailBaseMailboxSize>
<rsEmailMaxNumberMailboxes>4</rsEmailMaxNumberMailboxes>
<rsEmailExtraStorage>10240</rsEmailExtraStorage>
<rsEmailUsedStorage>0</rsEmailUsedStorage>
<aliases />
<archivingServiceEnabled>false</archivingServiceEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
<goodMobileServiceEnabled>true</goodMobileServiceEnabled>
<goodMobileLicenses>4</goodMobileLicenses>
</domain>
</pre>

''Json Result Example'':
<pre>
{"name":"apidomain21.com","accountNumber":"100000","serviceType":"both",
"exchangeBaseMailboxSize":2048,"exchangeUsedStorage":0,"exchangeTotalStorage":18432,
"exchangeExtraStorage":10240,"exchangeMaxNumMailboxes":4,"rsEmailBaseMailboxSize":2048,
"rsEmailMaxNumberMailboxes":4,"rsEmailExtraStorage":10240,"rsEmailUsedStorage":0,
"aliases":[],"archivingServiceEnabled":false,"blackBerryMobileServiceEnabled":true,
"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,"activeSyncLicenses":4,
"goodMobileServiceEnabled":true,"goodMobileLicenses":4}
</pre>

== Add/Edit ==

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

''Description'':

Adds/edits a new domain to the account with the data specified. To add a domain to your own account, use your own account id.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| serviceType
| string
| Domain service type. "rsemail" = "Rackspace Email Only". "exchange" = "Exchange Only". "both" = "Rackspace Email and Exchange"
|-
| exchangeExtraStorage
| int
| Exchange service extra storage in megabytes
|-
| exchangeMaxNumMailboxes
| int
| Maximum number of mailboxes allowed under the domain Exchange service. Required for Adding Exchange service
|-
| rsEmailBaseMailboxSize
| int
| Rackspace Email base mailbox size in megabytes
|-
| rsEmailMaxNumberMailboxes
| int
| Maximum number of mailboxes allowed under the domain Rackspace Email service. Required for Adding Rackspace Email service
|-
| rsEmailExtraStorage
| int
| Rackspace Email service extra storage in megabytes
|-
| blackBerryMobileServiceEnabled
| boolean
| Enable or disable domain BlackBerry Mobile service
|-
| blackBerryLicenses
| int
| Maximum number of mailboxes allowed to have BlackBerry Mobile service. 0 means unlimited
|-
| activeSyncMobileServiceEnabled
| boolean
| Enable or disable domain ActiveSync Mobile service
|-
| activeSyncLicenses
| int
| Maximum number of mailboxes allowed to have ActiveSync Mobile service. 0 means unlimited
|-
| goodMobileServiceEnabled
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses
| int
| Maximum number of mailboxes allowed to have Good Mobile service. 0 means unlimited
|-
| archivingServiceEnabled
| boolean
| Enable or disable domain archiving service
|-
|}

''Example'':

<pre>
post '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '5',
'extraStorage' => '1024'
}
</pre>

<pre>
put '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '25',
'extraStorage' => '2048'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| New domain name doesn't meet the naming requirements
| 400
| Invalid domain name
|-
| New domain name already exists
| 400
| abc.com already exists as a domain or alternate domain
|}

== Move ==

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v0/customers/
(new customer account number)/domains/(domain name)</nowiki>

''Description'':

Moves the domain to another customer account.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| moveDomain
| boolean
| Indicate whether or not moving the domain
|}

''Remarks'':

Note 'Move Domain' and 'Edit Domain' share the same URI and HTTP verb. When the domain doesn't belong to the customer and 'moveDomain' is set to 'true', API will take the request as a 'Move Domain' call.

''Example'':

<pre>
put '/customers/123456/domains/newcompany.com', 'text/xml',
{
'moveDomain' => 'true'
}
</pre>

== Delete ==

''URL'':

<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)</nowiki>

''Description'':

Deletes the domain.

''Remarks'':

The domain and all the mailboxes, mailbox contents, groups, and contacts are deleted permanently.

''Example'':

<pre>
delete '/customers/12345678/domains/newcompany.com', 'text/xml'
</pre>

== Spam ==

=== Index Blacklist ===

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

''Description'':

This operation returns the email address blacklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Blacklist.xsd Blacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/blacklist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blacklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blacklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

=== Index IP Blacklist ===

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

''Description'':

This operation returns IP blacklist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpBlacklist.xsd IpBlacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipblacklist', 'text/xml'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

=== Index Safelist ===

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

''Description'':

This operation returns email address safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Safelist.xsd Safelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/safelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

=== Index IP Safelist ===

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

''Description'':

This operation returns IP safelist associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpSafelist.xsd IpSafelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipsafelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

=== Add Blacklist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/blacklist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blacklist/anyone@spam.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

=== Add IP Blacklist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/blacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Add Safelist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

=== Add IP Safelist ===

''URL'':
<nowiki>[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/spam/safelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Delete Blacklist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/blacklist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the list
|}

=== Delete IP Blacklist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipblacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

=== Delete Safelist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/safelist/(email address)</nowiki>

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the list
|}

=== Delete IP Safelist ===

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/spam/ipsafelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the list
|}

=== Show Spam Setting ===

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

''Description'':

This operation returns the spam settings associated with the domain.

''Remarks'':

The Show operation only supports the GET HTTP verb. For .xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/DomainSpamSetting.xsd DomainSpamSetting.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/settings', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<domainSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:DomainSpamSettings">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toAddress</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress>someone@mail.com</spamForwardingAddress>
</rsEmailSettings>
<exchangeSettings>
<forwardToDomainQuarantine>on</forwardToDomainQuarantine>
<quarantineOwner>someone@mail.com</quarantineOwner>
<defaultQuarantineOwner>someone@mail.com</defaultQuarantineOwner>
</exchangeSettings>
</domainSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","rsEmailSettings":{"spamHandling":"toAddress","hasFolderCleaner":false,"spamFolderAgeLimit":0,"spamFolderNumLimit":0,"spamForwardingAddress":"someone@mail.com"},"exchangeSettings":{"forwardToDomainQuarantine":"on","quarantineOwner":"someone@mail.com","defaultQuarantineOwner":"someone@mail.com"}}

=== Edit Spam Setting ===

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/spam/settings</nowiki>

''Description'':

Edits the domain Spam Settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| overrideUserSettings
| boolean
| Set this flag to "true" to override preferences for all users regardless of their own preferences. Otherwise, it sets preferences only for users who have not set their own.
|-
| rsEmail.spamHandling
| string
| Change settings for Rackspace Email Handling. For the options, see the table below.
|-
| rsEmail.hasFolderCleaner
| boolean
| Turns on/off Spam Folder Cleaner. Requires "rsEmail.spamHandling" to be set to "toFolder".
|-
| rsEmail.spamFolderAgeLimit
| int
| The number of days that email stays the "Spam" folder before being deleted. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamFolderNumLimit
| int
| The max number of emails that will be kept in the "Spam" folder. Requires "rsEmail.hasFolderCleaner" to be set to "true".
|-
| rsEmail.spamForwardingAddress
| string
| The address that spams will be forwarded to. Requires "rsEmail.spamHandling" to be set to "toAddress".
|-
| exchange.forwardToDomainQuarantine
| string
| Change settings for Exchange Handling. For the options, see the table below.
|-
| exchange.quarantineOwner
| string
| The address that domain quarantine notifications will be sent to.
|-
| exchange.removeQuarantineOwner
| boolean
| Set this flag to "true" to remove domain quarantine owner.
|-
| exchange.defaultQuarantineOwner
| string
| The address that quarantine notifications will be sent to. This applies to new users and users that have not changed their settings to override.
|-
| exchange.removeDefaultQuarantineOwner
| boolean
| Set this flag to "true" to remove default domain quarantine owner.
|}

Rackspace Email Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| toFolder
| Deliver to Spam folder
|-
| delete
| Delete the email immediately
|-
| labelSubject
| Include "[SPAM]" at the beginning of the subject line
|-
| toAddress
| Deliver to the email address that is specified by "rsEmail.spamForwardingAddress"
|}

Exchange Handling Options:
{| class="wikitable"
!''Value''
!''Description''
|-
| on
| Send all spam to domain quarantine
|-
| off
| Send spam to recipient's quarantine
|-
| nonuser
| Send non-user spam (Contacts, Resources, etc.) to domain quarantine
|}

''Example'':

<pre>
put '/customers/me/domains/' + @@domain + '/spam/settings', 'text/xml',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid input for Filter Level
| 400
| Invalid FilterLevel: high. Input must be: on/off/exclusive
|-
| Invalid input for RSEmail SpamHandling
| 400
| Invalid RSEmail SpamHandling: nonuser. Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid input for Exchange ForwardToDomainQuarantine
| 400
| Invalid input for Exchange ForwardToDomainQuarantine: delete. Input must be: on/off/nonuser
|}

== Alternate Domains ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/
domains/(domain name)/alternatedomains</nowiki>

''Description'':

This operation returns a list of Domain Aliases and Accepted Domains for the domain. The type of the alternate domain is indicated by the 'type' data field. The XML schema for the returned data is [http://api.emailsrvr.com/v0/Schemas/DomainSplitRouting.xsd DomainAlternateList.xsd]

''Example'':

<pre>
get '/customers/12345678/domains/test.com/alternatedomains', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<alternateDomainList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainAlternateList">
<alternateDomains>
<alternateDomain>
<name>domainalias.com</name>
<type>DomainAlias</type>
</alternateDomain>
<alternateDomain>
<name>accepteddomain.com</name>
<type>AcceptedDomain</type>
</alternateDomain>
</alternateDomains>
</alternateDomainList>
</pre>

''Json Result Example'':

<pre>{"alternateDomains":[{"name":"domainalias.com","type":"DomainAlias"},{"name":"accepteddomain.com","type":"AcceptedDomain"}]}</pre>

=== Add ===

''URL'':
<nowiki>
[POST] https://api.emailsrvr.com/v0/customers/(customer account number)
/domains/(domain name)/alternatedomains/(alternate domain name)
</nowiki>

''Description'':

Adds either a Domain Alias or Accepted Domain to the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| type
| string
| Alternate domain type. Send "DomainAlias" for a domain alias, and "AcceptedDomain" for an accepted domain. (Required)
|-
| createForExistingRecipients
| boolean
| Whether the alternate addresses should be created for existing mailboxes when adding an Accepted Domain. Sending this field in the request when the type is Domain Alias will throw an error. This defaults to false.
|-
|}

''Example'':

<pre>
post '/customers/123456/domains/example.com/alternatedomains/accepteddomain.com', 'text/xml',
{
'type' => 'AcceptedDomain'
'createForExistingRecipients' => 'true'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| New domain name doesn't meet the naming requirements
| 400
| Invalid domain name
|-
| Alternate domain already exists
| 400
| abc.com already exists as a domain or alternate domain
|-
| The 'createForExistingRecipients' field was sent with either data, or as a null field. It should not be included in the form data at all.
| 400
| Invalid Alternate Domain Setting: createForExistingRecipients is an invalid setting for Domain Aliases
|-
| The only valid values for 'type' are 'DomainAlias' and 'AcceptedDomain', for a Domain Alias and Accepted Domain respectively.
| 400
| Invalid Alternate Domain type
|}

=== Delete ===

''URL'':

<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/
domains/(domain name)/alternatedomains/(alternate domain name)</nowiki>

''Description'':

Deletes the alternate domain.

''Example'':

<pre>
delete '/customers/12345678/domains/example.com/alternatedomains/accepteddomain.com'
</pre>

== Split Domain Routing ==

=== Show Settings ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain)/splitdomainrouting</nowiki>

''Description'':
Shows the current external email server. The XML schema document for the output of this command is [http://api.emailsrvr.com/v0/Schemas/DomainSplitRouting.xsd DomainSplitRouting.xsd]

''Example'':

<pre>
get '/customers/12345678/domains/company.com/splitdomainrouting', 'text/xml'
</pre>

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<splitDomainRouting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:splitDomainRouting">
<externalServer>email.externalserver.com</externalServer>
</splitDomainRouting>
</pre>

''JSON Result Example'':
<pre>
{"externalServer":"email.externalserver.com"}
</pre>

=== Edit Settings ===

''URL'':

<nowiki>[PUT] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain)/splitdomainrouting</nowiki>

''Description'':

This command sets the external email server. This command will return a success when the verification passes. Since this involves communication to the external server the request may take some time. If the verification fails a 400 return code will be sent back with the verification's error message.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| externalServer
| string
| The address of the external email server. To turn off split domain routing send 'none'. (Required)
|-
| verificationAddress
| string
| An email address part of your domain or one of the alternate domains that the external server is already set up to handle. (Required only when turning on split domain routing, Do not send this field if turning off.)
|-
|}

''Example'':

<pre>
put '/customers/12345678/domains/company.com/splitdomainrouting', 'text/xml',
{
'externalServer' => 'email.externalserver.com',
'verificationAddress' => 'externalaccount@company.com',
}
</pre>

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The SMTP host could not be found.
| 400
| One of the verification error messages.
|}

== Archiving SSO Login URL ==

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain)/archivingSSOLoginURL</nowiki>

''Description'':

Gets the domain archiving service SSO login URL.

''Remarks'':

The retrieved URL can be used in browser to access the domain archiving control panel.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/archivingSSOLoginURL', 'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| No archiving service
| 404
| Domain abc.com has no archiving service enabled
|}

Customer (Rest API)

2009-11-30T18:18:13Z

Kevin.lin: Updated to reflect latest version.

__TOC__

== Index ==

''URL'':

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

''Description'':

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

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/CustomerList.xsd CustomerList.xsd]

''Example'':

<pre>
get '/customers?size=100&page=1', 'text/xml'
</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 ==

''URL'':

[GET] <nowiki>https://api.emailsrvr.com/v0/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/v0/customers/me'</nowiki>.

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Customer.xsd Customer.xsd]

''Example'':

<pre>
get '/customers/me', 'text/xml'
</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>
</customer>
</pre>

''JSON Result Example'':

<pre>
{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"}
</pre>

== Add/Edit ==

''URL'':

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

''Description'':

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

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

''Example'':

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

<pre>
put '/customers/999999', 'text/xml',
{
'name' => 'NewName',
'referenceNumber' => '12345'
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The name field was not specified
| 400
| Missing required field: name
|-
| The name field cannot be blank
| 400
| Required field name cannot be empty
|-
| Names cannot start with a space
| 400
| Improper Customer Name
|}

== Delete ==

''URL'':

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

''Description'':

Deletes the account.

''Example'':

<pre>
delete '/customers/999999', 'text/xml'
</pre>

Rest API

2009-11-30T18:16:45Z

Kevin.lin: Updated to reflect latest live version.

== Recent Changes ==

'''11/22/09 '''
{|
|
New features:
*Index/Add/Delete Alternate Domains.
*Show/Edit Domain Spam Settings.
*Index/Add/Delete Domain Blacklist/Safelist.
*Show/Edit Split Domain Routing.
*Show Mailbox ActiveSync Setup Info.
|
|}

== Introduction ==

The Email & Apps Control Panel API provides most of the functions of the Control Panel through a HTTP-based REST API ([http://en.wikipedia.org/wiki/Application_programming_interface Application Programming Interface]). 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://en.wikipedia.org/wiki/Representational_State_Transfer

http://java.sun.com/developer/technicalArticles/WebServices/restful/

The API is accessible to resellers only. As of now, most of the supported functions manage only customers, domains, and Exchange accounts.

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

{| class="wikitable"
!Resource
!Example URI
|-
| [[Customer_(Rest_API)| Customer]]
| /customers/123456789
|-
| [[Domain_(Rest_API)| Domain]]
| /customers/123456789/domains/example.com
|-
| [[Mailbox_(Rest_API)| Exchange Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
|-
| [[Contact_(Rest_API)| Exchange Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
|-
| [[Distribution_List_(Rest_API)| Exchange Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
|}

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

To get a list of mailboxes under a domain:

First, you need to populate some HTTP headers with the correct information. 'Accept' needs to be either 'text/xml' or 'application/json' to indicate the format of the returned data. 'User-Agent' just needs to be any name you choose to identify your client with. 'X-Api-Signature' needs a

== Accessing the API ==

Your application will need to make HTTP requests to remote servers. Most programming languages have this function provided in its class library. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE.


Calls without [http://en.wikipedia.org/wiki/Transport_Layer_Security TLS] (formerly SSL) will complete successfully but it is HIGHLY RECOMMENDED that TLS always be used. Interception of unencrypted communication will allow a third party to have complete access to all functions available via the API.

For some language libraries just using an URL 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/v0/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

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

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/v0/. 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.

{| 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 that are generated from the Control Panel Web interface.

{| 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'''>:<'''Signature'''> 
Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''

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 YYYYMMDDHHmmssff. 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
|-
| ff
| Millisecond
|}

 
'''Signature''':

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 URLs, corresponding HTTP Methods, and necessary form data for the desired operations are detailed in the [[#Operations|operation pages]].

==== 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 consistent and is outlined in the table 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''
|-
| Accept
| The requested content type (required regardless of type of operation). 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=''
|}

==== 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
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

'''Reference Number'''

For the customer object only, the query string "referenceNumber=xx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The current limit is 1500 requests over 5 minutes. 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.

==== Examples ====

Example requests:
<pre>
Index of Exchange Mailboxes:

Hypertext Transfer Protocol
GET /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Request Method: GET
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml

Adding New Exchange Mailbox:

Hypertext Transfer Protocol
POST /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Request Method: POST
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
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 ===

On a successfully executed request, a 200 HTTP Code is returned. Requested data is also returned if the operation was a Show or Index action. If the request is unsuccessful, then an error HTTP Code is returned with a message detailing the error. The errors and their corresponding codes are detailed on the operation pages.

==== 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 extract data from 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 library with the functions necessary for whichever method you choose to use to extract data.

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.

==== Errors ====

If a request is not sucessfully completed an HTTP error code in the 400s or 500s will be returned. An error code of 500 generally indicates an error with our servers whereas an error code in the 400s is generally an error with the data sent to the server. In such cases the HTTP response will return a header named 'x-error-message'. Below are some errors that are common to many operations. Each operation also has some specific errors which are outlined with the operation.

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
|Format is invalid
|400
|When requesting an index or show on a resource the 'Accept' header should be either 'text/xml' or 'application/json'
|-
|Customer account number is invalid
|404
|Invalid account number
|-
|Domain is not found
|404
|<domain name> not found
|-
|Mailbox is not found
|404
|Mailbox not found
|-
|Required form field is missing
|400
|Missing required field: <required field>
|-
|Required form field has null or empty string input
|400
|Required field <required field> cannot be empty
|-
|Integer form field has non-integer input
|400
|Invalid format for <field>, input must be an integer
|-
|Boolean form field has non-boolean input
|400
|Invalid format for <field>, input must be True or False
|-
|Form data has an unrecognized field
|400
|Unrecognized field: <field>
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== 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.
|}

== 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>
module NetMethods
def get(url_string, format)
url = URI.parse('https://' + server_host + server_port + version + url_string)
@response = Net::HTTP::start(url.host, url.port) do |http|
sign_request
assign_format(format)
@request = Net::HTTP::Get.new(url.path, @headers)

http.request(@request)
end
end

def post(url_string, format, fields_hash)
url = URI.parse('https://' + server_host + server_port + version + url_string)

sign_request
assign_format(format)
@request = Net::HTTP::Post.new(url.path, @headers)

@request.set_form_data(fields_hash)
@response = Net::HTTP::start(url.host, url.port) do |http|
http.request(@request)
end
end

def assign_format (format)
@headers['Accept'] = format
end

def sign_request
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S00')
apiKey = 'XXXXXXXXXXXXXXXXXXXX'
secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

data_to_sign = apiKey + userAgent + timestamp + secretKey

signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))

@headers = Hash.new
@headers['User-Agent'] = userAgent
@headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature
end

def server_host
'api.emailsrvr.com'
end

def server_port
'80'
end

def version
'/v0'
end
end
</pre>

=== C# ===

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

<pre>
using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = userAgent;

var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmssff");

var dataToSign = apiKey + userAgent + dateTime + secretKey;
var hash = SHA1.Create();
var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
var signature = Convert.ToBase64String(signedBytes);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

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

MediaWiki:Sidebar

2009-11-30T18:12:35Z

Kevin.lin: Changed 'Beta API' to 'Rest API'

Companies

2009-11-30T16:28:43Z

Kevin.lin: Updating company name.

Resellers of Rackspace Email hosting services can add sub-accounts to their main reseller account. Each sub-account usually represents a company that purchases email hosting from the reseller. Sub-accounts may only be one level deep with respect to the reseller (no sub-accounts of sub-accounts).

== Function List ==
[[GetSubaccounts()]] 
[[SearchSubaccounts()]] 
[[SearchDomains()]] 
[[AddSubaccount()]] 
[[DeleteSubaccount()]] 
[[ModifySubaccount()]] 
[[Subaccount_GetDomains()]] 
[[Subaccount_GetAdmins()]] 
[[Subaccount_GetAdminType()]] 
[[Subaccount_AddAdmin()]] 
[[Subaccount_ChangeAdminPassword()]] 
[[Subaccount_ChangeAdminType()]] 
[[Subaccount_DeleteAdmin()]] 
[[Subaccount_AddDomain()]] 
[[Subaccount_MoveDomain()]] 
[[GetAllDomainsUserCount()]] 
[[GetAllDomainsMXRecords()]]

ModifyDomainMaxNumUsers()

2009-11-20T21:17:08Z

Kevin.lin: Removing webmail.us reference.

This function will change the maximum number of mailboxes that can be created for a domain. Please note that mailbox and domain aliases do not count towards the total number of mailboxes. A limit of 0 is the same as saying that there are no limits to the number of mailboxes that may be created for the domain. Please use the "0" cautiously and be certain that your contract with us permits this to prevent billing problems.

===Parameters===

Three strings, one integer:
Administrative username,
Administrative password,
Domain name,
Maximum mailbox count (integer, must be 0 or greater, 0 = no limit)
===Return Values===
If successful, the return value of the function will be 1.

Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

ASP

2009-11-20T21:14:43Z

Kevin.lin: Removing webmail.us reference.

A customer recommended the following article as being helpful for System.Net.WebException errors: http://geekswithblogs.net/Denis/archive/2005/08/16/50365.aspx 
 

<% 
Option Explicit 
 
Dim soapClient 
set soapclient = CreateObject("MSSOAP.SoapClient") 
 
soapclient.ClientProperty("ServerHTTPRequest") = True 
soapclient.mssoapinit "<nowiki>https://admin.webmail.us/excedentsoap/excedentsoap.wsdl</nowiki>", "excedentsoap", "UtilsSoapPort" 
 
'*********************Initializing************************* 
Dim retval 
 
'this is the username and password you use to log in to our admin.webmail.us site 
Dim AdminUsername, AdminPassword 
 
AdminUsername = "adminUser" 
AdminPassword = "adminPassword" 
 
Dim emailAddr 
Dim HostName 'the hostname of the email domain 
Dim UserID 'userid (id before the @ symbol in the email address) 
Dim sesID 
 
HostName = "webmail.us" 
UserID = "someguy" 
 
'*************function call checkuserexists**************** 
retval = soapclient.LoginUserWebMail(AdminUsername, AdminPassword, HostName, UserID, sesID) 
 
Response.Write retval 
Response.Write " " & sesID 
Response.Redirect "<nowiki>http://reseller1.webmail.us/mail/src/redirect.php?</nowiki> 
  user_name=someguy@webmail.us&emailaddress=someguy@webmail.us&sessionID="&SesID 
 
Set soapclient = nothing 
 
%>

AddMailAllotStorage()

2009-11-20T21:14:15Z

Kevin.lin: Removing webmail.us reference.

This function will add or remove allocatable/extra storage for a domain. Passing a negative value to reduce the allocatable storage. After calling this function, extra storage may be assigned to a user with [[SetUserMailboxMaxSize()]]. Check current extra storage levels with [[GetMailAllotStorage()]]. Please make sure that your contract with us permits you to change these values to ensure that billing will be handled properly.

===Input Parameters===
Three strings and one result array:
Administrative username,
Administrative password,
Domain name,
Storage change (integer, MB; use negative values to reduce storage, positive to add to existing extra storage)
===Return Values===
If successful, the return value of the function will be 1.

Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

Subaccount AddDomain()

2009-11-20T21:13:28Z

Kevin.lin:

This function will add a domain to a subaccount and configure the system to accept email for that domain. Please note that this is wholly separate from the DNS process of configuring the DNS and especially MX records for a domain.

===Parameters===

Five strings, 3 integers
Administrative username (string),
Administrative password (string),
Subaccount number (string),
New domain name (string),
Aliases for the new domain (string, format "alias1.com, alias2.com, ...),
Maximum mailbox size in MB (int, must be > 0),
Maximum number of mailboxes (int, 0 means no limit and should be used cautiously),
Placeholder (int, please set to 1)
===Return Values===
If successful, the return value of the function will be 1.

Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

Domains

2009-11-20T21:12:24Z

Kevin.lin:

These functions are designed for resellers, but other customers may find these functions useful, as well.

== Categories ==
[[Domain_spam|Domain-level spam settings]] 
[[Domain_parameters|Domain-level general parameters]] 
[[Domain_administration| Domain-level administration]]

AddUserWithLdapAttributes()

2009-11-20T21:11:37Z

Kevin.lin:

This function will add a new mailbox and set it's mailbox LDAP attributes. Please note that a number of attributes cannot be edited from the control panel without contacting support and requesting "LDAP access" so that you can configure which attributes are optional or required when adding a new user via the control panel and to have required and optional attributes displayed. Here is the list of LDAP attributes and their meaning:
<pre>
'sn' - As in surname, or last name
'displayName' - Person's full name
'givenName' - First name

'intials' - Middle name or initial(s)
'personalTitle' - As in "Mrs."
'o' - Organization/company

'ou' - Organizational unit/department
'title' - Title as in job title
'businessCategory' - Flexible: region/type/other

'telephoneNumber' - Telephone number
'mobile' - Mobile telephone number
'pager' - Pager telephone number

'facsimileTelephoneNumber' - Fax phone number
'street' - Street address
'l' - That's a lower-case "L", for city

'st' - State
'postalCode' - Zip code in the U.S.
'c' - Country

'mail' - Email address/reply-to address
'homePhone' - Home phone number
'homeStreet' - Home street address

'homeCity' - Home city
'homeState' - Home state
'homeCountry' - Home country

'homePostalCode' - Home postal/zip code
</pre>
===Input Parameters===
Five strings, one integer, and one array of strings:
Administrative username,
Administrative password,
Domain name,
UserID (the part before @),
Surname (last name of user-- required),
Password,
Active (int; 1=active, 0=inactive),
Attributes array ("givenname John", "o MyCompany", ...) (tab delimited)
===Return Values===
If successful, the return value of the function will be 1.

Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

GetTimeZoneVals()

2009-11-20T21:10:31Z

Kevin.lin:

This function will return the long list of the time zone values that are supported. Look at the bottom of this page for the current list as of 14 December 2005.

===Input Parameters===

Two strings and a result array:
Administrative username,
Administrative password,

Contact list array (as in: array[0]["firstname"]="Robert", array[1]["firstname"]="Janice")
===Return Values===
If successful, the return value of the function will be 1.

Consult the [[resultcodes|Result Code Table]] for a list of result codes and their meaning.

===Time Zone Values===
From 14 December 2005: 
<pre>
Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
Africa/Asmera
Africa/Bamako
Africa/Bangui
Africa/Banjul
Africa/Bissau
Africa/Blantyre
Africa/Brazzaville
Africa/Bujumbura
Africa/Cairo
Africa/Casablanca
Africa/Ceuta
Africa/Conakry
Africa/Dakar
Africa/Dar_es_Salaam
Africa/Djibouti
Africa/Douala
Africa/El_Aaiun
Africa/Freetown
Africa/Gaborone
Africa/Harare
Africa/Johannesburg
Africa/Kampala
Africa/Khartoum
Africa/Kigali
Africa/Kinshasa
Africa/Lagos
Africa/Libreville
Africa/Lome
Africa/Luanda
Africa/Lubumbashi
Africa/Lusaka
Africa/Malabo
Africa/Maputo
Africa/Maseru
Africa/Mbabane
Africa/Mogadishu
Africa/Monrovia
Africa/Nairobi
Africa/Ndjamena
Africa/Niamey
Africa/Nouakchott
Africa/Ouagadougou
Africa/Porto-Novo
Africa/Sao_Tome
Africa/Timbuktu
Africa/Tripoli
Africa/Tunis
Africa/Windhoek
America/Adak
America/Anchorage
America/Anguilla
America/Antigua
America/Araguaina
America/Aruba
America/Asuncion
America/Atka
America/Barbados
America/Belem
America/Belize
America/Boa_Vista
America/Bogota
America/Boise
America/Buenos_Aires
America/Cambridge_Bay
America/Cancun
America/Caracas
America/Catamarca
America/Cayenne
America/Cayman
America/Chicago
America/Chihuahua
America/Cordoba
America/Costa_Rica
America/Cuiaba
America/Curacao
America/Danmarkshavn
America/Dawson
America/Dawson_Creek
America/Denver
America/Detroit
America/Dominica
America/Edmonton
America/Eirunepe
America/El_Salvador
America/Ensenada
America/Fort_Wayne
America/Fortaleza
America/Glace_Bay
America/Godthab
America/Goose_Bay
America/Grand_Turk
America/Grenada
America/Guadeloupe
America/Guatemala
America/Guayaquil
America/Guyana
America/Halifax
America/Havana
America/Hermosillo
America/Indiana/Indianapolis
America/Indiana/Knox
America/Indiana/Marengo
America/Indiana/Vevay
America/Indianapolis
America/Inuvik
America/Iqaluit
America/Jamaica
America/Jujuy
America/Juneau
America/Kentucky/Louisville
America/Kentucky/Monticello
America/Knox_IN
America/La_Paz
America/Lima
America/Los_Angeles
America/Louisville
America/Maceio
America/Managua
America/Manaus
America/Martinique
America/Mazatlan
America/Mendoza
America/Menominee
America/Merida
America/Mexico_City
America/Miquelon
America/Monterrey
America/Montevideo
America/Montreal
America/Montserrat
America/Nassau
America/New_York
America/Nipigon
America/Nome
America/Noronha
America/North_Dakota/Center
America/Panama
America/Pangnirtung
America/Paramaribo
America/Phoenix
America/Port-au-Prince
America/Port_of_Spain
America/Porto_Acre
America/Porto_Velho
America/Puerto_Rico
America/Rainy_River
America/Rankin_Inlet
America/Recife
America/Regina
America/Rio_Branco
America/Rosario
America/Santiago
America/Santo_Domingo
America/Sao_Paulo
America/Scoresbysund
America/Shiprock
America/St_Johns
America/St_Kitts
America/St_Lucia
America/St_Thomas
America/St_Vincent
America/Swift_Current
America/Tegucigalpa
America/Thule
America/Thunder_Bay
America/Tijuana
America/Tortola
America/Vancouver
America/Virgin
America/Whitehorse
America/Winnipeg
America/Yakutat
America/Yellowknife
Antarctica/Casey
Antarctica/Davis
Antarctica/DumontDUrville
Antarctica/Mawson
Antarctica/McMurdo
Antarctica/Palmer
Antarctica/South_Pole
Antarctica/Syowa
Antarctica/Vostok
Arctic/Longyearbyen
Asia/Aden
Asia/Almaty
Asia/Amman
Asia/Anadyr
Asia/Aqtau
Asia/Aqtobe
Asia/Ashgabat
Asia/Ashkhabad
Asia/Baghdad
Asia/Bahrain
Asia/Baku
Asia/Bangkok
Asia/Beirut
Asia/Bishkek
Asia/Brunei
Asia/Calcutta
Asia/Choibalsan
Asia/Chongqing
Asia/Chungking
Asia/Colombo
Asia/Dacca
Asia/Damascus
Asia/Dhaka
Asia/Dili
Asia/Dubai
Asia/Dushanbe
Asia/Gaza
Asia/Harbin
Asia/Hong_Kong
Asia/Hovd
Asia/Irkutsk
Asia/Ishigaki
Asia/Istanbul
Asia/Jakarta
Asia/Jayapura
Asia/Jerusalem
Asia/Kabul
Asia/Kamchatka
Asia/Karachi
Asia/Kashgar
Asia/Katmandu
Asia/Krasnoyarsk
Asia/Kuala_Lumpur
Asia/Kuching
Asia/Kuwait
Asia/Macao
Asia/Macau
Asia/Magadan
Asia/Manila
Asia/Muscat
Asia/Nicosia
Asia/Novosibirsk
Asia/Omsk
Asia/Oral
Asia/Phnom_Penh
Asia/Pontianak
Asia/Pyongyang
Asia/Qatar
Asia/Qyzylorda
Asia/Rangoon
Asia/Riyadh
Asia/Riyadh87
Asia/Riyadh88
Asia/Riyadh89
Asia/Saigon
Asia/Sakhalin
Asia/Samarkand
Asia/Seoul
Asia/Shanghai
Asia/Singapore
Asia/Taipei
Asia/Tashkent
Asia/Tbilisi
Asia/Tehran
Asia/Tel_Aviv
Asia/Thimbu
Asia/Thimphu
Asia/Tokyo
Asia/Ujung_Pandang
Asia/Ulaanbaatar
Asia/Ulan_Bator
Asia/Urumqi
Asia/Vientiane
Asia/Vladivostok
Asia/Yakutsk
Asia/Yekaterinburg
Asia/Yerevan
Atlantic/Azores
Atlantic/Bermuda
Atlantic/Canary
Atlantic/Cape_Verde
Atlantic/Faeroe
Atlantic/Jan_Mayen
Atlantic/Madeira
Atlantic/Reykjavik
Atlantic/South_Georgia
Atlantic/St_Helena
Atlantic/Stanley
Australia/ACT
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Canberra
Australia/Darwin
Australia/Hobart
Australia/LHI
Australia/Lindeman
Australia/Lord_Howe
Australia/Melbourne
Australia/NSW
Australia/North
Australia/Perth
Australia/Queensland
Australia/South
Australia/Sydney
Australia/Tasmania
Australia/Victoria
Australia/West
Australia/Yancowinna
Brazil/Acre
Brazil/DeNoronha
Brazil/East
Brazil/West
CET
CST6CDT
Canada/Atlantic
Canada/Central
Canada/East-Saskatchewan
Canada/Eastern
Canada/Mountain
Canada/Newfoundland
Canada/Pacific
Canada/Saskatchewan
Canada/Yukon
Chile/Continental
Chile/EasterIsland
China/Beijing
China/Shanghai
Cuba
EET
EST
EST5EDT
Egypt
Eire
Etc/GMT
Etc/GMT+0
Etc/GMT+1
Etc/GMT+10
Etc/GMT+11
Etc/GMT+12
Etc/GMT+2
Etc/GMT+3
Etc/GMT+4
Etc/GMT+5
Etc/GMT+6
Etc/GMT+7
Etc/GMT+8
Etc/GMT+9
Etc/GMT-0
Etc/GMT-1
Etc/GMT-10
Etc/GMT-11
Etc/GMT-12
Etc/GMT-13
Etc/GMT-14
Etc/GMT-2
Etc/GMT-3
Etc/GMT-4
Etc/GMT-5
Etc/GMT-6
Etc/GMT-7
Etc/GMT-8
Etc/GMT-9
Etc/GMT0
Etc/Greenwich
Etc/UCT
Etc/UTC
Etc/Universal
Etc/Zulu
Europe/Amsterdam
Europe/Andorra
Europe/Athens
Europe/Belfast
Europe/Belgrade
Europe/Berlin
Europe/Bratislava
Europe/Brussels
Europe/Bucharest
Europe/Budapest
Europe/Chisinau
Europe/Copenhagen
Europe/Dublin
Europe/Gibraltar
Europe/Helsinki
Europe/Istanbul
Europe/Kaliningrad
Europe/Kiev
Europe/Lisbon
Europe/Ljubljana
Europe/London
Europe/Luxembourg
Europe/Madrid
Europe/Malta
Europe/Minsk
Europe/Monaco
Europe/Moscow
Europe/Nicosia
Europe/Oslo
Europe/Paris
Europe/Prague
Europe/Riga
Europe/Rome
Europe/Samara
Europe/San_Marino
Europe/Sarajevo
Europe/Simferopol
Europe/Skopje
Europe/Sofia
Europe/Stockholm
Europe/Tallinn
Europe/Tirane
Europe/Tiraspol
Europe/Uzhgorod
Europe/Vaduz
Europe/Vatican
Europe/Vienna
Europe/Vilnius
Europe/Warsaw
Europe/Zagreb
Europe/Zaporozhye
Europe/Zurich
Factory
GB
GB-Eire
GMT
GMT+0
GMT-0
GMT0
Greenwich
HST
Hongkong
Iceland
Indian/Antananarivo
Indian/Chagos
Indian/Christmas
Indian/Cocos
Indian/Comoro
Indian/Kerguelen
Indian/Mahe
Indian/Maldives
Indian/Mauritius
Indian/Mayotte
Indian/Reunion
Iran
Israel
Jamaica
Japan
Kwajalein
Libya
MET
MST
MST7MDT
Mexico/BajaNorte
Mexico/BajaSur
Mexico/General
Mideast/Riyadh87
Mideast/Riyadh88
Mideast/Riyadh89
NZ
NZ-CHAT
Navajo
PRC
PST8PDT
Pacific/Apia
Pacific/Auckland
Pacific/Chatham
Pacific/Easter
Pacific/Efate
Pacific/Enderbury
Pacific/Fakaofo
Pacific/Fiji
Pacific/Funafuti
Pacific/Galapagos
Pacific/Gambier
Pacific/Guadalcanal
Pacific/Guam
Pacific/Honolulu
Pacific/Johnston
Pacific/Kiritimati
Pacific/Kosrae
Pacific/Kwajalein
Pacific/Majuro
Pacific/Marquesas
Pacific/Midway
Pacific/Nauru
Pacific/Niue
Pacific/Norfolk
Pacific/Noumea
Pacific/Pago_Pago
Pacific/Palau
Pacific/Pitcairn
Pacific/Ponape
Pacific/Port_Moresby
Pacific/Rarotonga
Pacific/Saipan
Pacific/Samoa
Pacific/Tahiti
Pacific/Tarawa
Pacific/Tongatapu
Pacific/Truk
Pacific/Wake
Pacific/Wallis
Pacific/Yap
Poland
Portugal
ROC
ROK
Singapore
SystemV/AST4
SystemV/AST4ADT
SystemV/CST6
SystemV/CST6CDT
SystemV/EST5
SystemV/EST5EDT
SystemV/HST10
SystemV/MST7
SystemV/MST7MDT
SystemV/PST8
SystemV/PST8PDT
SystemV/YST9
SystemV/YST9YDT
Turkey
UCT
US/Alaska
US/Aleutian
US/Arizona
US/Central
US/East-Indiana
US/Eastern
US/Hawaii
US/Indiana-Starke
US/Michigan
US/Mountain
US/Pacific
US/Samoa
UTC
Universal
W-SU
WET
Zulu
</pre>

Exchange Mailbox (Rest API)

2009-11-20T20:33:41Z

Kevin.lin: moved RestAPI/Mailbox to Mailbox (Rest API)

__TOC__

== Index ==

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Remarks'':

The show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/MailboxList.xsd MailboxList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes', 'text/xml'
</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"}]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

== Show ==

''URL'':
<nowiki>[GET] http://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Mailbox.xsd Mailbox.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith', 'text/xml'
</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>
<isPublicFolderAdmin>true</isPublicFolderAdmin>
<enabled>true</enabled>
<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>
</contactInfo>
<emailForwardingAddress />
<emailAddressList>
<emailAddress>
<address>apiexmailbox90@apidomain92.com</address>
<replyTo>true</replyTo>
</emailAddress>
</emailAddressList>
<hasBlackBerryMobileService>false</hasBlackBerryMobileService>
<hasActiveSyncMobileService>false</hasActiveSyncMobileService>
</mailbox>
</pre>

''Json Result Example'':

{"name":"apiexmailbox90","displayName":"API Test","size":2048,"currentUsage":0,"isHidden":false,"isPublicFolderAdmin":true,"enabled":true,"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"},"emailForwardingAddress":"","emailAddressList":[{"address":"apiexmailbox90@apidomain92.com","replyTo":true}],"hasBlackBerryMobileService":false,"hasActiveSyncMobileService":false}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

== Add/Edit ==

''URL'':
<nowiki>Add: [POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)
Edit: [PUT] http://api.emailsrvr.com/v0/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.

{| border=1 class="simple"
!''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
|-
| 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.)
|-
| enabled
| string
| Enable/Disable mailbox, input must be "true" or "false"
|}

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| Required form field is missing
| 400
| Missing required field: displayName
|-
| Required form field has null or empty string input
| 400
| Required field displayName cannot be empty
|-
| 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
|-
| Integer form field has non-integer input
| 400
| Invalid format for size, input must be an integer
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for Enabled, input must be True or False
|-
| New mailbox password doesn't meet the password pattern requirements
| 400
| Password must be at least 8 characters long
|-
| Form data has unrecognized field
| 400
| Unrecognized field: extraStorage
|-
| New mailbox name (user name) already exists
| 400
| The email address john.doe@abc.com is already in use
|}

== Delete ==

''URL'':
<nowiki>[DELETE] http://api.emailsrvr.com/v0/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', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

== Add Email Address ==

''URL'':
<nowiki>[POST] http://api.emailsrvr.com/v0/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', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

== Delete Email Address ==

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

''Description'':

The delete 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', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

== Spam ==

=== Index Blacklist ===

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

''Description'':

This operation returns email address blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Blacklist.xsd Blacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<blacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:blacklist">
<addresses>
<address>name1@spam.com</address>
<address>name2@spam.com</address>
</addresses>
</blacklist>
</pre>

''Json Result Example'':

{"addresses":["name1@spam.com","name2@spam.com"]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

=== Index IP Blacklist ===

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

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpBlacklist.xsd IpBlacklist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist', 'text/xml'
</pre>

''XML Result Example':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipBlacklist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipBlacklist">
<addresses>
<ip>216.12.34.1</ip>
<ip>216.12.34.2</ip>
</addresses>
</ipBlacklist>
</pre>

''Json Result Example'':

{"addresses":["216.12.34.1","216.12.34.2"]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

=== Index Safelist ===

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

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Safelist.xsd Safelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<safelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:safelist">
<addresses>
<address>name1@notspam.com</address>
<address>name2@notspam.com</address>
</addresses>
</safelist>
</pre>

''Json Result Example'':

{"addresses":["name1@notspam.com","name2@notspam.com"]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

=== Index IP Safelist ===

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

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/IpSafelist.xsd IpSafelist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<ipSafelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:ipSafelist">
<addresses>
<ip>192.168.0.1</ip>
<ip>192.168.0.2</ip>
</addresses>
</ipSafelist>
</pre>

''Json Result Example'':

{"addresses":["192.168.0.1","192.168.0.2"]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

=== Add Blacklist ===

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

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@spam.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

=== Add IP Blacklist ===

''URL'':
<nowiki>[POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Add Safelist ===

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

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

=== Add IP Safelist ===

''URL'':
<nowiki>[POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/safelist/(ip address)</nowiki>

''Description'':

Adds an IP to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

=== Delete Blacklist ===

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

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the blacklist
|}

=== Delete IP Blacklist ===

''URL'':
<nowiki>[DELETE] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

=== Delete Safelist ===

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

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

=== Delete IP Safelist ===

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

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist/216.12.34.1', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

=== Show Spam Setting ===

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

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/MailboxSpamSetting.xsd MailboxSpamSetting.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<MailboxSpamSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:MailboxSpamSettings">
<filterLevel>on</filterLevel>
<sendToDomainQuarantine>false</sendToDomainQuarantine>
<quarantineOwner />
</MailboxSpamSettings>
</pre>

''Json Result Example'':

{"filterLevel":"on","sendToDomainQuarantine":false,"quarantineOwner":""}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

=== Edit Spam Setting ===

''URL'':
<nowiki>[PUT] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/spam/settings</nowiki>

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on' or 'off' or 'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Required form field is missing
| 400
| Missing required field: filterlevel
|-
| Required form field has null or empty string input
| 400
| Required field filterlevel cannot be empty
|-
| Form data has unrecognized field
| 400
| Unrecognized field: address
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for sendtodomainquarantine, input must be true or false
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

== BlackBerry Mobile Service ==

=== Index ===

''URL'':
<nowiki>[GET] http://api.emailsrvr.com/v0/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. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/BlackberryMobileServiceList.xsd BlackberryMobileServiceList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/blackberrymobileservices', 'text/xml'
</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"]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Add ===

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

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| Mailbox already has BlackBerry Service
| 400
| User john.smith@example.com has BlackBerry Mobile Service already
|}

=== Delete ===

''URL'':
<nowiki>[DELETE] http://api.emailsrvr.com/v0/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', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

== ActiveSync Mobile Service ==

=== Index ===

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ActiveSyncMobileServiceList.xsd ActiveSyncMobileServiceList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/activesyncmobileservices', 'text/xml'
</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"]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Add ===

''URL'':
<nowiki>[POST] http://api.emailsrvr.com/v0/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/blackberrymobileservice', 'text/xml',
{
'activationPassword' => '12345'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| Mailbox already has BlackBerry Service
| 400
| User john.smith@example.com has BlackBerry Mobile Service already
|}

=== Delete ===

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

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

RestAPI/Mailbox

2009-11-20T20:33:41Z

Kevin.lin: moved RestAPI/Mailbox to Mailbox (Rest API)

#REDIRECT [[Mailbox (Rest API)]]

Exchange Distribution List (Rest API)

2009-11-20T20:32:39Z

Kevin.lin: moved RestAPI/Distributionlist to Distribution List (Rest API)

__TOC__

=== Index ===

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

''Description'':

This operation returns a list of distribution lists associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/DistributionlistList.xsd DistributionlistList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists?size=100&page=1&contains=mailing', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<distributionlistList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:xml:distributionlistList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<distributionlists>
<distributionlist>
<name>apiexgroup4</name>
<displayName>API Test Group</displayName>
</distributionlist>
<distributionlist>
<name>apiexgroup62</name>
<displayName>API Test Group</displayName>
</distributionlist>
<distributionlist>
<name>apiexgroup64</name>
<displayName>API Test Group</displayName>
</distributionlist>
</distributionlists>
</distributionlistList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"distributionlists":[{"name":"apiexgroup4","displayName":"API Test Group"},{"name":"apiexgroup62","displayName":"API Test Group"},{"name":"apiexgroup64","displayName":"API Test Group"}]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution List is not found
| 404
| Distribution List not found
|}

=== Show ===

''URL'':
[<nowiki>GET] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)</nowiki>

''Description'':

Returns the distribution list's details.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Distributionlist.xsd Distributionlist.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

''XML Result Example''

<pre>
<?xml version="1.0" encoding="utf-8"?>
<distributionlist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contact">
<name>apiexgroup64</name>
<displayName>API Test Group</displayName>
<isHidden>false</isHidden>
<emailAddressList>
<emailAddress>
<address>apiexgroup64@apidomain36.com</address>
<replyTo>true</replyTo>
</emailAddress>
</emailAddressList>
<memberList>
<member>apiexmailbox30@apidomain36.com</member>
<member>apiexmailbox7@apidomain36.com</member>
<member>apiexmailbox99@apidomain36.com</member>
</memberList>
</distributionlist>
</pre>

''Json Result Example'':

{"name":"apiexgroup64","displayName":"API Test Group","isHidden":false,"emailAddressList":[{"address":"apiexgroup64@apidomain36.com","replyTo":true}],"memberList":["apiexmailbox30@apidomain36.com","apiexmailbox7@apidomain36.com","apiexmailbox99@apidomain36.com"]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Add/Edit ===

''URL'':
<nowiki>Add: [POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)
Edit: [PUT] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)</nowiki>

''Description'':

Adds/edits the distribution list with the specified information. Required fields must be supplied when adding. Others are optional.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Distribution list display name (Required)
|-
| isHidden
| boolean
| Whether or not the distribution list is hidden from the Global Address List (Defaults to false)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'name' => 'all.employees',
'displayName' => 'Employees'
},
'text/xml'
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'displayName' => 'Example.com Employees'
},
'text/xml',
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Required form field is missing
| 400
| Missing required field: name
|-
| Required form field has null or empty string input
| 400
| Required field displayName cannot be empty
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for isHidden, input must be True or False
|-
| Form data has unrecognized field
| 400
| Unrecognized field: size
|-
| New distribution list name already exists
| 400
| The email address john.doe@abc.com is already in use
|-
| New distribution list name doesn't meet the naming requirements
| 400
| Invalid user name
|-
| New distribution list display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Distribution list is not found
| 404
| Distribution List not found
|-
| Display name doesn't meet the naming requirements
| 400
| Invalid display name
|}

=== Delete ===

''URL'':
<nowiki>[DELETE] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)</nowiki>

''Description'':

Deletes the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Email Addresses ===

This refers to the email addresses a distribution list can appear as.

==== Add Email Address ====

''URL'':
<nowiki>[POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)/emailaddresses/(email address)</nowiki>

''Description'':

Adds an email address that the distribution list is associated with to the list. This address' domain name must be the same as the domain the distribution list is under.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/emailaddresses/alex@example.com', {}, 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution list is not found
| 404
| Distribution list not found
|}

==== Delete Email Address ====

''URL'':
<nowiki>[DELETE] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)/emailaddresses/(email address)</nowiki>

''Description'':

Deletes the email address that is tied to the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/emailaddresses/alex@example.com', 'text/xml'
</pre>

=== Member ===

This refers to the recipients of the distribution list.

==== Add Member ====

''URL'':
<nowiki>[POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)/members/(member name)</nowiki>

''Description'':

Adds an email address to the distribution list.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| Required form field is missing
| 400
| Missing field: addmember
|-
| Form data has unrecognized field
| 400
| Unrecognized field: deletemember
|-
| New member is not found
| 400
| No user with the email address jane.doe exists
|}

==== Delete Member ====

''URL'':
<nowiki>[DELETE] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/distributionlists/(distribution list name)/members/(member name)</nowiki>

''Description'':

Delete an email address from the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| Member is not found
| 400
| Invalid group member name
|}

RestAPI/Distributionlist

2009-11-20T20:32:39Z

Kevin.lin: moved RestAPI/Distributionlist to Distribution List (Rest API)

#REDIRECT [[Distribution List (Rest API)]]

Exchange Contact (Rest API)

2009-11-20T20:32:02Z

Kevin.lin: moved RestAPI/Contact to Contact (Rest API)

__TOC__

=== Index ===

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

''Description'':

Returns a list of contacts under the domain.

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/ContactList.xsd ContactList.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts?size=100&page=1&contains=john', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<contactList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contactList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<contacts>
<contact>
<name>apiexcontact66</name>
<displayName>API Test</displayName>
<externalEmail>externalemail58@yahoo.com</externalEmail>
</contact>
<contact>
<name>apiexcontact73</name>
<displayName>API Test</displayName>
<externalEmail>externalemail98@yahoo.com</externalEmail>
</contact>
<contact>
<name>apiexcontact81</name>
<displayName>API Test</displayName>
<externalEmail>externalemail46@yahoo.com</externalEmail>
</contact>
</contacts>
</contactList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"contacts":[{"name":"apiexcontact66","displayName":"API Test","externalEmail":"externalemail58@yahoo.com"},{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com"},{"name":"apiexcontact81","displayName":"API Test","externalEmail":"externalemail46@yahoo.com"}]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Show ===

''URL'':
<nowiki>[GET] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)</nowiki>

''Description'':

Returns the contact's details.

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Contact.xsd Contact.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<contact xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contact">
<name>apiexcontact73</name>
<displayName>API Test</displayName>
<externalEmail>externalemail98@yahoo.com</externalEmail>
<isHidden>false</isHidden>
<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>
</contactInfo>
</contact>
</pre>

''Json Result Example'':

{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com","isHidden":false,"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"}}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Contact is not found
| 404
| Contact not found
|}

=== Add/Edit ===

''URL'':
<nowiki>Add: [POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)

Edit: [PUT] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)</nowiki>

''Description'':

Adds or edits the contact's details as specified. If the contact does not exist, use Add, if it does, use Edit.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Name of contact when displayed (Required for add)
|-
| externalEmail
| string
| Email address (Required for add)
|-
| isHidden
| boolean
| Whether the contact is hidden from the Global List
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| jobTitle
| string
| Job title
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| businessnumber
| string
| Business phone number
|-
| homenumber
| string
| Home phone number
|-
| mobilenumber
| string
| Mobile phone number
|-
| faxnumber
| string
| Fax number
|-
| pagernumber
| string
| Pager number
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| notes
| string
| Notes field
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml',
{
'displayName' => 'Johnny Customer',
'externalEmail' => 'jonny@apple.com'
}
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml',
{
'externalEmail' => 'jonnysNewEmail@microsoft.com',
'company' => 'Microsoft',
'businessnumber' => '425 555 5555'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Contact is not found
| 404
| No user with the email address jane.doe@abc.com exists
|-
| New display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for Enabled, input must be True or False
|-
| Form data has unrecognized field
| 400
| Unrecognized field: size
|-
| Required form field is missing
| 400
| Missing required field: displayName
|-
| Required form field has null or empty string input
| 400
| Required field displayName cannot be empty
|-
| New display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| New contact name (user name) already exists
| 400
| The email address john.doe@abc.com is already in use
|-
| New contact name (user name) is reserved by Exchange
| 400
| user name reserved
|}

=== Delete ===

''URL'':
<nowiki>[DELETE] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)</nowiki>

''Description'':

Deletes the contact.

''Remarks'':

Contact is deleted immediately without verification and data is lost permanently.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Contact is not found
| 404
| No user with the email address jane.doe@abc.com exists
|}

RestAPI/Contact

2009-11-20T20:32:02Z

Kevin.lin: moved RestAPI/Contact to Contact (Rest API)

#REDIRECT [[Contact (Rest API)]]

Domain (Rest API)

2009-11-20T20:31:46Z

Kevin.lin: moved RestAPI/Domain to Domain (Rest API)

__TOC__

== Index ==

''URL'':

<nowiki>[GET] http://api.emailsrvr.com/v0/customers/(customer account number)/domains</nowiki>

''Description'':

This operation returns a list of domains under the account. If a customer account is specified, then a list of domains under that specific account will be returned.

''Remarks'':

To retrieve a list of domains owned by the account that is logged in, use "me" as the customer account number i.e. <nowiki>'http://api.emailsrvr.com/v0/customers/me/domains'</nowiki>. To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number.

The index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/DomainList.xsd DomainList.xsd]

''Example'':

<pre>
get '/customers/all/domains?size=100&page=1', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?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>3</total>
<domains>
<domain>
<name>apidomain53.com</name>
<accountNumber>100000</accountNumber>
<serviceType>both</serviceType>
</domain>
<domain>
<name>apidomain66.com</name>
<accountNumber>100001</accountNumber>
<serviceType>both</serviceType>
</domain>
<domain>
<name>apidomain68.com</name>
<accountNumber>100002</accountNumber>
<serviceType>both</serviceType>
</domain>
</domains>
</domainList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":3,"domains":[{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both"},{"name":"apidomain66.com","accountNumber":"100001","serviceType":"both"},{"name":"apidomain68.com","accountNumber":"100002","serviceType":"both"}]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Customer account number is invalid
| 404
| Invalid account number
|}

== Show ==

''URL'':

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

''Description'':

The show operation will return detailed information about the specified domain name.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Domain.xsd Domain.xsd]

''Example'':

<pre>
get '/customers/999999/domains/example.com', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<domain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domain">
<name>apidomain66.com</name>
<accountNumber>100000</accountNumber>
<serviceType>both</serviceType>
<exchangeBaseMailboxSize>2048</exchangeBaseMailboxSize>
<exchangeUsedStorage>0</exchangeUsedStorage>
<exchangeTotalStorage>18432</exchangeTotalStorage>
<exchangeExtraStorage>10240</exchangeExtraStorage>
<exchangeMaxNumMailboxes>4</exchangeMaxNumMailboxes>
<rsEmailBaseMailboxSize>2048</rsEmailBaseMailboxSize>
<rsEmailMaxNumberMailboxes>4</rsEmailMaxNumberMailboxes>
<rsEmailExtraStorage>10240</rsEmailExtraStorage>
<rsEmailUsedStorage>0</rsEmailUsedStorage>
<aliases />
<hasArchivingService>false</hasArchivingService>
<hasBlackBerryMobileService>true</hasBlackBerryMobileService>
<blackBerryLicenses>4</blackBerryLicenses>
<hasActivesyncMobileService>true</hasActivesyncMobileService>
<activeSyncLicenses>4</activeSyncLicenses>
<hasGoodmobileMobileService>true</hasGoodmobileMobileService>
<goodmobileLicenses>4</goodmobileLicenses>
</domain>
</pre>

''Json Result Example'':

{"name":"apidomain66.com","accountNumber":"200001","serviceType":"both","exchangeBaseMailboxSize":2048,"exchangeUsedStorage":0,"exchangeTotalStorage":18432,"exchangeExtraStorage":10240,"exchangeMaxNumMailboxes":4,"rsEmailBaseMailboxSize":2048,"rsEmailMaxNumberMailboxes":4,"rsEmailExtraStorage":10240,"rsEmailUsedStorage":0,"aliases":[],"hasArchivingService":false,"hasBlackBerryMobileService":true,"blackBerryLicenses":4,"hasActivesyncMobileService":true,"activeSyncLicenses":4,"hasGoodmobileMobileService":true,"goodmobileLicenses":4}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

== Add/Edit ==

''URL'':
<nowiki>
Add: [POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
Edit: [PUT] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
</nowiki>

''Description'':

Adds/edits a new domain to the account with the data specified. To add a domain to your own account, use your own account id.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| serviceType
| string
| Domain service type. "rsemail" = "Rackspace Email Only". "exchange" = "Exchange Only". "both" = "Rackspace Email and Exchange"
|-
| exchangeExtraStorage
| int
| Exchange service extra storage in megabytes
|-
| exchangeMaxNumMailboxes
| int
| Maximum number of mailboxes allowed under the domain Exchange service. Required for Adding Exchange service
|-
| rsEmailBaseMailboxSize
| int
| Rackspace Email base mailbox size in megabytes
|-
| rsEmailMaxNumberMailboxes
| int
| Maximum number of mailboxes allowed under the domain Rackspace Email service. Required for Adding Rackspace Email service
|-
| rsEmailExtraStorage
| int
| Rackspace Email service extra storage in megabytes
|-
| blackberry
| boolean
| Enable or disable domain BlackBerryMobile service
|-
| blackberryLicenses
| int
| Maximum number of mailboxes allowed to have BlackBerryMobile service. 0 means unlimited
|-
| activesync
| boolean
| Enable or disable domain ActiveSyncMobile service
|-
| activesyncLicenses
| int
| Maximum number of mailboxes allowed to have ActiveSyncMobile service. 0 means unlimited
|-
| goodmobile
| boolean
| Enable or disable domain GoodMobile service
|-
| goodmobileLicenses
| int
| Maximum number of mailboxes allowed to have GoodMobile service. 0 means unlimited
|-
| hasArchivingService
| boolean
| Enable or disable domain archiving service
|-
|}

''Example'':

<pre>
post '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '5',
'extraStorage' => '1024'
}
</pre>

<pre>
put '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '25',
'extraStorage' => '2048'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Customer account number is invalid
| 404
| Invalid account number
|-
| Form data has unrecognized field
| 400
| Unrecognized field: size
|-
| Required form field is missing
| 400
| Missing required field: maxNumMailboxes
|-
| Required form field has null or empty string input
| 400
| Required field name cannot be empty
|-
| Integer form field has non-integer input
| 400
| Invalid format for maxNumMailboxes, input must be an integer
|-
| New domain name doesn't meet the naming requirements
| 400
| Invalid domain name
|-
| New domain name already exists
| 400
| abc.com already exists as a domain or alternate domain
|}

== Move ==

''URL'':

<nowiki>[PUT] http://api.emailsrvr.com/v0/customers/(new customer account number)/domains/(domain name)</nowiki>

''Description'':

Moves the domain to another customer account.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| moveDomain
| boolean
| Indicate whether or not moving the domain
|}

''Remarks'':

Note 'Move Domain' and 'Edit Domain' share the same URI and HTTP verb. When the domain doesn't belong to the customer and 'moveDomain' is set to 'true', API will take the request as a 'Move Domain' call.

''Example'':

<pre>
put '/customers/123456/domains/newcompany.com', 'text/xml',
{
'moveDomain' => 'true'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Customer is not found
| 404
| Customer not found
|}

== Delete ==

''URL'':

<nowiki>[DELETE] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)</nowiki>

''Description'':

Deletes the domain.

''Remarks'':

The domain and all the mailboxes, mailbox contents, groups, and contacts are deleted permanently.

''Example'':

<pre>
delete '/customers/12345678/domains/newcompany.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

== Archiving SSO Login URL ==

''URL'':

<nowiki>[GET] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain)/archivingSSOLoginURL</nowiki>

''Description'':

Gets the domain archiving service SSO login URL.

''Remarks'':

The retrieved URL can be used in browser to access the domain archiving control panel.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/archivingSSOLoginURL', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| No archiving service
| 404
| Domain abc.com has no archiving service enabled
|}

RestAPI/Domain

2009-11-20T20:31:46Z

Kevin.lin: moved RestAPI/Domain to Domain (Rest API)

#REDIRECT [[Domain (Rest API)]]

Customer (Rest API)

2009-11-20T20:30:21Z

Kevin.lin: moved RestAPI/Customer to Customer (Rest API)

__TOC__

== Index ==

''URL'':

[GET] <nowiki>http://api.emailsrvr.com/v0/customers</nowiki>

''Description'':

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

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/CustomerList.xsd CustomerList.xsd]

''Example'':

<pre>
get '/customers?size=100&page=1', 'text/xml'
</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'':

{"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"}]}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|}

== Show ==

''URL'':

[GET] <nowiki>http://api.emailsrvr.com/v0/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>'http://api.emailsrvr.com/v0/customers/me'</nowiki>.

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/Customer.xsd Customer.xsd]

''Example'':

<pre>
get '/customers/me', 'text/xml'
</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>
</customer>
</pre>

''Json Result Example'':

{"name":"API Customer 17","accountNumber":"460182","referenceNumber":"49"}

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Customer account number is invalid
| 404
| Invalid account number
|}

== Add/Edit ==

''URL'':

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

''Description'':

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

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| name
| string
| The customer's display name (Required for Add)
|-
| referenceNumber
| string
| The reference number of this account
|}

''Example'':

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

<pre>
put '/customers/999999', 'text/xml',
{
'name' => 'NewName',
'referenceNumber' => '12345'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| The name field was not specified
| 400
| Missing required field: name
|-
| The name field cannot be blank
| 400
| Required field name cannot be empty
|-
| Names cannot start with a space
| 400
| Improper Customer Name
|-
| The customer account was not found
| 404
| Customer Not Found
|}

== Delete ==

''URL'':

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

''Description'':

Deletes the account.

''Example'':

<pre>
delete '/customers/999999', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| The customer account was not found
| 404
| Customer Not Found
|}

RestAPI/Customer

2009-11-20T20:30:21Z

Kevin.lin: moved RestAPI/Customer to Customer (Rest API)

#REDIRECT [[Customer (Rest API)]]

Rest API

2009-11-20T20:29:16Z

Kevin.lin: moved RestAPI to Rest API

{{TOC_right}}

== Introduction ==

The Email API provides most of the functions of Rackspace's Email and Apps Control Panel through a web-based API ([http://en.wikipedia.org/wiki/Application_programming_interface Application Programming Interface]). 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. The API is a RESTful web service based on the Hypertext Transfer Protocol (HTTP). Actions and data requests are performed by using HTTP-based commands. For more information on RESTful web services refer to the following sites:

http://en.wikipedia.org/wiki/Representational_State_Transfer

http://java.sun.com/developer/technicalArticles/WebServices/restful/

Right now the API is in its beta release and is restricted to resellers only.

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

{| border=1 class="simple"
!Resource
!Example URI
|-
| [[RestAPI/Customer| Customer]]
| /customers/123456789
|-
| [[RestAPI/Domain| Domain]]
| /customers/123456789/domains/example.com
|-
| [[RestAPI/Mailbox| Exchange Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
|-
| [[RestAPI/Distributionlist| Exchange Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
|-
| [[RestAPI/Contact| Exchange Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
|}

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

== Accessing the API ==

Your application will need to make HTTP requests to remote servers. Most programming languages have this function provided in its class library. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE. All API calls should be directed to a URL in the following format.
<pre>http://api.emailsrvr.com/(version)/(resource)</pre>

Example:
<pre>http://api.emailsrvr.com/v0/customers/12345678/domains/customerbusiness.com</pre>

=== Versions ===

{| border=1 class="simple"
!''Supported Versions''
!''URL''
!''Version Documentation''
|-
| v0 (current)
| <nowiki>http://api.emailsrvr.com/v0/</nowiki>
| http://signup.apps.rackspace.com/api-wiki/index.php/RestAPI
|}

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 http://api.emailsrvr.com/v0/. 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.

Note: Pre-release versions of the API will be located at <nowiki>http://api.emailsrvr.com/v0/</nowiki>.

{| border=1 class="simple"
!''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 that are generated from the Control Panel Web interface.

{| border=1 class="simple"
!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'''>:<'''Signature'''>

Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

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

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

 
'''Signature''':

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 Interface20010317143725QHOvchm/40czXhJ1OxfxK7jDHr3t''

Resulting base-64 SHA1 Hash: ''HKUn0aajpSDx7qqGK3vqzn3FglI=''

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 URLs, corresponding HTTP Methods, and necessary form data for the desired operations are detailed in the [[RestAPI#Operations|operation pages]].

==== 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 consistent and is outlined in the table below.

{| border=1 class="simple"
!''HTTP Method''
!''Operations''
|-
|rowspan=2|GET
|Index - returns a list of the resources
|-
|Show - returns the details of the resource
|-
|POST
|Add - adds a new resource
|-
|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:

{| border=1 class="simple"
!''Header Name''
!''Description''
!''Example''
|-
| Accept
| The requested content type (required regardless of type of operation)
| ''text/xml''
|-
| User-Agent
| An identifier you choose for your client software
| ''Rackspace Management Interface''
|-
| X-Api-Signature
| An authentication string explained in detail [[RestAPI#X-Api-Signature_Header|here]]
| ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''
|}

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

{| border=1 class="simple"
!''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
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

'''Reference Number'''

For the customer object only, the query string "referenceNumber=xx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

==== Throttling ====

The server limits the number of requests allowed per user in a certain period of time. The current limit is 2500 requests over 5 minutes. 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.

==== Examples ====

Example requests:
<pre>
Index of Exchange Mailboxes:

Hypertext Transfer Protocol
GET /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Request Method: GET
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml

Adding New Exchange Mailbox:

Hypertext Transfer Protocol
POST /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith HTTP/1.1
Request Method: POST
Request URI: /v0/customers/12345678/domains/example.com/ex/mailboxes/john.smith
Request Version: HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
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 ===

On a successfully executed request, a 200 HTTP Code is returned. Requested data is also returned if the operation was a Show or Index action. If the request is unsuccessful, then an error HTTP Code is returned with a message detailing the error. The errors and their corresponding codes are detailed on the operation pages.

==== Returned Data ====

Requests for data (index and show requests) are returned with XML or JSON data based on what your application populates the HTTP Accept Header 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 extract data from 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 library with the functions necessary for whichever method you choose to use to extract data.

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.

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

{| border=1 class="simple"
!''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.
|}

== 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>
module NetMethods
def get(url_string, format)
url = URI.parse('http://' + server_host + server_port + version + url_string)
@response = Net::HTTP::start(url.host, url.port) do |http|
sign_request
assign_format(format)
@request = Net::HTTP::Get.new(url.path, @headers)

http.request(@request)
end
end

def post(url_string, format, fields_hash)
url = URI.parse('http://' + server_host + server_port + version + url_string)

sign_request
assign_format(format)
@request = Net::HTTP::Post.new(url.path, @headers)

@request.set_form_data(fields_hash)
@response = Net::HTTP::start(url.host, url.port) do |http|
http.request(@request)
end
end

def assign_format (format)
@headers['Accept'] = format
end

def sign_request
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S00')
apiKey = 'XXXXXXXXXXXXXXXXXXXX'
secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

data_to_sign = apiKey + userAgent + timestamp + secretKey

signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))

@headers = Hash.new
@headers['User-Agent'] = userAgent
@headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature
end

def server_host
'api.emailsrvr.com'
end

def server_port
'80'
end

def version
'/v0'
end
end
</pre>

=== C# ===

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

<pre>
using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = userAgent;

var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmssff");

var dataToSign = apiKey + userAgent + dateTime + secretKey;
var hash = SHA1.Create();
var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
var signature = Convert.ToBase64String(signedBytes);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

The PHP Example can be found [http://signup.apps.rackspace.com/api-wiki/index.php/RestAPI/Examples/PHP here].

RestAPI

2009-11-20T20:29:16Z

Kevin.lin: moved RestAPI to Rest API

#REDIRECT [[Rest API]]