Rackspace Email & Apps API - User contributions [en]

Exchange Mailbox Spam (Rest API)

2013-02-28T21:37:06Z

Zhen.wei:

__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
|-
| removeQuarantineOwner
| boolean
| Set this flag to "true" to remove quarantine owner
|}

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

=== Edit ===

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

''Description'':

Edit email addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/blacklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
},
'text/xml'
</pre>

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

=== Edit ===

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

''Description'':

Edit IP addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/ipblacklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
},
'text/xml'
</pre>

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

=== Edit ===

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

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
},
'text/xml'
</pre>

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

=== Edit ===

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

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/ex/mailboxes/jane.doe/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
},
'text/xml'
</pre>

Rackspace Mailbox Spam (Rest API)

2013-02-28T21:36:36Z

Zhen.wei:

__TOC__

== Spam Settings ==

=== Show ===

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

''Description'':

This operation returns the spam settings associated with the mailbox. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/RSMailboxSpamSetting.xsd RSMailboxSpamSetting.xsd]

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

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailboxSpamSetting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:RSMailboxSpamSetting">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toFolder</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress />
</rsEmailSettings>
</rsMailboxSpamSetting>
</pre>

''Json Result Example'':

<pre>
{"filterLevel":"on","rsEmailSettings":"hasFolderCleaner":false,"spamFolderAgeLimit":0,"spamFolderNumLimit":0,
"spamForwardingAddress":"","spamHandling":"toFolder"}}
</pre>

=== Edit ===

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

''Description'':

This operation will modify the mailbox spam settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| This is a required field. Spam filter status: 'on', 'off', or 'exclusive'. Exclusive mode allows only email cleared by the Safelist.
|
|-
| rsEmail.spamHandling
| string
| The string 'toFolder' will deliver the email to the user's Spam folder, 'delete' will delete the mail immediately, 'labelSubject' will prepend [SPAM] to the email's subject line, and 'toAddress' will send the email to a specified folder instead.

Valid Field Combinations:

(toFolder => hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit)

(toAddress => spamForwardingAddress)
|-
| rsEmail.hasFolderCleaner
| string
| This field is effective when rsEmail.spamHandling option is set to 'toFolder'. This field controls how the spam that is delivered o the spam folder is handled. There are currently two options supported for handling spam. First option is to set a limit after which the spam gets deleted. One can set limit on the number of days or on the number of spam emails. Second option is to never automatically delete the spam. For both these options to be enabled the rsEmail.hasFolderCleaner field should be set to 'true'.
The folder cleaner fields (hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit) are allowed
only when the spamHandling field is set to 'toFolder'. In order to never delete the spam set the spamFolderAgeLimit and spamFolderNumLimit fields to 0.
|-
| rsEmail.spamFolderAgeLimit
| string
| The number of days a message stays in the Spam folder before its deleted. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamFolderNumLimit
| string
| The maximum number of emails the Spam folder holds. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamForwardingAddress
| string
| The email address that Spam emails will be redirected to. This field is required when the spamHandling field is set to 'toAddress'
|}

''Example'':
<pre>
put '/customers/100018/domains/resellerallservices.net/rs/mailboxes/unittestexist/spam/settings',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}, Formats.xml
</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
|-
| Invalid input for form field 'spamHandling'
| 400
| Invalid RSEmail SpamHandling: Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid email address in spam forwarding address
| 400
| Invalid email address
|-
| Empty forwarding address
| 400
| Spam Forwarding Address cannot be empty for spam handling policy: toAddress
|-
| Invalid value for field 'spamFolderAgeLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamFolderAgeLimit should be non-negative
|-
| Invalid value for field 'spamFolderNumLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamNumberLimit should be non-negative.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: delete.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: labelSubject.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: toAddress.
|}

== Blacklist ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/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/rs/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
|}

=== Edit ===

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

''Description'':

Edit email addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/blacklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
},
'text/xml'
</pre>

== IP Blacklist ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/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
|}

=== Edit ===

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

''Description'':

Edit IP addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/ipblacklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
},
'text/xml'
</pre>

== Safelist ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/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/rs/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
|}

=== Edit ===

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

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
},
'text/xml'
</pre>

== IP Safelist ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the ipsafelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/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
|}

=== Edit ===

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

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/jane.doe/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
},
'text/xml'
</pre>

Domain Spam (Rest API)

2013-02-28T21:35:56Z

Zhen.wei:

== Spam Settings ==

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

== Blacklist ==

=== 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"]}

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

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

=== Edit Blacklist ===

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

''Description'':

Edit email addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/blacklist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
},
'text/xml'
</pre>

== IP Blacklist ==

=== 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"]}

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

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

=== Edit IP Blacklist ===

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

''Description'':

Edit IP addresses on the blacklist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/ipblacklist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
},
'text/xml'
</pre>

== Safelist ==

=== 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"]}

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

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

=== Edit Safelist ===

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

''Description'':

Edit email addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of email addresses to add to the list
|-
| removeList
| string
| Comma separated list of email addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in domains, but not in the TLD (.com, .net, etc). You cannot use wildcards in email addresses. For example, the following are allowed: @%.example.com, @examp%.com.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/safelist',
{
'addList' => '@%.example.com,abc@example.com',
'removeList' => '@examp%.com'
},
'text/xml'
</pre>

== IP Safelist ==

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

=== Edit IP Safelist ===

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

''Description'':

Edit IP addresses on the safelist.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| addList
| string
| Comma separated list of IP addresses to add to the list
|-
| removeList
| string
| Comma separated list of IP addresses to remove from the list
|}

''Note'':

You can use a '%' as a wildcard in the last octets to specify IP ranges. For example: 216.12.34.%, 216.12.%.%, 216.%.%.%.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/spam/ipsafelist',
{
'addList' => '216.12.34.%,216.12.%.%',
'removeList' => '216.%.%.%'
},
'text/xml'
</pre>

Main Page

2012-11-27T20:40:37Z

Zhen.wei:

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

== Operations ==

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

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

The API version number is a component of the URL that is used to access the API. For example, to access the root of the API, the URL is https://api.emailsrvr.com/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. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/faults.xsd Faults.xsd]

