Rackspace Email & Apps API - User contributions [en]

Main Page

2011-08-11T17:01:19Z

Subir.jolly: /* Recent Changes */

== Introduction ==

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

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

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

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

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

== Recent Changes ==
'''08/11/11'''
{|
|
New features:
* Bulk operations for Alias resource. [http://api-wiki.apps.rackspace.com/api-wiki/index.php/Rackspace_Alias%28Rest_API%29#Bulk_Modify_Alias_List Click here] for more details.
* Returning fault in response body on errors instead of plain text description. [http://api-wiki.apps.rackspace.com/api-wiki/index.php/Main_Page#Errors Click here] for more details.
|
|}

'''10/31/10 '''
{|
|
New features:
* Rackspace Mailbox indexes now support custom fields.
* A Login Token may now be generated for Rackspace Mailboxes.
* Users can set Rackspace Mailbox storage notification settings. See [[Rackspace_Storage_Notification_(Rest_API)| here]] for more details.
* Users can now manage admins. See [[Admin_(Rest_API)| here]] for more details.
* Added Email Everyone to Domain operations. See [[Domain_(Rest_API)#Domain_Email_Everyone | here]] for more details.
* Added Show/Edit Catch-All Address to Domain operations. See [[Domain_(Rest_API)#Show_Domain_Catch-All_Address | here]] for more details.
|
|}

'''09/01/10 '''
{|
|
New features:
* Now Rackspace Email Mailbox can be marked as visible in Exchange Global Address List.
* Exchange Mailbox can be marked as visible in Rackspace Email Company Directory.
* Rackspace Email/Exchange Mailbox last login time.
* Filter Rackspace Email/Exchange Mailbox by "Enabled" flag.
* Resellers now can create Login Token that only can be used to log into sub-account Control Panel. See [[Customer_(Rest_API)#Create_Login_Tokens| here]].
|
|}

'''08/01/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Contact info. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added Create Login Token. See [[Customer_(Rest_API)#Create_Login_Tokens| here]].
|
|}

'''06/20/10 '''
{|
|
New features:
* Added [[Rackspace_Alias(Rest_API)| Rackspace Email Alias]].
|
|}

'''06/11/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Spam Settings/Blacklist/Safelist. See [[Rackspace_Mailbox_Spam_(Rest_API)| here]].
* Now Rackspace Email Mailbox can Show/Edit vacation message and email forwarding address. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added SharePoint Service Settings. See [[SharePoint_(Rest_API)| here]].
|
|}

'''05/16/10 '''
{|
|
New features:
* Added shortened URLs. Any URLs that starts with '/customers/me/domains/~' is equivalent to '/domains/~'.
* Added Rackspace Email Mailbox Add/Edit/Delete/Index. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Allows to customize Exchange mailbox list result. See [[Exchange_Mailbox_(Rest_API)#Index| Exchange Mailbox Index]] action 'Custom Fields' section.
|
|}

{|
|
Changes:
* Server throttling section has been updated. See [[Rest_API#Throttling| here]].
|
|}

{|
|
Bug fix:
* Fixed a bug that request without User-Agent Header gets 500 error. Now it gets "Authentication failed".
|
|}

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

== Operations ==

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

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

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

== Quick Start ==

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

'''Making your first API call, an Show Customer request:'''
# Obtain your API keys
#:* 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 number of requests made are logged per minute. Calls that were made correctly with a user's API key, but not completed for any reason, including those exceeding the throttle limit, are included in this count.

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

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

==== Examples ====

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

When an error occurs, the system will return an HTTP error response code denoting the type of error. The system will also return additional information about the fault in the body of the response.

'''Example Fault Response – XML'''
<pre>
<appsFault code="500">
<message>Fault!</message>
<details>Error Details...</details>
</appsFault>
</pre>

'''Example Fault Response – JSON'''
<pre>
{
"appsFault" : {
"code" : 500,
"message" : "Fault!",
"details" : "Error Details..."
}
}
</pre>

The error code is returned in the body of the response for convenience. The message section returns a human-readable message that is appropriate for display to the end user. The details section is optional and may contain information—for example, a stack trace—to assist in tracking down an error. The detail section may or may not be appropriate for display to an end user.
The root element of the fault (e.g. appsFault) may change depending on the type of error. The following is a list of possible common root elements along with their associated error codes. More specific faults may be may exist for different resources and will be documented with those resources.

{| class="wikitable"
!''Fault Element''
!''Error Codes''
!''Custom Fields''
|-
|appsFault
|500, 400, and other codes
|
|-
|itemNotFound
|404
|resourceType - What resource in the request that was not found (Domain, Mailbox, etc.)
|-
|unauthorized
|403
|
|-
|badRequest
|400
|
|}

From an XML schema perspective, all API faults are extensions of the base fault type AppsAPIFault. When working with a system that binds XML to actual classes (such as JAXB), one should be capable of using AppsAPIFault as a “catch-all” if there's no interest in distinguishing between individual fault types.

'''X-Error-Message Header'''

Prior to faults in the body of HTTP responses, the only information returned to users was the HTTP status code and an HTTP header x-error-message with the error message. This functionality has been kept for backwards compatibility but retrieving fault information in the HTTP body is the recommended approach for new applications.

==== Paging ====

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

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

===== Example =====

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

==== Examples ====

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

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

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

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

== Examples ==

=== Ruby ===

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

<pre>
require 'server.rb'

server = Server.new

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

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

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

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

class Server
include Test::Unit::Assertions

def initialize(server='api.emailsrvr.com', version_prefix='/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]].

Main Page

2011-08-11T16:44:45Z

Subir.jolly: /* Recent Changes */

== Introduction ==

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

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

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

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

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

== Recent Changes ==
'''08/11/11'''
{|
|
New features:
* Bulk operations for Alias resource.
* Returning fault in response body on errors instead of plain text description.
|
|}

'''10/31/10 '''
{|
|
New features:
* Rackspace Mailbox indexes now support custom fields.
* A Login Token may now be generated for Rackspace Mailboxes.
* Users can set Rackspace Mailbox storage notification settings. See [[Rackspace_Storage_Notification_(Rest_API)| here]] for more details.
* Users can now manage admins. See [[Admin_(Rest_API)| here]] for more details.
* Added Email Everyone to Domain operations. See [[Domain_(Rest_API)#Domain_Email_Everyone | here]] for more details.
* Added Show/Edit Catch-All Address to Domain operations. See [[Domain_(Rest_API)#Show_Domain_Catch-All_Address | here]] for more details.
|
|}

'''09/01/10 '''
{|
|
New features:
* Now Rackspace Email Mailbox can be marked as visible in Exchange Global Address List.
* Exchange Mailbox can be marked as visible in Rackspace Email Company Directory.
* Rackspace Email/Exchange Mailbox last login time.
* Filter Rackspace Email/Exchange Mailbox by "Enabled" flag.
* Resellers now can create Login Token that only can be used to log into sub-account Control Panel. See [[Customer_(Rest_API)#Create_Login_Tokens| here]].
|
|}

'''08/01/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Contact info. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added Create Login Token. See [[Customer_(Rest_API)#Create_Login_Tokens| here]].
|
|}

'''06/20/10 '''
{|
|
New features:
* Added [[Rackspace_Alias(Rest_API)| Rackspace Email Alias]].
|
|}

'''06/11/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Spam Settings/Blacklist/Safelist. See [[Rackspace_Mailbox_Spam_(Rest_API)| here]].
* Now Rackspace Email Mailbox can Show/Edit vacation message and email forwarding address. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added SharePoint Service Settings. See [[SharePoint_(Rest_API)| here]].
|
|}

'''05/16/10 '''
{|
|
New features:
* Added shortened URLs. Any URLs that starts with '/customers/me/domains/~' is equivalent to '/domains/~'.
* Added Rackspace Email Mailbox Add/Edit/Delete/Index. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Allows to customize Exchange mailbox list result. See [[Exchange_Mailbox_(Rest_API)#Index| Exchange Mailbox Index]] action 'Custom Fields' section.
|
|}

{|
|
Changes:
* Server throttling section has been updated. See [[Rest_API#Throttling| here]].
|
|}

{|
|
Bug fix:
* Fixed a bug that request without User-Agent Header gets 500 error. Now it gets "Authentication failed".
|
|}

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

== Operations ==

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

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

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

== Quick Start ==

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

'''Making your first API call, an Show Customer request:'''
# Obtain your API keys
#:* 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 number of requests made are logged per minute. Calls that were made correctly with a user's API key, but not completed for any reason, including those exceeding the throttle limit, are included in this count.

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

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

==== Examples ====

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

When an error occurs, the system will return an HTTP error response code denoting the type of error. The system will also return additional information about the fault in the body of the response.

'''Example Fault Response – XML'''
<pre>
<appsFault code="500">
<message>Fault!</message>
<details>Error Details...</details>
</appsFault>
</pre>

'''Example Fault Response – JSON'''
<pre>
{
"appsFault" : {
"code" : 500,
"message" : "Fault!",
"details" : "Error Details..."
}
}
</pre>

The error code is returned in the body of the response for convenience. The message section returns a human-readable message that is appropriate for display to the end user. The details section is optional and may contain information—for example, a stack trace—to assist in tracking down an error. The detail section may or may not be appropriate for display to an end user.
The root element of the fault (e.g. appsFault) may change depending on the type of error. The following is a list of possible common root elements along with their associated error codes. More specific faults may be may exist for different resources and will be documented with those resources.

{| class="wikitable"
!''Fault Element''
!''Error Codes''
!''Custom Fields''
|-
|appsFault
|500, 400, and other codes
|
|-
|itemNotFound
|404
|resourceType - What resource in the request that was not found (Domain, Mailbox, etc.)
|-
|unauthorized
|403
|
|-
|badRequest
|400
|
|}

From an XML schema perspective, all API faults are extensions of the base fault type AppsAPIFault. When working with a system that binds XML to actual classes (such as JAXB), one should be capable of using AppsAPIFault as a “catch-all” if there's no interest in distinguishing between individual fault types.

'''X-Error-Message Header'''

Prior to faults in the body of HTTP responses, the only information returned to users was the HTTP status code and an HTTP header x-error-message with the error message. This functionality has been kept for backwards compatibility but retrieving fault information in the HTTP body is the recommended approach for new applications.

==== Paging ====

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

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

===== Example =====

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

==== Examples ====

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

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

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

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

== Examples ==

=== Ruby ===

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

<pre>
require 'server.rb'

server = Server.new

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

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

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

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

class Server
include Test::Unit::Assertions

def initialize(server='api.emailsrvr.com', version_prefix='/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]].

Main Page

2011-08-11T16:40:04Z

Subir.jolly: /* Errors */

== Introduction ==

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

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

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

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

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

== Recent Changes ==

'''10/31/10 '''
{|
|
New features:
* Rackspace Mailbox indexes now support custom fields.
* A Login Token may now be generated for Rackspace Mailboxes.
* Users can set Rackspace Mailbox storage notification settings. See [[Rackspace_Storage_Notification_(Rest_API)| here]] for more details.
* Users can now manage admins. See [[Admin_(Rest_API)| here]] for more details.
* Added Email Everyone to Domain operations. See [[Domain_(Rest_API)#Domain_Email_Everyone | here]] for more details.
* Added Show/Edit Catch-All Address to Domain operations. See [[Domain_(Rest_API)#Show_Domain_Catch-All_Address | here]] for more details.
|
|}

'''09/01/10 '''
{|
|
New features:
* Now Rackspace Email Mailbox can be marked as visible in Exchange Global Address List.
* Exchange Mailbox can be marked as visible in Rackspace Email Company Directory.
* Rackspace Email/Exchange Mailbox last login time.
* Filter Rackspace Email/Exchange Mailbox by "Enabled" flag.
* Resellers now can create Login Token that only can be used to log into sub-account Control Panel. See [[Customer_(Rest_API)#Create_Login_Tokens| here]].
|
|}

'''08/01/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Contact info. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added Create Login Token. See [[Customer_(Rest_API)#Create_Login_Tokens| here]].
|
|}

'''06/20/10 '''
{|
|
New features:
* Added [[Rackspace_Alias(Rest_API)| Rackspace Email Alias]].
|
|}

'''06/11/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Spam Settings/Blacklist/Safelist. See [[Rackspace_Mailbox_Spam_(Rest_API)| here]].
* Now Rackspace Email Mailbox can Show/Edit vacation message and email forwarding address. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added SharePoint Service Settings. See [[SharePoint_(Rest_API)| here]].
|
|}

'''05/16/10 '''
{|
|
New features:
* Added shortened URLs. Any URLs that starts with '/customers/me/domains/~' is equivalent to '/domains/~'.
* Added Rackspace Email Mailbox Add/Edit/Delete/Index. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Allows to customize Exchange mailbox list result. See [[Exchange_Mailbox_(Rest_API)#Index| Exchange Mailbox Index]] action 'Custom Fields' section.
|
|}

{|
|
Changes:
* Server throttling section has been updated. See [[Rest_API#Throttling| here]].
|
|}

{|
|
Bug fix:
* Fixed a bug that request without User-Agent Header gets 500 error. Now it gets "Authentication failed".
|
|}

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

== Operations ==

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

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

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

== Quick Start ==

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

'''Making your first API call, an Show Customer request:'''
# Obtain your API keys
#:* 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 number of requests made are logged per minute. Calls that were made correctly with a user's API key, but not completed for any reason, including those exceeding the throttle limit, are included in this count.

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

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

==== Examples ====

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

When an error occurs, the system will return an HTTP error response code denoting the type of error. The system will also return additional information about the fault in the body of the response.

'''Example Fault Response – XML'''
<pre>
<appsFault code="500">
<message>Fault!</message>
<details>Error Details...</details>
</appsFault>
</pre>

'''Example Fault Response – JSON'''
<pre>
{
"appsFault" : {
"code" : 500,
"message" : "Fault!",
"details" : "Error Details..."
}
}
</pre>

The error code is returned in the body of the response for convenience. The message section returns a human-readable message that is appropriate for display to the end user. The details section is optional and may contain information—for example, a stack trace—to assist in tracking down an error. The detail section may or may not be appropriate for display to an end user.
The root element of the fault (e.g. appsFault) may change depending on the type of error. The following is a list of possible common root elements along with their associated error codes. More specific faults may be may exist for different resources and will be documented with those resources.

{| class="wikitable"
!''Fault Element''
!''Error Codes''
!''Custom Fields''
|-
|appsFault
|500, 400, and other codes
|
|-
|itemNotFound
|404
|resourceType - What resource in the request that was not found (Domain, Mailbox, etc.)
|-
|unauthorized
|403
|
|-
|badRequest
|400
|
|}

From an XML schema perspective, all API faults are extensions of the base fault type AppsAPIFault. When working with a system that binds XML to actual classes (such as JAXB), one should be capable of using AppsAPIFault as a “catch-all” if there's no interest in distinguishing between individual fault types.

'''X-Error-Message Header'''

Prior to faults in the body of HTTP responses, the only information returned to users was the HTTP status code and an HTTP header x-error-message with the error message. This functionality has been kept for backwards compatibility but retrieving fault information in the HTTP body is the recommended approach for new applications.

==== Paging ====

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

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

===== Example =====

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

==== Examples ====

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

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

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

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

== Examples ==

=== Ruby ===

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

<pre>
require 'server.rb'

server = Server.new

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

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

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

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

class Server
include Test::Unit::Assertions

def initialize(server='api.emailsrvr.com', version_prefix='/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]].

Rackspace Alias(Rest API)

2011-08-11T16:24:46Z

Subir.jolly:

__TOC__

== Index ==

''URL'':

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

''Description'':

Shows a list of aliases for the Rackspace 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/RSAliasList.xsd RSAliasList.xsd]

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

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<aliasList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:aliasList">
<aliases>
<alias>
<name>alias1</name>
<numberOfMembers>3</numberOfMembers>
</alias>
</aliases>
</aliasList>
</pre>

''Json Result Example'':
<pre>
{"aliases":[{"name":"alias1","numberOfMembers":3}]}
</pre>

== Add ==

''URL'':

<nowiki>[POST] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/aliases/(alias name)</nowiki>

''Description'':

Creates an alias.

{| class="wikitable"
!''Field Name''
!''Description''
|-
| aliasEmails
| Comma separated list of domain and non-domain emails.
|}

''Example'':
<pre>
post '/customers/100018/domains/resellerallservices.net/rs/aliases/alias1',
{'aliasEmails'=>'jane.doe@resellerallservices.net, joe.schmoe@resellerallservices.net,e1@yahoo.com, e2@gmail.com'
},
Formats.xml
</pre>

''Remarks'':
Currently there is a limit of 50 domain emails and 4 non-domain emails.

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Non-existent domain email address.
| 400
| An alias must point to a valid email address. The following email addresses do not exist: a@resellerallservices.net
|-
| Empty domain email list and non-domain email list.
| 400
| An alias must point to a valid email address.
|-
| More than four non-domain email addresses specified.
| 400
| Max number of non-local email recipients reached.
|-
|}

== Show ==

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

''Description'':

Returns detailed information about the specified alias.

''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/RSAliasInfo.xsd RSAliasInfo.xsd]

''Example'':
<pre>
get '/customers/100018/domains/resellerallservices.net/rs/aliases/alias1', Formats.xml
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<alias xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:alias">
<name>alias1</name>
<emailAddressList>
<emailAddress>jane.doe@resellerallservices.net</emailAddress>
<emailAddress>e3@yahoo.com</emailAddress>
</emailAddressList>
</alias>
</pre>

''Json Result Example'':

{"emailAddressList":{"emailAddress":["jane.doe@resellerallservices.net","e3@yahoo.com"]},"name":"alias3"}

''Errors'':

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

== Delete ==

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

''Description'':

Deletes the alias.

''Example'':
<pre>
delete '/customers/100018/domains/resellerallservices.net/rs/aliases/alias1', Formats.xml
</pre>

''Errors'':

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

== Add Email Address to Alias List ==

''URL'':
<nowiki>Adding an email address to a alias.
[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/aliases/(alias name)/(email address)
</nowiki>

''Description'':

Adds an email address to the domain email list or to the non-domain email list.

''Example'':
<pre>
post '/customers/100018/domains/resellerallservices.net/rs/aliases/alias1/joe.schmoe@resellerallservices.net', {}, Formats.xml

</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Non-existent email address in the alias.
| 400
| An alias must point to a valid email address. The following email addresses do not exist: a@resellerallservices.net
|-
| More than four non-domain email addresses specified.
| 400
| Max number of non-local email recipients reached.
|-
| Non existent alias.
| 404
| Resource not found.
|-
|}

== Delete Email Address From Alias List ==

''URL'':
<nowiki>Deleting an email address from an alias.
[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/aliases/(alias name)/(email address)
</nowiki>

''Description'':

Deletes an email address from the domain email list or from the non-domain email list.

''Example'':
<pre>
delete '/customers/100018/domains/resellerallservices.net/rs/aliases/alias1/joe.schmoe@resellerallservices.net', {}, Formats.xml
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Non existent alias.
| 404
| Resource not found.
|-
| Non existent email address in the alias.
| 404
| Email address jane.doe@resellerallservices.net does not exist in alias alias1.
|-
|}

== Bulk Modify Alias List ==

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

''Description'':

You can modify an existing alias by replacing its contents with the new email addresses specified in the field aliasEmails. The following list shows the number of email addresses you can specify:

* 1 - 50 domain email addresses
* 1 - 4 non-domain addresses

You must specify at least one email address. By default, the maximum combined total of email addresses you can specify is 50.

You cannot delete a specific email address using DELETE. If you use DELETE with this operation, the entire alias is deleted.

''Form Fields:''

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| aliasEmail
| string
| A comma separated list of email addresses.
|-
|}

''Example'':
<pre>
put '/customers/100487/domains/testdomain.com/rs/aliases/alias_name',
{ aliasEmails=email@outsider.com,abc@yahoo.com,user1@domain.com, user2@domain.com },
'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Modify Invalid Alias
| 404
| Entity of type Alias identified by user3@domain.com was not found.
|-
| Modify Valid Alias With No Email Address
| 400
| An alias must point to a valid email address.
|-
| Modify Valid Alias With Non Existing Email Address(es)
| 404
| An alias must point to a valid email address. The following email addresses do not exist: user@domain.com.
|}