'''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.IO;
using System.Net;
using System.Security.Cryptography;
using System.Text;

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

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

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

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

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

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

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

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

}

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

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

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

=== PHP ===

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

Main Page

2012-11-27T03:43:25Z

Zhen.wei:

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

== Operations ==

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

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

The API version number is a component of the URL that is used to access the API. For example, to access the root of the API, the URL is https://api.emailsrvr.com/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. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/faults.xsd Faults.xsd]

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

Rest API

2012-11-27T03:17:05Z

Zhen.wei:

== Recent Changes ==

'''09/01/10 '''
{|
|
New features:
* Now Rackspace Email Mailboxes can be visible in Exchange Global Address List. And Exchange Mailboxes can be visible in Rackspace Email Company Directory.
* Now Index Rackspace Email/Exchange Mailbox can filter mailboxes by "enabled" flag.
* Added "lastLogin" to Rackspace Email/Exchange Mailbox Show.
|
|}

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

== 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
| [[Customer_(Rest_API)#Create_Login_Tokens| Create Login Token]]
|-
| [[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_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_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://api-wiki.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 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 ====

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

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

MediaWiki:Sidebar

2012-11-09T22:13:57Z

Zhen.wei:

* navigation
** Mainpage|Rest API
** Soap_API_(Deprecated)|Soap API (Deprecated)
** helppage|help
* SEARCH
* TOOLBOX
* LANGUAGES

Soap API (Deprecated)

2012-11-09T22:12:33Z

Zhen.wei: Created page with '== The Rackspace Email Soap API Deprecation == === Why are you doing this? === In order to maximize our ability to deliver great functionality quickly, we have to make the toug…'

== The Rackspace Email Soap API Deprecation ==

=== Why are you doing this? ===
In order to maximize our ability to deliver great functionality quickly, we have to make the tough call to deprecate old stuff that slows us down. We feel that REST is a better approach to web services: It is more scaleable, more securable, more evolvable, and generally simpler to consume, maintain, and support.

=== What does this mean for me? ===

* For customers new to our APIs
For the best support, you should integrate with our [[Main_Page|REST API]]. If there is functionality you need that is not available in the REST API, please tell us. We thrive on your feedback!

* For customers who consume our SOAP API
Deprecation of the SOAP API is not imminent but we highly encourage you to consider revisiting your current applications and update them to use the newer REST API. Once a SOAP API deprecation date has been set there will be 6 month notice prior to its End-Of-Life.

We will not be porting over every function from our SOAP API to our REST API. So the only way to ensure you'll have everything you need when the SOAP API is officially deprecated is to start early, and let us know what is missing.

=== What is currently missing from the REST API, that you plan to add? ===
* Search for a Domain
* Get default max mailbox size for domain
* Get/Set max size for mailbox
* Get mailbox last login date/time
* Get addresses configured to receive forwarded email
* Search mailboxes

If you rely on functionality that is not currently in the [[Main_Page|REST API]], or in this list, please tell us.

== The Rackspace Email Soap API (Deprecated) ==

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.

* [[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

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

2012-05-22T22:14:02Z

Zhen.wei: added link to rse mobile sync on homepage.

== Recent Changes ==
'''05/22/12'''
{|
|
New features:
* Rackspace Email Mobile Sync. [http://api-wiki.apps.rackspace.com/api-wiki/index.php/Rackspace_Email_Mobile_Sync_(Rest_API) Click here] for more details.
|
|}

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

== Operations ==

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

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

The API version number is a component of the URL that is used to access the API. For example, to access the root of the API, the URL is https://api.emailsrvr.com/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. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/faults.xsd Faults.xsd]

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

Domain (Rest API)

2011-07-08T17:24:27Z

Zhen.wei:

__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&offset=10', '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]

''Notes'':

# These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.
# Due to a performance issue Domain Public Folder Status is now returned from an individual URL. See [[Domain_(Rest_API)#Show_Status | Public Folders Status]]. The field 'publicFoldersEnabled' from Show Domain result always returns 'false' at this moment.

''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>
<publicFoldersEnabled>false</publicFoldersEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
</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,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":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 (deprecated)
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses (deprecated)
| 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>

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

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

''Description'':

Retrieves the Exchange Public Folders status for the domain. The XML schema for the returned data is [http://api.emailsrvr.com/v0/Schemas/DomainPublicFolders.xsd DomainPublicFolders.xsd]

''Example'':

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

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
<domainPublicFolders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainPublicFolders">
<enabled>true</enabled>
</domainPublicFolders>
</pre>

=== Enable ===
''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
|}

== Domain Email Everyone ==

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

''Description'':
Send an email to all mailboxes for the domain. This request returns a list of recipients.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| fromName
| string
| Sender's Name.
|-
| fromAddress
| string
| Sender's Email Address.
|-
| subject
| string
| Message subject.
|-
| body
| string
| Message body.
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'fromName' => 'John Doe',
'fromAddress' => 'john.doe@test.com',
'subject' => 'Hi All',
'body' => 'Hello World.',
}
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<emailAddressList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddressList">
<emailAddresses>
<address>a@example.com</address>
<address>b@example.com</address>
</emailAddresses>
</emailAddressList>
</pre>

''Json Result Example'':

{"emailAddresses":["a@example.com","b@example.com"]}

== Show Domain Catch-All Address ==

''URL'':

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

''Description'':

Return the Catch-All Address for the domain. Returns empty string when no Catch-All Address set for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

''Example'':

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

''XML Result Example'':

<pre>

<?xml version="1.0" encoding="utf-8"?>
<emailAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddress">
<address>abc@example.com</address>
</emailAddress>
</pre>

''Json Result Example'':
<pre>
{"address":"abc@example.com"}
</pre>

== Edit Domain Catch-All Address ==

''URL'':

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

''Description'':

Edit the Catch-All Address for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

''Notes'':

This request may take about 1-2 minutes to be applied to the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| address
| string
| The Catch-All email address. Set address to empty string to remove Catch-All Address.
|-
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'address' => 'abc@example.com'
}
</pre>

Domain (Rest API)

2011-07-08T17:20:11Z

Zhen.wei: updated public folder info

__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&offset=10', '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]

''Note'':

# These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.
# Due to a performance issue Domain Public Folder Status is now returned from an individual URL. See [[Domain_(Rest_API)#Show_Status | Public Folders Status]]. The field 'publicFoldersEnabled' from Show Domain result always returns 'false' at this moment.

''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>
<publicFoldersEnabled>false</publicFoldersEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
</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,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":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 (deprecated)
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses (deprecated)
| 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>

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

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

''Description'':

Retrieves the Exchange Public Folders status for the domain. The XML schema for the returned data is [http://api.emailsrvr.com/v0/Schemas/DomainPublicFolders.xsd DomainPublicFolders.xsd]

''Example'':

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

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
<domainPublicFolders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainPublicFolders">
<enabled>true</enabled>
</domainPublicFolders>
</pre>

=== Enable ===
''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
|}

== Domain Email Everyone ==

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

''Description'':
Send an email to all mailboxes for the domain. This request returns a list of recipients.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| fromName
| string
| Sender's Name.
|-
| fromAddress
| string
| Sender's Email Address.
|-
| subject
| string
| Message subject.
|-
| body
| string
| Message body.
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'fromName' => 'John Doe',
'fromAddress' => 'john.doe@test.com',
'subject' => 'Hi All',
'body' => 'Hello World.',
}
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<emailAddressList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddressList">
<emailAddresses>
<address>a@example.com</address>
<address>b@example.com</address>
</emailAddresses>
</emailAddressList>
</pre>

''Json Result Example'':

{"emailAddresses":["a@example.com","b@example.com"]}

== Show Domain Catch-All Address ==

''URL'':

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

''Description'':

Return the Catch-All Address for the domain. Returns empty string when no Catch-All Address set for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

''Example'':

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

''XML Result Example'':

<pre>

<?xml version="1.0" encoding="utf-8"?>
<emailAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddress">
<address>abc@example.com</address>
</emailAddress>
</pre>

''Json Result Example'':
<pre>
{"address":"abc@example.com"}
</pre>

== Edit Domain Catch-All Address ==

''URL'':

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

''Description'':

Edit the Catch-All Address for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

''Notes'':

This request may take about 1-2 minutes to be applied to the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| address
| string
| The Catch-All email address. Set address to empty string to remove Catch-All Address.
|-
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'address' => 'abc@example.com'
}
</pre>

Rackspace Storage Notification (Rest API)

2011-06-21T15:50:09Z

Zhen.wei: minor typo fix.

__TOC__

== Show ==

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

''Description'':

The show operation will return detailed information about a given domain's Rackspace Mailbox storage notification settings that control whether an email notification is sent to users when their mailbox reaches a certain capacity.

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

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

''XML Result Example'':
<pre>
<rsStorageNotification xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsStorageNotification">
<enabled>true</enabled>
<notificationCC>test@email.net</notificationCC>
<notificationMessage>The mailbox is getting full.</notificationMessage>
<notificationPercentage>99</notificationPercentage>
</rsStorageNotification>
</pre>

''Json Result Example'':
<pre>
{"enabled":true, "notificationCC":"test@email.net", "notificationMessage":"Test", "notificationPercentage":99}
</pre>

== Edit ==

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

''Description'':

The edit operation will set detailed information about a given domain's Rackspace Mailbox storage notification settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| enabled
| boolean
| Activates domain storage notification. (Required)
|-
| notificationPercentage
| int
| The storage percentage that triggers the notification. (Required for Add) (Valid Values: 50, 60, 70, 80, 90, 99)
|-
| notificationMessage
| string
| The notification message. (The special tag <*USER*> will substitute in the username. The special tag <*DOMAIN*> will substitute in the domain.)
|-
| notificationCC
| string
| An email address the notification message will be carbon copied to.
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith', 'text/xml',
{
'enabled' => 'true',
'notificationPercentage' => '90',
'notificationMessage' => 'Your mailbox "<*USER*>@<*DOMAIN*>" is almost full.',
'notificationCC' => 'test@testdomain.com'
}
</pre>

Main Page

2010-11-01T21:39:45Z

Zhen.wei:

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

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

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

Domain (Rest API)

2010-11-01T21:39:27Z

Zhen.wei:

__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&offset=10', '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]

''Note'':

These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.

''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>
<publicFoldersEnabled>false</publicFoldersEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
</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,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":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 (deprecated)
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses (deprecated)
| 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>

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

== Domain Email Everyone ==

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

''Description'':
Send an email to all mailboxes for the domain. This request returns a list of recipients.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| fromName
| string
| Sender's Name.
|-
| fromAddress
| string
| Sender's Email Address.
|-
| subject
| string
| Message subject.
|-
| body
| string
| Message body.
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'fromName' => 'John Doe',
'fromAddress' => 'john.doe@test.com',
'subject' => 'Hi All',
'body' => 'Hello World.',
}
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<emailAddressList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddressList">
<emailAddresses>
<address>a@example.com</address>
<address>b@example.com</address>
</emailAddresses>
</emailAddressList>
</pre>

''Json Result Example'':

{"emailAddresses":["a@example.com","b@example.com"]}

== Show Domain Catch-All Address ==

''URL'':

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

''Description'':

Return the Catch-All Address for the domain. Returns empty string when no Catch-All Address set for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

''Example'':

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

''XML Result Example'':

<pre>

<?xml version="1.0" encoding="utf-8"?>
<emailAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddress">
<address>abc@example.com</address>
</emailAddress>
</pre>

''Json Result Example'':
<pre>
{"address":"abc@example.com"}
</pre>

== Edit Domain Catch-All Address ==

''URL'':

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

''Description'':

Edit the Catch-All Address for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

''Notes'':

This request may take about 1-2 minutes to be applied to the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| address
| string
| The Catch-All email address. Set address to empty string to remove Catch-All Address.
|-
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'address' => 'abc@example.com'
}
</pre>

Main Page

2010-11-01T19:29:10Z

Zhen.wei:

== 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| Domain Email Everyone ]]
|-
| [[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 ====

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

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

Domain (Rest API)

2010-11-01T19:22:17Z

Zhen.wei: add catch all

__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&offset=10', '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]

''Note'':

These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.

''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>
<publicFoldersEnabled>false</publicFoldersEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
</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,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":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 (deprecated)
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses (deprecated)
| 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>

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

== Domain Email Everyone ==

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

''Description'':
Send an email to all mailboxes for the domain. This request returns a list of recipients.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| fromName
| string
| Sender's Name.
|-
| fromAddress
| string
| Sender's Email Address.
|-
| subject
| string
| Message subject.
|-
| body
| string
| Message body.
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'fromName' => 'John Doe',
'fromAddress' => 'john.doe@test.com',
'subject' => 'Hi All',
'body' => 'Hello World.',
}
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<emailAddressList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddressList">
<emailAddresses>
<address>a@example.com</address>
<address>b@example.com</address>
</emailAddresses>
</emailAddressList>
</pre>

''Json Result Example'':

{"emailAddresses":["a@example.com","b@example.com"]}

== Show Domain Catch-All Address ==

''URL'':

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

''Description'':

Return the Catch-All Address for the domain. Returns empty string when no Catch-All Address set for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

''Example'':

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

''XML Result Example'':

<pre>

<?xml version="1.0" encoding="utf-8"?>
<emailAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddress">
<address>abc@example.com</address>
</emailAddress>
</pre>

''Json Result Example'':
<pre>
{"address":"abc@example.com"}
</pre>

== Edit Domain Catch-All Address ==

''URL'':

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

''Description'':

Edit the Catch-All Address for the domain.

''Remarks'':

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| address
| string
| The Catch-All email address. Set address to empty string to remove Catch-All Address.
|-
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'address' => 'abc@example.com'
}
</pre>

Main Page

2010-11-01T03:10:21Z

Zhen.wei: 10/31 update 2

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

'''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| Domain Email Everyone ]]
|-
| [[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 ====

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

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

Domain (Rest API)

2010-11-01T02:55:04Z

Zhen.wei:

__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&offset=10', '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]

''Note'':

These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.

''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>
<publicFoldersEnabled>false</publicFoldersEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
</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,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":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 (deprecated)
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses (deprecated)
| 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>

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

== Domain Email Everyone ==

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

''Description'':
Send an email to all mailboxes for the domain. This request returns a list of recipients.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| fromName
| string
| Sender's Name.
|-
| fromAddress
| string
| Sender's Email Address.
|-
| subject
| string
| Message subject.
|-
| body
| string
| Message body.
|}

''Example'':

<pre>
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml',
{
'fromName' => 'John Doe',
'fromAddress' => 'john.doe@test.com',
'subject' => 'Hi All',
'body' => 'Hello World.',
}
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<emailAddressList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddressList">
<emailAddresses>
<address>a@example.com</address>
<address>b@example.com</address>
</emailAddresses>
</emailAddressList>
</pre>

''Json Result Example'':

{"emailAddresses":["a@example.com","b@example.com"]}

Admin (Rest API)

2010-11-01T02:35:13Z

Zhen.wei:

__TOC__

== Index ==

''URL'':

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

''Description'':

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

''Remarks'':

To retrieve a list of admins 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>.

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

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<adminList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:adminList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<admins>
<admin>
<adminId>apiadmin37</adminId>
<type>super</type>
<enabled>true</enabled>
<locked>false</locked>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<type>super</type>
<enabled>true</enabled>
<locked>false</locked>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<type>super</type>
<enabled>true</enabled>
<locked>false</locked>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{"admins":[{"adminId":"apiadmin37","enabled":true,"locked":false,"type":"super"},{"adminId":"apiadmin76","enabled":true,"locked":false,"type":"super"},{"adminId":"apiadmin94","enabled":true,"locked":false,"type":"super"}],"offset":0,"size":50,"total":3}
</pre>

== Show ==

''URL'':

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

''Description'':

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

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

''Example'':

<pre>
get '/customers/999999/admins/admin1', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<admin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:admin">
<adminId>apiadmin1</adminId>
<type>super</type>
<enabled>true</enabled>
<locked>false</locked>
<firstName>First</firstName>
<lastName>Last</lastName>
<email>first.last@rackspace.com</email>
<passwordExpiration>10</passwordExpiration>
<allowSimultaneousLogins>false</allowSimultaneousLogins>
<restrictedIps>
<restrictedIps>1.1.1.1</restrictedIps>
<restrictedIps>1.1.1.2</restrictedIps>
<restrictedIps>1.1.1.3</restrictedIps>
</restrictedIps>
</admin>
</pre>

''Json Result Example'':
<pre>
{"adminId":"apiadmin1","allowSimultaneousLogins":false,"email":"first.last@rackspace.com","firstName":"First","enabled":true,"locked":false,"lastName":"Last","passwordExpiration":10,"restrictedIps":["1.1.1.1","1.1.1.2","1.1.1.3"],"type":"super"}
</pre>

== Add/Edit ==

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

Edit: [PUT] https://api.emailsrvr.com/v0/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v0/admins/(admin name)
</nowiki>

''Description'':

Add a new admin or edit an existing admin under the specified account.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| type
| string
| Admin type (Required for Add). Must be "super", "standard" or "limited". Can't change permissions and domain access for limited admin at this point.
|-
| password
| string
| Admin log in password (Required for Add)
|-
| firstName
| string
| Admin first name (Required for Add)
|-
| lastName
| string
| Admin last name (Required for Add)
|-
| email
| string
| Admin contact email (Required for Add)
|-
| securityQuestion
| string
| Security question (Required for Add)
|-
| securityAnswer
| string
| Security answer (Required for Add)
|-
| passwordExpiration
| int
| The number of days in which password expires. 0 means password never expires.
|-
| allowSimultaneousLogins
| boolean
| Allow simultaneous logins using this Administrative ID
|-
| restrictedIps
| string
| Login restricted to IP address(es). Can be up to 3 valid addresses separated by commas.
|-
| enabled
| boolean
| Enable/disable admin account
|-
| locked
| boolean
| Lock/unlock admin account
|}

''Example'':

<pre>
post '/customers/999999/admins/admin1',
{
'type' => 'super',
'password' => 'password',
'firstName' => 'First',
'lastName' => 'Last',
'email' => 'first.last@rackspace.com',
'securityQuestion' => 'Q',
'securityAnswer' => 'A'
},
'text/xml'
</pre>

<pre>
put '/customers/999999/admins/admin2',
{
'enabled' => 'true',
'locked' => 'false',
'passwordExpiration' => '0',
'allowSimultaneousLogins' => 'true',
'restrictedIps' => '1.1.1.1'
},
'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Password doesn't meet the requirements
| 400
| Password must be 7 to 30 characters.
|-
| Invalid email address
| 400
| Invalid email address.
|-
| Invalid restricted to IP address(es)
| 400
| IP addresses must be valid addresses separated by commas. A maximum of 3 addresses may be entered.
|}

== Delete ==

''URL'':

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

''Description'':

Deletes the admin.

''Example'':

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

Admin (Rest API)

2010-11-01T02:32:29Z

Zhen.wei: create admin page

__TOC__

== Index ==

''URL'':

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

''Description'':

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

''Remarks'':

To retrieve a list of admins 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>.

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

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<adminList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:adminList">
<offset>0</offset>
<size>50</size>
<total>3</total>
<admins>
<admin>
<adminId>apiadmin37</adminId>
<type>super</type>
<isActive>true</isActive>
<isLocked>false</isLocked>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<type>super</type>
<isActive>true</isActive>
<isLocked>false</isLocked>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<type>super</type>
<isActive>true</isActive>
<isLocked>false</isLocked>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{"admins":[{"adminId":"apiadmin37","isActive":true,"isLocked":false,"type":"super"},{"adminId":"apiadmin76","isActive":true,"isLocked":false,"type":"super"},{"adminId":"apiadmin94","isActive":true,"isLocked":false,"type":"super"}],"offset":0,"size":50,"total":3}
</pre>

== Show ==

''URL'':

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

''Description'':

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

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

''Example'':

<pre>
get '/customers/999999/admins/admin1', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<admin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:admin">
<adminId>apiadmin1</adminId>
<type>super</type>
<isActive>true</isActive>
<isLocked>false</isLocked>
<firstName>First</firstName>
<lastName>Last</lastName>
<email>first.last@rackspace.com</email>
<passwordExpiration>10</passwordExpiration>
<allowSimultaneousLogins>false</allowSimultaneousLogins>
<restrictedIps>
<restrictedIps>1.1.1.1</restrictedIps>
<restrictedIps>1.1.1.2</restrictedIps>
<restrictedIps>1.1.1.3</restrictedIps>
</restrictedIps>
</admin>
</pre>

''Json Result Example'':
<pre>
{"adminId":"apiadmin1","allowSimultaneousLogins":false,"email":"first.last@rackspace.com","firstName":"First","isActive":true,"isLocked":false,"lastName":"Last","passwordExpiration":10,"restrictedIps":["1.1.1.1","1.1.1.2","1.1.1.3"],"type":"super"}
</pre>

== Add/Edit ==

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

Edit: [PUT] https://api.emailsrvr.com/v0/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v0/admins/(admin name)
</nowiki>

''Description'':

Add a new admin or edit an existing admin under the specified account.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| type
| string
| Admin type (Required for Add). Must be "super", "standard" or "limited". Can't change permissions and domain access for limited admin at this point.
|-
| password
| string
| Admin log in password (Required for Add)
|-
| firstName
| string
| Admin first name (Required for Add)
|-
| lastName
| string
| Admin last name (Required for Add)
|-
| email
| string
| Admin contact email (Required for Add)
|-
| securityQuestion
| string
| Security question (Required for Add)
|-
| securityAnswer
| string
| Security answer (Required for Add)
|-
| passwordExpiration
| int
| The number of days in which password expires. 0 means password never expires.
|-
| allowSimultaneousLogins
| boolean
| Allow simultaneous logins using this Administrative ID
|-
| restrictedIps
| string
| Login restricted to IP address(es). Can be up to 3 valid addresses separated by commas.
|-
| enabled
| boolean
| Enable/disable admin account
|-
| locked
| boolean
| Lock/unlock admin account
|}

''Example'':

<pre>
post '/customers/999999/admins/admin1',
{
'type' => 'super',
'password' => 'password',
'firstName' => 'First',
'lastName' => 'Last',
'email' => 'first.last@rackspace.com',
'securityQuestion' => 'Q',
'securityAnswer' => 'A'
},
'text/xml'
</pre>

<pre>
put '/customers/999999/admins/admin2',
{
'enabled' => 'true',
'locked' => 'false',
'passwordExpiration' => '0',
'allowSimultaneousLogins' => 'true',
'restrictedIps' => '1.1.1.1'
},
'text/xml'
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Password doesn't meet the requirements
| 400
| Password must be 7 to 30 characters.
|-
| Invalid email address
| 400
| Invalid email address.
|-
| Invalid restricted to IP address(es)
| 400
| IP addresses must be valid addresses separated by commas. A maximum of 3 addresses may be entered.
|}

== Delete ==

''URL'':

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

''Description'':

Deletes the admin.

''Example'':

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

Rest API/Test Bug

2010-10-13T21:27:32Z

Zhen.wei: test bug page

Test Bug

Exchange Mailbox Spam (Rest API)

2010-09-15T14:31:29Z

Zhen.wei: add removeQuarantineOwner

__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
|-
| removeQuarantineOwner
| boolean
| Set this flag to "true" to remove quarantine owner
|}

''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-09-13T20:18:55Z

Zhen.wei: 09/01/2010 update

== Recent Changes ==

'''09/01/10 '''
{|
|
New features:
* Now Rackspace Email Mailboxes can be visible in Exchange Global Address List. And Exchange Mailboxes can be visible in Rackspace Email Company Directory.
* Now Index Rackspace Email/Exchange Mailbox can filter mailboxes by "enabled" flag.
* Added "lastLogin" to Rackspace Email/Exchange Mailbox Show.
|
|}

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

== 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
| [[Customer_(Rest_API)#Create_Login_Tokens| Create Login Token]]
|-
| [[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_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_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 ====

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

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

2010-09-02T00:26:09Z

Zhen.wei:

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

'''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]]
|-
| [[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_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_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 ====

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

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

2010-09-02T00:25:21Z

Zhen.wei: 09/01/2010 update

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

'''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 by their sub-account. 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]]
|-
| [[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_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_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 ====

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

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

Exchange Mailbox (Rest API)

2010-09-02T00:15:29Z

Zhen.wei: 09/01/2010 update

__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

''Filter/Search'':

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

''Remarks'':

The show operation only supports the GET HTTP verb. 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"}]}

''Custom Fields'':

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

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

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

== Add/Edit ==

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/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.)
|-
| visibleInRackspaceEmailCompanyDirectory
| boolean
| Flag indicating whether the mailbox is visible in the company directory
|-
| enabled
| boolean
| Enable/Disable mailbox, input must be "true" or "false"
|-
| lastLogin '''''(read only)'''''
| string
| Date of last login, EST Time (in string format)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith', '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 Settings ==

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

== Mailbox Permissions ==

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

permissionType:= (SendAs | FullAccess | Both)

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

<nowiki>[GET] http://api.emailsrvr.com/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.

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

Rackspace Mailbox (Rest API)

2010-09-02T00:12:45Z

Zhen.wei: 09/01/2010 update

__TOC__

== Index ==

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Filter/Search'':

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

''Remarks'':

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

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

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailboxList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailboxList">
<offset>0</offset>
<size>50</size>
<total>2</total>
<rsMailboxes>
<rsMailbox>
<name>apirsmailbox37</name>
</rsMailbox>
<rsMailbox>
<name>apirsmailbox91</name>
</rsMailbox>
</rsMailboxes>
</rsMailboxList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":2,"rsMailboxes":[{"name":"apirsmailbox37"},{"name":"apirsmailbox91"}]}

== Show ==

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/RSMailbox.xsd RSMailbox.xsd]

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

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
<rsMailbox xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailbox">
<name>apirsmailbox37</name>
<size>10240</size>
<currentUsage>1024</currentUsage>
<vacationMessage>My Test Vacation Message</vacationMessage>
<enableVacationMessage>true</enableVacationMessage>
<emailForwardingAddressList>
<emailAddress>notreal0@apidomain.net</emailAddress>
<emailAddress>notreal1@apidomain.net</emailAddress>
</emailForwardingAddressList>
<saveForwardedEmail>false</saveForwardedEmail>
<lastLogin>2/12/2009 1:00:00 AM</lastLogin>
<createdDate>4/10/2006 7:47:34 PM</createdDate>
<visibleInRackspaceEmailCompanyDirectory>false</visibleInRackspaceEmailCompanyDirectory>
<visibleInExchangeGAL>false</visibleInExchangeGAL>
<contactInfo>
<lastName>Testlast</lastName>
<firstName>Jayfirst</firstName>
<generationQualifier>Jr</generationQualifier>
<initials>A</initials>
<organizationUnit>IT</organizationUnit>
<businessStreet>123 Biz St</businessStreet>
<businessCity>Blacksburg</businessCity>
<businessState>VA</businessState>
<businessPostalCode>24060</businessPostalCode>
<businessCountry>USA</businessCountry>
<homeStreet>456 Home St</homeStreet>
<homeCity>Charlotte</homeCity>
<homeState>NC</homeState>
<homePostalCode>28210</homePostalCode>
<homeCountry>USA</homeCountry>
<businessNumber>555.123.0001</businessNumber>
<homeNumber>555.123.0003</homeNumber>
<mobileNumber>555.123.0004</mobileNumber>
<faxNumber>555.123.0005</faxNumber>
<homeFaxNumber>555.123.0006</homeFaxNumber>
<pagerNumber>555.123.0002</pagerNumber>
<notes>This is my note about my mailbox.</notes>
<title>My Title</title>
<userID>J.Test</userID>
<organizationalStatus>OrgStatus</organizationalStatus>
<employeeType>Full-Time</employeeType>
</contactInfo>
<enabled>true</enabled>
</rsMailbox>
</pre>

''Json Result Example'':

''{"emailForwardingAddressList":["test@resellerallservices.net"],"enableVacationMessage":true,"enabled":true,"contactInfo":{"businessNumber":"555.123.0001" ,"faxNumber":"555.123.0005" ,"firstName":"Jimmy" ,"homeNumber":"555.123.0003" ,"lastName":"TestLaste" ,"mobileNumber":"555.123.0004" ,"notes":"This is my note about my mailbox." ,"pagerNumber":"555.123.0002" ,"businessCity":"" ,"businessCountry":"" ,"businessPostalCode":"" ,"businessState":"" ,"businessStreet":"" ,"employeeType":"DoesNotExist" ,"generationQualifier":"Jr" ,"homeCity":"" ,"homeCountry":"" ,"homeFaxNumber":"555.123.0006" ,"homePostalCode":"" ,"homeState":"" ,"homeStreet":"" ,"initials":"A" ,"organizationUnit":"IT" ,"organizationalStatus":"gainfully employed" ,"title":"My Title" ,"userID":"J.Test"},"name":"unittestexist" ,"saveForwardedEmail":false,"size":10240,"vacationMessage":"Test Vacation Message", "createdDate":"4\/10\/2006 7:47:34 PM", "currentUsage":1024, "visibleInExchangeGAL":false, "visibleInRackspaceEmailCompanyDirectory":false}''

== Add/Edit ==

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

''Description'':

Adds/Edits a Rackspace Email mailbox using the following form fields.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| password
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| enableVacationMessage
| boolean
| indicates whether vacation message has been enabled
|-
| vacationMessage
| string
| A mailbox's vacation message
|-
| emailForwardingAddresses
| string
| A comma delimited list, Maximum 15 addresses, 4 of which can be outside of this domain
|-
| saveForwardedEmail
| string
| Indicates whether to save a copy of any forwarded email
|-
| lastName
| string
| A last name
|-
| firstName
| string
| A first name
|-
| generationQualifier
| string
| A person's generation (ex. Jr., Sr., III)
|-
| initials
| string
| A person's middle initial
|-
| organizationUnit
| string
| A person's organization unit (ex. Marketing)
|-
| 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
|-
| homeFaxNumber
| string
| Home Fax phone number
|-
| businessStreet
| string
| The business street address for a contact
|-
| businessCity
| string
| The business city for a contact
|-
| businessState
| string
| The business state for a contact
|-
| businessPostalCode
| string
| The business postal code/zip code for a contact
|-
| businessCountry
| string
| The business country for a contact
|-
| homeStreet
| string
| The home street address for a contact
|-
| homeCity
| string
| The home city for a contact
|-
| homeState
| string
| The home state for a contact
|-
| homePostalCode
| string
| The home postal code/zip code for a contact
|-
| homeCountry
| string
| The home country for a contact
|-
| notes
| string
| Any notes for the mailbox
|-
| title
| string
| A contact's title
|-
| userID
| string
| A user ID for a contact
|-
| organizationalStatus
| string
| A contact's organization status
|-
| employeeType
| string
| A contact's employee type
|-
| enabled
| boolean
| Status of the mailbox: true = enabled, false = disabled.
|-
| visibleInRackspaceEmailCompanyDirectory
| boolean
| Flag indicating whether the mailbox is visible in the company directory
|-
| visibleInExchangeGAL
| boolean
| Flag indicating whether the mailbox is visible in the Exchange Global Address List
|-
| currentUsage '''''(read only)'''''
| positive integer
| Current space used in mailbox (in MB)
|-
| createdDate '''''(read only)'''''
| string
| Date of mailbox creation, EST Time (in string format)
|-
| lastLogin '''''(read only)'''''
| string
| Date of last login, EST Time (in string format)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith', 'text/xml',
{
'password' => 'Secret13!@#',
'size' => '2048',
'enableVacationMessage' => 'true',
'vacationMessage' => 'My Vacation Message',
'emailForwardingAddresses' => 'sampletest@example.com,sampletest2@example.com',
'saveForwardedEmail' => 'false'
'lastName' => 'Testlastname',
'firstName' => 'Jay',
'generationQualifier' => 'III',
'initials' => 'A',
'organizationUnit' => 'IT',
'businessStreet' => '123 Biz St.',
'businessCity' => 'Blacksburg',
'businessState' => 'VA',
'businessPostalCode' => '24060',
'businessCountry' => 'USA',
'homeStreet' => '456 Home St.',
'homeCity' => 'Charlotte',
'homeState' => 'NC',
'homePostalCode' => '28210',
'homeCountry' => 'USA',
'notes' => 'This is my note about my mailbox.',
'title' => 'My Title',
'userID' => 'J.Test',
'organizationalStatus' => 'OrgStatus',
'employeeType' => 'Full-Time'
'visibleInExchangeGAL'=>'true',
'visibleInRackspaceEmailCompanyDirectory' => 'false'

}
</pre>

== Delete ==
''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/mailboxes/alex.smith', 'text/xml'
</pre>

Rest API

2010-08-23T18:40:23Z

Zhen.wei:

== Recent Changes ==

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

== 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_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_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 ====

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

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

Customer (Rest API)

2010-08-19T15:57:20Z

Zhen.wei: re-write customer search parameter explanation.

__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'':

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

''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&offset=10', '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>

== Create Login Tokens ==

''URL'':

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

''Description'':

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

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

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

''Example'':

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

</pre>

Create login token for virtual user 'dev_cust_limitedadmin'.

<pre>

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

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

xmlns="urn:xml:loginToken">

<user>dev_cust_limitedadmin_460896_vu</user>

<token>EEB0012D8DBC2CAC26E28365D44B537FFF0D79350</token>

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

</loginToken>
</pre>

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

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

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

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

Exchange Resource Mailbox (Rest API)

2010-08-19T15:38:54Z

Zhen.wei: replace page with offset

__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&offset=10&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)
|-
| 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 Distribution List (Rest API)

2010-08-19T15:38:06Z

Zhen.wei: replace page with offset

__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&offset=10&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
|}

Exchange Contact (Rest API)

2010-08-19T15:37:00Z

Zhen.wei: replace page with offset

__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&offset=10&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
|}

Domain (Rest API)

2010-08-19T15:29:07Z

Zhen.wei: replace page with offset

__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&offset=10', '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]

''Note'':

These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.

''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>
<publicFoldersEnabled>false</publicFoldersEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
</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,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":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 (deprecated)
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses (deprecated)
| 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>

== 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-08-19T14:51:37Z

Zhen.wei: replace page with offset

__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&offset=10', '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>

== Create Login Tokens ==

''URL'':

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

''Description'':

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

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

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

''Example'':

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

</pre>

Create login token for virtual user 'dev_cust_limitedadmin'.

<pre>

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

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

xmlns="urn:xml:loginToken">

<user>dev_cust_limitedadmin_460896_vu</user>

<token>EEB0012D8DBC2CAC26E28365D44B537FFF0D79350</token>

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

</loginToken>
</pre>

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

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

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

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

Rackspace Mailbox (Rest API)

2010-08-10T16:09:53Z

Zhen.wei: fix rs mailbox name.

__TOC__

== Index ==

''URL'':

<nowiki>[GET] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/RSMailboxList.xsd RSMailboxList.xsd]

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

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailboxList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailboxList">
<offset>0</offset>
<size>50</size>
<total>2</total>
<rsMailboxes>
<rsMailbox>
<name>apirsmailbox37</name>
</rsMailbox>
<rsMailbox>
<name>apirsmailbox91</name>
</rsMailbox>
</rsMailboxes>
</rsMailboxList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":2,"rsMailboxes":[{"name":"apirsmailbox37"},{"name":"apirsmailbox91"}]}

== Show ==

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/RSMailbox.xsd RSMailbox.xsd]

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

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailbox xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailbox">
<name>apirsmailbox37</name>
<size>10240</size>
<vacationMessage>My Test Vacation Message</vacationMessage>
<enableVacationMessage>true</enableVacationMessage>
<emailForwardingAddressList>
<emailAddress>notreal0@apidomain.net</emailAddress>
<emailAddress>notreal1@apidomain.net</emailAddress>
</emailForwardingAddressList>
<saveForwardedEmail>false</saveForwardedEmail>
<contactInfo>
<lastName>Testlast</lastName>
<firstName>Jayfirst</firstName>
<generationQualifier>Jr</generationQualifier>
<initials>A</initials>
<organizationUnit>IT</organizationUnit>
<businessStreet>123 Biz St</businessStreet>
<businessCity>Blacksburg</businessCity>
<businessState>VA</businessState>
<businessPostalCode>24060</businessPostalCode>
<businessCountry>USA</businessCountry>
<homeStreet>456 Home St</homeStreet>
<homeCity>Charlotte</homeCity>
<homeState>NC</homeState>
<homePostalCode>28210</homePostalCode>
<homeCountry>USA</homeCountry>
<businessNumber>555.123.0001</businessNumber>
<homeNumber>555.123.0003</homeNumber>
<mobileNumber>555.123.0004</mobileNumber>
<faxNumber>555.123.0005</faxNumber>
<homeFaxNumber>555.123.0006</homeFaxNumber>
<pagerNumber>555.123.0002</pagerNumber>
<notes>This is my note about my mailbox.</notes>
<title>My Title</title>
<userID>J.Test</userID>
<organizationalStatus>OrgStatus</organizationalStatus>
<employeeType>Full-Time</employeeType>
</contactInfo>
</rsMailbox>
</pre>

''Json Result Example'':

''{"emailForwardingAddressList":["test@resellerallservices.net"],"enableVacationMessage":true,"contactInfo":{"businessNumber":"555.123.0001" ,"faxNumber":"555.123.0005" ,"firstName":"Jimmy" ,"homeNumber":"555.123.0003" ,"lastName":"TestLaste" ,"mobileNumber":"555.123.0004" ,"notes":"This is my note about my mailbox." ,"pagerNumber":"555.123.0002" ,"businessCity":"" ,"businessCountry":"" ,"businessPostalCode":"" ,"businessState":"" ,"businessStreet":"" ,"employeeType":"DoesNotExist" ,"generationQualifier":"Jr" ,"homeCity":"" ,"homeCountry":"" ,"homeFaxNumber":"555.123.0006" ,"homePostalCode":"" ,"homeState":"" ,"homeStreet":"" ,"initials":"A" ,"organizationUnit":"IT" ,"organizationalStatus":"gainfully employed" ,"title":"My Title" ,"userID":"J.Test"},"name":"unittestexist" ,"saveForwardedEmail":false,"size":10240,"vacationMessage":"Test Vacation Message"}''

== Add/Edit ==

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

''Description'':

Adds/Edits a Rackspace Email mailbox using the following form fields.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| password
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| enableVacationMessage
| boolean
| indicates whether vacation message has been enabled
|-
| vacationMessage
| string
| A mailbox's vacation message
|-
| emailForwardingAddresses
| string
| A comma delimited list, Maximum 15 addresses, 4 of which can be outside of this domain
|-
| saveForwardedEmail
| string
| Indicates whether to save a copy of any forwarded email
|-
| lastName
| string
| A last name
|-
| firstName
| string
| A first name
|-
| generationQualifier
| string
| A person's generation (ex. Jr., Sr., III)
|-
| initials
| string
| A person's middle initial
|-
| organizationUnit
| string
| A person's organization unit (ex. Marketing)
|-
| 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
|-
| homeFaxNumber
| string
| Home Fax phone number
|-
| businessStreet
| string
| The business street address for a contact
|-
| businessCity
| string
| The business city for a contact
|-
| businessState
| string
| The business state for a contact
|-
| businessPostalCode
| string
| The business postal code/zip code for a contact
|-
| businessCountry
| string
| The business country for a contact
|-
| homeStreet
| string
| The home street address for a contact
|-
| homeCity
| string
| The home city for a contact
|-
| homeState
| string
| The home state for a contact
|-
| homePostalCode
| string
| The home postal code/zip code for a contact
|-
| homeCountry
| string
| The home country for a contact
|-
| notes
| string
| Any notes for the mailbox
|-
| title
| string
| A contact's title
|-
| userID
| string
| A user ID for a contact
|-
| organizationalStatus
| string
| A contact's organization status
|-
| employeeType
| string
| A contact's employee type
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith', 'text/xml',
{
'password' => 'Secret13!@#',
'size' => '2048',
'enableVacationMessage' => 'true',
'vacationMessage' => 'My Vacation Message',
'emailForwardingAddresses' => 'sampletest@example.com,sampletest2@example.com',
'saveForwardedEmail' => 'false'
'lastName' => 'Testlastname',
'firstName' => 'Jay',
'generationQualifier' => 'III',
'initials' => 'A',
'organizationUnit' => 'IT',
'businessStreet' => '123 Biz St.',
'businessCity' => 'Blacksburg',
'businessState' => 'VA',
'businessPostalCode' => '24060',
'businessCountry' => 'USA',
'homeStreet' => '456 Home St.',
'homeCity' => 'Charlotte',
'homeState' => 'NC',
'homePostalCode' => '28210',
'homeCountry' => 'USA',
'notes' => 'This is my note about my mailbox.',
'title' => 'My Title',
'userID' => 'J.Test',
'organizationalStatus' => 'OrgStatus',
'employeeType' => 'Full-Time'

}
</pre>

== Delete ==
''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/mailboxes/alex.smith', 'text/xml'
</pre>

Main Page

2010-08-02T03:47:31Z

Zhen.wei: replace main page with rest api homepage

== 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/01/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Contact info. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added Create Login Token. See 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
| 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_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_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 ====

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

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

MediaWiki:Sidebar

2010-08-02T03:45:34Z

Zhen.wei: change navigation bar

* navigation
** Mainpage|Rest API
** Soap_API|Soap API
** helppage|help
* SEARCH
* TOOLBOX
* LANGUAGES

Soap API

2010-08-02T03:44:28Z

Zhen.wei: add soap api page

== The Rackspace Email Soap 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.

* [[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

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

Rest API

2010-08-02T03:43:40Z

Zhen.wei: 08/01/10 update

== Recent Changes ==

'''08/01/10 '''
{|
|
New features:
* Added Rackspace Email Mailbox Contact info. See [[Rackspace_Mailbox_(Rest_API)| here]].
* Added Create Login Token. See 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.
|
|}

== 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_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_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 ====

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

===== 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 Mailbox (Rest API)

2010-08-02T03:38:04Z

Zhen.wei: add rs mailbox contact info

__TOC__

== Index ==

''URL'':

<nowiki>[GET] http://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/RSMailboxList.xsd RSMailboxList.xsd]

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

''XML Result Example'':
<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailboxList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailboxList">
<offset>0</offset>
<size>50</size>
<total>2</total>
<rsMailboxes>
<rsMailbox>
<name>apirsmailbox37</name>
</rsMailbox>
<rsMailbox>
<name>apirsmailbox91</name>
</rsMailbox>
</rsMailboxes>
</rsMailboxList>
</pre>

''Json Result Example'':

{"offset":0,"size":50,"total":2,"rsMailboxes":[{"name":"apirsmailbox37"},{"name":"apirsmailbox91"}]}

== Show ==

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/RSMailbox.xsd RSMailbox.xsd]

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

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailbox xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailbox">
<name>apirsmailbox37</name>
<size>10240</size>
<vacationMessage>My Test Vacation Message</vacationMessage>
<enableVacationMessage>true</enableVacationMessage>
<emailForwardingAddressList>
<emailAddress>notreal0@apidomain.net</emailAddress>
<emailAddress>notreal1@apidomain.net</emailAddress>
</emailForwardingAddressList>
<saveForwardedEmail>false</saveForwardedEmail>
<contactInfo>
<lastName>Testlast</lastName>
<firstName>Jayfirst</firstName>
<generationQualifier>Jr</generationQualifier>
<initials>A</initials>
<organizationUnit>IT</organizationUnit>
<businessStreet>123 Biz St</businessStreet>
<businessCity>Blacksburg</businessCity>
<businessState>VA</businessState>
<businessPostalCode>24060</businessPostalCode>
<businessCountry>USA</businessCountry>
<homeStreet>456 Home St</homeStreet>
<homeCity>Charlotte</homeCity>
<homeState>NC</homeState>
<homePostalCode>28210</homePostalCode>
<homeCountry>USA</homeCountry>
<businessNumber>555.123.0001</businessNumber>
<homeNumber>555.123.0003</homeNumber>
<mobileNumber>555.123.0004</mobileNumber>
<faxNumber>555.123.0005</faxNumber>
<homeFaxNumber>555.123.0006</homeFaxNumber>
<pagerNumber>555.123.0002</pagerNumber>
<notes>This is my note about my mailbox.</notes>
<title>My Title</title>
<userID>J.Test</userID>
<organizationalStatus>OrgStatus</organizationalStatus>
<employeeType>Full-Time</employeeType>
</contactInfo>
</rsMailbox>
</pre>

''Json Result Example'':

''{"emailForwardingAddressList":["test@resellerallservices.net"],"enableVacationMessage":true,"contactInfo":{"businessNumber":"555.123.0001" ,"faxNumber":"555.123.0005" ,"firstName":"Jimmy" ,"homeNumber":"555.123.0003" ,"lastName":"TestLaste" ,"mobileNumber":"555.123.0004" ,"notes":"This is my note about my mailbox." ,"pagerNumber":"555.123.0002" ,"businessCity":"" ,"businessCountry":"" ,"businessPostalCode":"" ,"businessState":"" ,"businessStreet":"" ,"employeeType":"DoesNotExist" ,"generationQualifier":"Jr" ,"homeCity":"" ,"homeCountry":"" ,"homeFaxNumber":"555.123.0006" ,"homePostalCode":"" ,"homeState":"" ,"homeStreet":"" ,"initials":"A" ,"organizationUnit":"IT" ,"organizationalStatus":"gainfully employed" ,"title":"My Title" ,"userID":"J.Test"},"name":"unittestexist" ,"saveForwardedEmail":false,"size":10240,"vacationMessage":"Test Vacation Message"}''

== Add/Edit ==

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

''Description'':

Adds/edits a noteworthy mailbox using the following form fields.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| password
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| enableVacationMessage
| boolean
| indicates whether vacation message has been enabled
|-
| vacationMessage
| string
| A mailbox's vacation message
|-
| emailForwardingAddresses
| string
| A comma delimited list, Maximum 15 addresses, 4 of which can be outside of this domain
|-
| saveForwardedEmail
| string
| Indicates whether to save a copy of any forwarded email
|-
| lastName
| string
| A last name
|-
| firstName
| string
| A first name
|-
| generationQualifier
| string
| A person's generation (ex. Jr., Sr., III)
|-
| initials
| string
| A person's middle initial
|-
| organizationUnit
| string
| A person's organization unit (ex. Marketing)
|-
| 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
|-
| homeFaxNumber
| string
| Home Fax phone number
|-
| businessStreet
| string
| The business street address for a contact
|-
| businessCity
| string
| The business city for a contact
|-
| businessState
| string
| The business state for a contact
|-
| businessPostalCode
| string
| The business postal code/zip code for a contact
|-
| businessCountry
| string
| The business country for a contact
|-
| homeStreet
| string
| The home street address for a contact
|-
| homeCity
| string
| The home city for a contact
|-
| homeState
| string
| The home state for a contact
|-
| homePostalCode
| string
| The home postal code/zip code for a contact
|-
| homeCountry
| string
| The home country for a contact
|-
| notes
| string
| Any notes for the mailbox
|-
| title
| string
| A contact's title
|-
| userID
| string
| A user ID for a contact
|-
| organizationalStatus
| string
| A contact's organization status
|-
| employeeType
| string
| A contact's employee type
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith', 'text/xml',
{
'password' => 'Secret13!@#',
'size' => '2048',
'enableVacationMessage' => 'true',
'vacationMessage' => 'My Vacation Message',
'emailForwardingAddresses' => 'sampletest@example.com,sampletest2@example.com',
'saveForwardedEmail' => 'false'
'lastName' => 'Testlastname',
'firstName' => 'Jay',
'generationQualifier' => 'III',
'initials' => 'A',
'organizationUnit' => 'IT',
'businessStreet' => '123 Biz St.',
'businessCity' => 'Blacksburg',
'businessState' => 'VA',
'businessPostalCode' => '24060',
'businessCountry' => 'USA',
'homeStreet' => '456 Home St.',
'homeCity' => 'Charlotte',
'homeState' => 'NC',
'homePostalCode' => '28210',
'homeCountry' => 'USA',
'notes' => 'This is my note about my mailbox.',
'title' => 'My Title',
'userID' => 'J.Test',
'organizationalStatus' => 'OrgStatus',
'employeeType' => 'Full-Time'

}
</pre>

== Delete ==
''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/mailboxes/alex.smith', 'text/xml'
</pre>

Customer (Rest API)

2010-08-02T03:36:23Z

Zhen.wei: add create login token section

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

== Create Login Tokens ==

''URL'':

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

''Description'':

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

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

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

''Example'':

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

</pre>

Create login token for virtual user 'dev_cust_limitedadmin'.

<pre>

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

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

xmlns="urn:xml:loginToken">

<user>dev_cust_limitedadmin_460896_vu</user>

<token>EEB0012D8DBC2CAC26E28365D44B537FFF0D79350</token>

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

</loginToken>
</pre>

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

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

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

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

Domain (Rest API)

2010-07-30T21:44:36Z

Zhen.wei: add note to 'exchangeUsedStorage' and 'rsEmailUsedStorage'

__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]

''Note'':

These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.

''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>
<publicFoldersEnabled>false</publicFoldersEnabled>
<blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
<blackBerryLicenses>4</blackBerryLicenses>
<activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
<activeSyncLicenses>4</activeSyncLicenses>
</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,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":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 (deprecated)
| boolean
| Enable or disable domain Good Mobile service
|-
| goodMobileLicenses (deprecated)
| 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>

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

Rackspace Mailbox Spam (Rest API)

2010-07-30T16:29:21Z

Zhen.wei: fix RSMailboxSpamSetting.xsd link

__TOC__

== Spam Settings ==

=== Show ===

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

''Description'':

This operation returns the spam settings associated with the mailbox. For .xml format refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/RSMailboxSpamSetting.xsd RSMailboxSpamSetting.xsd]

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

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<rsMailboxSpamSetting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:RSMailboxSpamSetting">
<filterLevel>on</filterLevel>
<rsEmailSettings>
<spamHandling>toFolder</spamHandling>
<hasFolderCleaner>false</hasFolderCleaner>
<spamFolderAgeLimit>0</spamFolderAgeLimit>
<spamFolderNumLimit>0</spamFolderNumLimit>
<spamForwardingAddress />
</rsEmailSettings>
</rsMailboxSpamSetting>
</pre>

''Json Result Example'':

<pre>
{"filterLevel":"on","rsEmailSettings":"hasFolderCleaner":false,"spamFolderAgeLimit":0,"spamFolderNumLimit":0,
"spamForwardingAddress":"","spamHandling":"toFolder"}}
</pre>

=== Edit ===

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

''Description'':

This operation will modify the mailbox spam settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterLevel
| string
| This is a required field. Spam filter status: 'on', 'off', or 'exclusive'. Exclusive mode allows only email cleared by the Safelist.
|
|-
| rsEmail.spamHandling
| string
| The string 'toFolder' will deliver the email to the user's Spam folder, 'delete' will delete the mail immediately, 'labelSubject' will prepend [SPAM] to the email's subject line, and 'toAddress' will send the email to a specified folder instead.

Valid Field Combinations:

(toFolder => hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit)

(toAddress => spamForwardingAddress)
|-
| rsEmail.hasFolderCleaner
| string
| This field is effective when rsEmail.spamHandling option is set to 'toFolder'. This field controls how the spam that is delivered o the spam folder is handled. There are currently two options supported for handling spam. First option is to set a limit after which the spam gets deleted. One can set limit on the number of days or on the number of spam emails. Second option is to never automatically delete the spam. For both these options to be enabled the rsEmail.hasFolderCleaner field should be set to 'true'.
The folder cleaner fields (hasFolderCleaner, spamFolderAgeLimit, spamFolderNumLimit) are allowed
only when the spamHandling field is set to 'toFolder'. In order to never delete the spam set the spamFolderAgeLimit and spamFolderNumLimit fields to 0.
|-
| rsEmail.spamFolderAgeLimit
| string
| The number of days a message stays in the Spam folder before its deleted. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamFolderNumLimit
| string
| The maximum number of emails the Spam folder holds. This field is effective only when rsEmail.spamHandling is set to 'toFolder', and 'rs.hasFolderCleaner' is set to 'true'. This field cannot have negative value.
|-
| rsEmail.spamForwardingAddress
| string
| The email address that Spam emails will be redirected to. This field is required when the spamHandling field is set to 'toAddress'
|}

''Example'':
<pre>
put '/customers/100018/domains/resellerallservices.net/rs/mailboxes/unittestexist/spam/settings',
{
'filterLevel' => 'on',
'rsEmail.spamHandling' => 'toFolder',
'rsEmail.hasFolderCleaner' => 'true',
'rsEmail.spamFolderAgeLimit' => '7',
'rsEmail.spamFolderNumLimit' => '100',
}, Formats.xml
</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
|-
| Invalid input for form field 'spamHandling'
| 400
| Invalid RSEmail SpamHandling: Input must be: toFolder/delete/labelSubject/toAddress
|-
| Invalid email address in spam forwarding address
| 400
| Invalid email address
|-
| Empty forwarding address
| 400
| Spam Forwarding Address cannot be empty for spam handling policy: toAddress
|-
| Invalid value for field 'spamFolderAgeLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamFolderAgeLimit should be non-negative
|-
| Invalid value for field 'spamFolderNumLimit'
| 400
| Invalid RSEmail SpamCleanupOption: -1. rsEmail.spamNumberLimit should be non-negative.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: delete.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: labelSubject.
|-
| Invalid field combination
| 400
| Invalid field combination: Folder cleaner options cannot be specified with spam handling policy: toAddress.
|}

== Blacklist ==

=== Index ===

''URL'':
<nowiki>[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)</nowiki>

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/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)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/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/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(ip address)</nowiki>

''Description'':

Adds an IP to the ipsafelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/rs/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)
/rs/mailboxes/(mailbox name)/spam/ipsafelist/(email address)</nowiki>

''Description'':

Removes an IP from the safelist.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/rs/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-06-21T02:19:45Z

Zhen.wei: 06.20.2010 update

== Recent Changes ==

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

== 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_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_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 ====

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

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

BusinessDomain

2010-06-21T02:18:13Z

Zhen.wei:

__TOC__
[[ping()]] 
===Find out about a domain===
[[GetDomainStats()]] 
[[GetDomainUsers()]] 
[[GetDomainUsersString()]] 
[[GetDomainUsersSpamStatusString()]] 
[[GetDomainUsersSafeListStatusString()]] 
[[CheckUserExists()]] 
[[CheckAliasExists()]] 
[[CheckUserAvailable()]] 
[[GetDomainAllUserLastLogin()]] 
[[GetDomainAllUserStats()]] 
[[GetDomainAllUserStatsAlpha()]] 
[[GetDomainAllUserLastLoginActive()]] 
[[GetDomainAllUserStatsActive()]] 
[[GetDomainAllUsersForward()]] 

===General domain settings===
[[SetNobodyAlias()]] 
[[RemoveNobodyAlias()]] 
[[SetDomainNotify()]] 
[[GetDomainNotify()]] 
===Bulk operations===
[[SendMailDomainUsersAll()]] 
[[AddUsersBulk()]] 
[[ModifyUsersBulk()]] 
[[DeleteUsersBulk()]] 
[[SetUsersActiveBulk()]] 
[[GetUserAliasesBulk()]] 
[[AddUserAliasesBulk()]] 
[[DeleteUserAliasesBulk()]] 
===Mailbox size===
[[GetMailAllotStorage()]] 
[[GetDomainUsersMailboxMaxSize()]] 
[[SetDomainUsersMailboxMaxSize()]] 
[[GetDomainAllUserCurrentSizeActive()]] 
[[GetDomainAllUserCurrentSize()]] 

===Spam functions===
[[AddDomainSpam()]] 
[[DeleteDomainSpam()]] 
[[GetDomainSpam()]] 
[[SetDomainSpamCleaner()]] 
[[GetDomainSpamCleaner()]] 
[[SetDomainSpamSafeList()]] 
[[GetDomainSpamSafeList()]] 
[[SetDomainSpamBlackList()]] 
[[GetDomainSpamBlackList()]]

BusinessAll

2010-06-21T02:17:26Z

Zhen.wei:

[[AddAlias()]] 
[[AddDomainSpam()]] 
[[AddDomainSpamBlackList()]] 
[[AddDomainSpamIPBlackList()]] 
[[AddDomainSpamIPSafeList()]] 
[[AddDomainSpamSafeList()]] 
[[AddUser()]] 
[[AddUserAliasesBulk()]] 
[[AddUserSpam()]] 
[[AddUserSpamBlackList()]] 
[[AddUserSpamIPBlackList()]] 
[[AddUserSpamIPSafeList()]] 
[[AddUserSpamSafeList()]] 
[[AddUserWithLdapAttributes()]] 
[[AddUserWithLdapAttributesString()]] 
[[AddUsersBulk()]] 
[[CheckAliasExists()]] 
[[CheckUserAvailable()]] 
[[CheckUserExists()]] 
[[DeleteAlias()]] 
[[DeleteDomainSpam()]] 
[[DeleteUser()]] 
[[DeleteUserAliasesBulk()]] 
[[DeleteUserSpam()]] 
[[DeleteUsersBulk()]] 
[[GetAlias()]] 
[[GetDomainAllUserCurrentSize()]] 
[[GetDomainAllUserCurrentSizeActive()]] 
[[GetDomainAllUserLastLogin()]] 
[[GetDomainAllUserLastLoginActive()]] 
[[GetDomainAllUserStats()]] 
[[GetDomainAllUserStatsActive()]] 
[[GetDomainAllUserStatsAlpha()]] 
[[GetDomainAllUsersForward()]] 
[[GetDomainNotify()]] 
[[GetDomainSpam()]] 
[[GetDomainSpamBlackList()]] 
[[GetDomainSpamCleaner()]] 
[[GetDomainSpamSafeList()]] 
[[GetDomainStats()]] 
[[GetDomainUsers()]] 
[[GetDomainUsersMailboxMaxSize()]] 
[[GetDomainUsersSafeListStatusString()]] 
[[GetDomainUsersSpamStatusString()]] 
[[GetDomainUsersString()]] 
[[GetMailAllotStorage()]] 
[[GetUserActiveStatus()]] 
[[GetUserAliasesBulk()]] 
[[GetUserAliasesString()]] 
[[GetUserAttributes()]] 
[[GetUserLastLogin()]] 
[[GetUserMailForward()]] 
[[GetUserMailVacation()]] 
[[GetUserMailboxMaxSize()]] 
[[GetUserSpam()]] 
[[GetUserSpamBlackList()]] 
[[GetUserSpamCleaner()]] 
[[GetUserSpamSafeList()]] 
[[GetUsersWithFilterStr()]] 
[[ModifyAlias()]] 
[[ModifyUser()]] 
[[ModifyUserWithLdapAttributes()]] 
[[ModifyUserWithLdapAttributesString()]] 
[[ModifyUsersBulk()]] 
[[RemoveDomainSpamBlackList()]] 
[[RemoveDomainSpamIPBlackList()]] 
[[RemoveDomainSpamIPSafeList()]] 
[[RemoveDomainSpamSafeList()]] 
[[RemoveNobodyAlias()]] 
[[RemoveUserMailForward()]] 
[[RemoveUserSpamBlackList()]] 
[[RemoveUserSpamIPBlackList()]] 
[[RemoveUserSpamIPSafeList()]] 
[[RemoveUserSpamSafeList()]] 
[[SendMailDomainUsersAll()]] 
[[SetDomainNotify()]] 
[[SetDomainSpamBlackList()]] 
[[SetDomainSpamCleaner()]] 
[[SetDomainSpamSafeList()]] 
[[SetDomainUsersMailboxMaxSize()]] 
[[SetNobodyAlias()]] 
[[SetUserMailForward()]] 
[[SetUserMailVacation()]] 
[[SetUserMailboxMaxSize()]] 
[[SetUserSpamBlackList()]] 
[[SetUserSpamCleaner()]] 
[[SetUserSpamSafeList()]] 
[[SetUsersActiveBulk()]] 
[[ping()]] 

== Deprecated ==

[[GetDomainSpamGreylist()]] 
[[GetDomainAllUserCurrentSizeAlpha()]] 
[[GetDomainAllUserLastLoginAlpha()]] 
[[GetUserSpamGreylist()]] 
[[SetDomainSpamGreylist()]] 
[[SetUserSpamGreylist()]]

Domain administration

2010-06-21T02:16:54Z

Zhen.wei:

[[AddDomain()]] 
[[DeleteDomain()]] 
[[ModifyDomain()]] 
[[ModifyDomainAliases()]] 
[[ModifyDomainMaxMailboxSize()]] 
[[ModifyDomainMaxNumUsers()]] 
[[GetDomainSettings()]] 
[[GetDomainStats()]] 
[[GetDomainNumUsers()]] 
[[GetDomainNumUsersActive()]] 
[[GetAllDomains()]] 
[[GetAllDomainsStats()]] 
[[GetAllDomainsSettings()]] 
[[GetAllDomainsUserCount()]] 
[[SetNobodyAlias()]] 
[[RemoveNobodyAlias()]] 
[[GetDomainAllUserLastLogin()]] 
[[GetDomainAllUserCurrentSize()]] 
[[GetDomainAllUserStats()]] 
[[GetDomainAllUserLastLoginActive()]] 
[[GetDomainAllUserCurrentSizeActive()]] 
[[GetDomainAllUserStatsActive()]] 
[[GetDomainAllUserStatsActiveString()]] 
[[GetDomainAllUsersForward()]] 
[[SetDomainNotify()]] 
[[GetDomainNotify()]] 
[[SendMailDomainUsersAll()]] 
[[GetMailAllotStorage()]] 
[[GetDomainUsersMailboxMaxSize()]] 
[[SetDomainUsersMailboxMaxSize()]] 
[[AddMailAllotStorage()]] 
[[GetDomainAllUserStatsAlpha()]] 
[[SearchDomains()]] 
[[Subaccount_GetDomains()]] 
[[Subaccount_GetAdmins()]] 
[[Subaccount_AddAdmin()]] 
[[Subaccount_ChangeAdminPassword()]] 
[[Subaccount_ChangeAdminType()]] 
[[Subaccount_GetAdminType()]] 
[[Subaccount_DeleteAdmin()]] 
[[Subaccount_AddDomain()]] 
[[Subaccount_MoveDomain()]] 
[[Subaccount_DeleteDomain()]]

Rackspace Alias(Rest API)

2010-06-21T02:16:46Z

Zhen.wei: add rsemail alias page

__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'':

Create 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 on domain emails and 4 on 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'':

The show operation will return 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/RSAlias.xsd RSAlias.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.
|-
|}

Companies

2010-06-21T02:15:10Z

Zhen.wei: /* Function List */

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()]]

AllReseller

2010-06-21T02:14:24Z

Zhen.wei:

[[AddAlias()]] 
[[AddDomain()]] 
[[AddDomainSpam()]] 
[[AddDomainSpamBlackList()]] 
[[AddDomainSpamIPBlackList()]] 
[[AddDomainSpamIPSafeList()]] 
[[AddDomainSpamSafeList()]] 
[[AddMailAllotStorage()]] 
[[AddSubaccount()]] 
[[AddUser()]] 
[[AddUserAliasesBulk()]] 
[[AddUserSpam()]] 
[[AddUserSpamBlackList()]] 
[[AddUserSpamIPBlackList()]] 
[[AddUserSpamIPSafeList()]] 
[[AddUserSpamSafeList()]] 
[[AddUserWithLdapAttributes()]] 
[[AddUserWithLdapAttributesString()]] 
[[AddUsersBulk()]] 
[[CheckAliasExists()]] 
[[CheckUserAvailable()]] 
[[CheckUserExists()]] 
[[DeleteAlias()]] 
[[DeleteDomain()]] 
[[DeleteDomainSpam()]] 
[[DeleteSubaccount()]] 
[[DeleteUser()]] 
[[DeleteUserAliasesBulk()]] 
[[DeleteUserSpam()]] 
[[DeleteUsersBulk()]] 
[[GetAlias()]] 
[[GetAllDomains()]] 
[[GetAllDomainsSettings()]] 
[[GetAllDomainsStats()]] 
[[GetAllDomainsUserCount()]] 
[[GetCurrentUserMailboxSize()]] 
[[GetDomainAllUserCurrentSize()]] 
[[GetDomainAllUserCurrentSizeActive()]] 
[[GetDomainAllUserLastLogin()]] 
[[GetDomainAllUserLastLoginActive()]] 
[[GetDomainAllUserStats()]] 
[[GetDomainAllUserStatsActive()]] 
[[GetDomainAllUserStatsActiveString()]] 
[[GetDomainAllUserStatsAlpha()]] 
[[GetDomainAllUsersForward()]] 
[[GetDomainNotify()]] 
[[GetDomainNumBcc()]] 
[[GetDomainNumUsers()]] 
[[GetDomainNumUsersActive()]] 
[[GetDomainSettings()]] 
[[GetDomainSpam()]] 
[[GetDomainSpamBlackList()]] 
[[GetDomainSpamCleaner()]] 
[[GetDomainSpamSafeList()]] 
[[GetDomainStats()]] 
[[GetDomainUsers()]] 
[[GetDomainUsersBlackListStatusString()]] 
[[GetDomainUsersMailboxMaxSize()]] 
[[GetDomainUsersSafeListStatusString()]] 
[[GetDomainUsersSpamStatusString()]] 
[[GetDomainUsersString()]] 
[[GetDomainUsersStringAlpha()]] 
[[GetMailAllotStorage()]] 
[[GetRetCodeDesc()]] 
[[GetSubaccounts()]] 
[[GetUserActiveStatus()]] 
[[GetUserAliasesBulk()]] 
[[GetUserAliasesString()]] 
[[GetUserAttributes()]] 
[[GetUserLastLogin()]] 
[[GetUserMailForward()]] 
[[GetUserMailVacation()]] 
[[GetUserMailboxMaxSize()]] 
[[GetUserNumMessages()]] 
[[GetUserSpam()]] 
[[GetUserSpamBlackList()]] 
[[GetUserSpamCleaner()]] 
[[GetUserSpamSafeList()]] 
[[GetUserStatus()]] 
[[GetUsersWithFilterStr()]] 
[[LoginUserWebmail()]] 
[[ModifyAlias()]] 
[[ModifyDomain()]] 
[[ModifyDomainAliases()]] 
[[ModifyDomainMaxMailboxSize()]] 
[[ModifyDomainMaxNumUsers()]] 
[[ModifySubaccount()]] 
[[ModifyUser()]] 
[[ModifyUserWithLdapAttributes()]] 
[[ModifyUserWithLdapAttributesString()]] 
[[ModifyUsersBulk()]] 
[[RemoveDomainSpamBlackList()]] 
[[RemoveDomainSpamIPBlackList()]] 
[[RemoveDomainSpamIPSafeList()]] 
[[RemoveDomainSpamSafeList()]] 
[[RemoveNobodyAlias()]] 
[[RemoveUserMailForward()]] 
[[RemoveUserSpamBlackList()]] 
[[RemoveUserSpamIPBlackList()]] 
[[RemoveUserSpamIPSafeList()]] 
[[RemoveUserSpamSafeList()]] 
[[SearchDomains()]] 
[[SearchSubaccounts()]] 
[[SendMailDomainUsersAll()]] 
[[SetDomainNotify()]] 
[[SetDomainSpamBlackList()]] 
[[SetDomainSpamCleaner()]] 
[[SetDomainSpamSafeList()]] 
[[SetDomainUsersMailboxMaxSize()]] 
[[SetNobodyAlias()]] 
[[SetUserMailForward()]] 
[[SetUserMailVacation()]] 
[[SetUserMailboxMaxSize()]] 
[[SetUserSpamBlackList()]] 
[[SetUserSpamCleaner()]] 
[[SetUserSpamSafeList()]] 
[[SetUsersActiveBulk()]] 
[[Subaccount_AddAdmin()]] 
[[Subaccount_AddDomain()]] 
[[Subaccount_ChangeAdminPassword()]] 
[[Subaccount_ChangeAdminType()]] 
[[Subaccount_DeleteAdmin()]] 
[[Subaccount_DeleteDomain()]] 
[[Subaccount_GetAdminType()]] 
[[Subaccount_GetAdmins()]] 
[[Subaccount_GetAllocatedStorage()]] 
[[Subaccount_GetDomains()]] 
[[Subaccount_GetLimitedAdminPermissions()]] 
[[Subaccount_GetNumBcc()]] 
[[Subaccount_GetNumDomains()]] 
[[Subaccount_GetNumMailboxes()]] 
[[Subaccount_MoveDomain()]] 
[[Subaccount_SetLimitedAdminPermissions()]] 
[[ping()]] 

== Deprecated ==

[[GetAllDomainsMXRecords()]] 
[[GetDomainAllUserCurrentSizeAlpha()]] 
[[GetDomainAllUserLastLoginAlpha()]] 
[[GetDomainSpamGreylist()]] 
[[GetEMSubscriberLimit()]] 
[[GetUserSpamGreylist()]] 
[[SetDomainSpamGreylist()]] 
[[SetUserSpamGreylist()]]