Rackspace Email & Apps API - User contributions [en]

Admin (Rest API)

2018-08-20T21:48:08Z

Appscp: /* v2 - Coming Soon */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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>
<firstName>John</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>john.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>jane.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<firstName>Test</firstName>
<lastName>User</lastName>
<type>super</type>
<email>test.user@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>false</twoFactorEnabled>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{
"admins":[
{
"adminId":"apiadmin37",
"firstName": "John",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"john.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin76",
"firstName": "Jane",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"jane.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin94",
"firstName": "Test",
"lastName": "User",
"enabled":true,
"locked":false,
"type":"super",
"email":"test.user@example.com",
"twoFactorEnabled":false
}
],
"offset":0,
"size":50,
"total":3
}
</pre>

=== Show ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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'
}
</pre>

<pre>
put '/customers/999999/admins/admin2',
{
'enabled' => 'true',
'locked' => 'false',
'passwordExpiration' => '0',
'allowSimultaneousLogins' => 'true',
'restrictedIps' => '1.1.1.1'
}
</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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Current ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Admin (Rest API)

2018-08-20T21:46:58Z

Appscp: /* Delete */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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>
<firstName>John</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>john.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>jane.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<firstName>Test</firstName>
<lastName>User</lastName>
<type>super</type>
<email>test.user@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>false</twoFactorEnabled>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{
"admins":[
{
"adminId":"apiadmin37",
"firstName": "John",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"john.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin76",
"firstName": "Jane",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"jane.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin94",
"firstName": "Test",
"lastName": "User",
"enabled":true,
"locked":false,
"type":"super",
"email":"test.user@example.com",
"twoFactorEnabled":false
}
],
"offset":0,
"size":50,
"total":3
}
</pre>

=== Show ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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'
}
</pre>

<pre>
put '/customers/999999/admins/admin2',
{
'enabled' => 'true',
'locked' => 'false',
'passwordExpiration' => '0',
'allowSimultaneousLogins' => 'true',
'restrictedIps' => '1.1.1.1'
}
</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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Coming Soon ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Admin (Rest API)

2018-08-20T21:45:56Z

Appscp: /* Add/Edit */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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>
<firstName>John</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>john.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>jane.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<firstName>Test</firstName>
<lastName>User</lastName>
<type>super</type>
<email>test.user@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>false</twoFactorEnabled>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{
"admins":[
{
"adminId":"apiadmin37",
"firstName": "John",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"john.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin76",
"firstName": "Jane",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"jane.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin94",
"firstName": "Test",
"lastName": "User",
"enabled":true,
"locked":false,
"type":"super",
"email":"test.user@example.com",
"twoFactorEnabled":false
}
],
"offset":0,
"size":50,
"total":3
}
</pre>

=== Show ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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'
}
</pre>

<pre>
put '/customers/999999/admins/admin2',
{
'enabled' => 'true',
'locked' => 'false',
'passwordExpiration' => '0',
'allowSimultaneousLogins' => 'true',
'restrictedIps' => '1.1.1.1'
}
</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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Coming Soon ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Admin (Rest API)

2018-08-20T21:45:36Z

Appscp: /* Show */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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>
<firstName>John</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>john.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>jane.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<firstName>Test</firstName>
<lastName>User</lastName>
<type>super</type>
<email>test.user@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>false</twoFactorEnabled>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{
"admins":[
{
"adminId":"apiadmin37",
"firstName": "John",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"john.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin76",
"firstName": "Jane",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"jane.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin94",
"firstName": "Test",
"lastName": "User",
"enabled":true,
"locked":false,
"type":"super",
"email":"test.user@example.com",
"twoFactorEnabled":false
}
],
"offset":0,
"size":50,
"total":3
}
</pre>

=== Show ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Coming Soon ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Admin (Rest API)

2018-08-20T21:45:07Z

Appscp: /* Index */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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>
<firstName>John</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>john.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>jane.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<firstName>Test</firstName>
<lastName>User</lastName>
<type>super</type>
<email>test.user@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>false</twoFactorEnabled>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{
"admins":[
{
"adminId":"apiadmin37",
"firstName": "John",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"john.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin76",
"firstName": "Jane",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"jane.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin94",
"firstName": "Test",
"lastName": "User",
"enabled":true,
"locked":false,
"type":"super",
"email":"test.user@example.com",
"twoFactorEnabled":false
}
],
"offset":0,
"size":50,
"total":3
}
</pre>

=== Show ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Coming Soon ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Admin (Rest API)

2018-08-20T21:43:53Z

Appscp: Reverted edits by Appscp (talk) to last revision by Zach7981

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/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/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Coming Soon ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Admin (Rest API)

2018-08-20T21:42:08Z

Appscp: /* Delete */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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>
<firstName>John</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>john.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin76</adminId>
<firstName>Jane</firstName>
<lastName>Doe</lastName>
<type>super</type>
<email>jane.doe@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>true</twoFactorEnabled>
</admin>
<admin>
<adminId>apiadmin94</adminId>
<firstName>Test</firstName>
<lastName>User</lastName>
<type>super</type>
<email>test.user@example.com</email>
<enabled>true</enabled>
<locked>false</locked>
<twoFactorEnabled>false</twoFactorEnabled>
</admin>
</admins>
</adminList>
</pre>

''Json Result Example'':

<pre>
{
"admins":[
{
"adminId":"apiadmin37",
"firstName": "John",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"john.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin76",
"firstName": "Jane",
"lastName": "Doe",
"enabled":true,
"locked":false,
"type":"super",
"email":"jane.doe@example.com",
"twoFactorEnabled":true
},
{
"adminId":"apiadmin94",
"firstName": "Test",
"lastName": "User",
"enabled":true,
"locked":false,
"type":"super",
"email":"test.user@example.com",
"twoFactorEnabled":false
}
],
"offset":0,
"size":50,
"total":3
}
</pre>

=== Show ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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'
}
</pre>

<pre>
put '/customers/999999/admins/admin2',
{
'enabled' => 'true',
'locked' => 'false',
'passwordExpiration' => '0',
'allowSimultaneousLogins' => 'true',
'restrictedIps' => '1.1.1.1'
}
</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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Current ==



== v2 - Current ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Admin (Rest API)

2018-08-20T21:41:09Z

Appscp: /* Add/Edit */

Admin (Rest API)

2018-08-20T21:39:07Z

Appscp: /* Index */

Main Page

2018-06-13T13:58:44Z

Appscp: /* Accessing the API */

== Introduction ==

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

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

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

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

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

== Operations ==

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

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

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

== Quick Start ==

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

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

== Accessing the API ==

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

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

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

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

=== Versions ===

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

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

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

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

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

=== Authentication ===

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

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

An unsuccessful authentication will result in a 403 HTTP code.

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

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

Remember to include the colons between the data strings!

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

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

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

'''SHA1 Hash''':

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

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

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

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

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

== Using the API ==

=== Requests ===

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

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

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

==== URL ====

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

==== HTTP Method ====

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

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

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

==== HTTP Headers ====

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

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

==== Form Data ====

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

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

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

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

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

==== Throttling ====

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

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

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

==== Examples ====

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

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

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

</pre>

=== Responses ===

==== HTTP Status Code ====

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

==== HTTP Response Body ====

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

===== Formats =====

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

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

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

==== HTTP Headers ====

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

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

==== Errors ====

See [[Errors]].

==== Paging ====

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

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

===== Example =====

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

==== Examples ====

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

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

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

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

== Examples ==

=== Ruby ===

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

<pre>
require 'server.rb'

server = Server.new

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

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

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

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

class Server
include Test::Unit::Assertions

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

# Response Type Enums

def xml_format
'text/xml'
end

def json_format
'application/json'
end

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

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

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

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

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

response
end

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

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

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

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

data_to_sign = apiKey + userAgent + timestamp + secretKey

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

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

=== C# ===

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

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

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

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

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

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

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

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

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

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

}

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

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

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

=== PHP ===

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

Main Page

2018-06-13T13:57:39Z

Appscp: /* Quick Start */

== Introduction ==

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

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

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

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

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

== Operations ==

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

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

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

== Quick Start ==

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

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

== Accessing the API ==

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

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

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

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

=== Versions ===

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

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

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

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

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

=== Authentication ===

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

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

An unsuccessful authentication will result in a 403 HTTP code.

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

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

Remember to include the colons between the data strings!

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

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

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

'''SHA1 Hash''':

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

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

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

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

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

== Using the API ==

=== Requests ===

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

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

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

==== URL ====

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

==== HTTP Method ====

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

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

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

==== HTTP Headers ====

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

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

==== Form Data ====

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

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

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

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

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

==== Throttling ====

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

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

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

==== Examples ====

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

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

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

</pre>

=== Responses ===

==== HTTP Status Code ====

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

==== HTTP Response Body ====

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

===== Formats =====

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

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

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

==== HTTP Headers ====

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

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

==== Errors ====

See [[Errors]].

==== Paging ====

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

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

===== Example =====

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

==== Examples ====

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

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

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

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

== Examples ==

=== Ruby ===

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

<pre>
require 'server.rb'

server = Server.new

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

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

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

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

class Server
include Test::Unit::Assertions

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

# Response Type Enums

def xml_format
'text/xml'
end

def json_format
'application/json'
end

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

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

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

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

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

response
end

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

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

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

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

data_to_sign = apiKey + userAgent + timestamp + secretKey

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

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

=== C# ===

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

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

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

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

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

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

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

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

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

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

}

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

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

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

=== PHP ===

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

SharePoint (Rest API)

2017-09-15T20:12:49Z

Appscp:

__TOC__

== v1 - Current ==

=== Settings ===

==== Show ====

''URL'':

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

''Description'':

Returns the status and quota size of the SharePoint service.

''Example'':

<pre>
get '/customers/999999/sharepoint/settings'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<SharePointSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:SharePointSettings">
<enabled>true</enabled>
<size>0.25</size>
</SharePointSettings>
</pre>

''Json Result Example'':
<pre>
{"enabled":true,"size":0.25}
</pre>

==== Edit (Reseller Only) ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/sharepoint/settings</nowiki>

''Description'':

This operation will modify SharePoint's settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| enabled
| boolean
| Whether SharePoint is enabled or not. By enabling SharePoint you and/or your customers are agreeing to Rackspace's [http://www.rackspace.com/information/legal/sharepointappterms.php SharePoint Services Terms and Conditions].
|-
| size
| double
| SharePoint's storage size in GB. Valid values are .25 and any integer between 1 and 50 inclusive. This field will be ignored when SharePoint is disabled. (default value is 0.25GB)
|}

''Example'':
<pre>
put '/customers/123456/sharepoint/settings',
{
'enabled' => 'true',
'size' => '10.0'
}
</pre>

Domain (Rest API)

2017-04-05T18:31:11Z

Appscp: /* Add/Edit (Reseller Only) */ document rsEmailProduct field

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/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. <nowiki>'https://api.emailsrvr.com/v1/customers/all/domains'</nowiki>.
*To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. <nowiki>'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains'</nowiki>.
*Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me
<nowiki>'https://api.emailsrvr.com/v1/domains'</nowiki>.

*The index operation only supports the GET HTTP verb.

''Example'':

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

''domainNames Parameter '''(V1 only)''''':
The optional query string parameter "domainNames" can be used to retrieve a specific subset of domains by hostname. Up to 100 hostnames can be given at once in a comma-delimited list.
<pre>
get '/customers/all/domains?domainNames=apidomain53.com,apidomain66.com,apidomain68.com', 'application/json'
</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>
<exchangeMaxNumMailboxes>10</exchangeMaxNumMailboxes>
<exchangeUsedStorage>4</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>10</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>9</rsEmailUsedStorage>
</domain>
<domain>
<name>apidomain66.com</name>
<accountNumber>100001</accountNumber>
<serviceType>rsemail</serviceType>
<exchangeMaxNumMailboxes>0</exchangeMaxNumMailboxes>
<exchangeUsedStorage>0</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>100</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>40</rsEmailUsedStorage>
</domain>
<domain>
<name>apidomain68.com</name>
<accountNumber>100002</accountNumber>
<serviceType>exchange</serviceType>
<exchangeMaxNumMailboxes>50</exchangeMaxNumMailboxes>
<exchangeUsedStorage>10</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>0</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>0</rsEmailUsedStorage>
</domain>
</domains>
</domainList>
</pre>

''Json Result Example'':

<pre>
{"offset":0,"size":50,"total":3,"domains":
[{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both","exchangeMaxNumMailboxes":"10","exchangeUsedStorage":"4","rsEmailMaxNumberMailboxes":"10","rsEmailUsedStorage":"9"},
{"name":"apidomain66.com","accountNumber":"100001","serviceType":"rsemail","exchangeMaxNumMailboxes":"0","exchangeUsedStorage":"0","rsEmailMaxNumberMailboxes":"100","rsEmailUsedStorage":"40"},
{"name":"apidomain68.com","accountNumber":"100002","serviceType":"exchange","exchangeMaxNumMailboxes":"50","exchangeUsedStorage":"10","rsEmailMaxNumberMailboxes":"0","rsEmailUsedStorage":"0"}]}
</pre>

=== Export ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains?exportTo={email address}</nowiki>

''Description'':

Use this route to export a file that includes details for domains on an account.

''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/v1/customers/me/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number. <nowiki>'https://api.emailsrvr.com/v1/customers/all/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. <nowiki>'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me
<nowiki>'https://api.emailsrvr.com/v1/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*The export route supports 'contains' and 'startswith' filtering

=== Show ===

''URL'':

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

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

''Example'':

<pre>
get '/customers/999999/domains/example.com'
</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/v1/customers/(customer account number)/domains/(domain name)
Edit: [PUT] https://api.emailsrvr.com/v1/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
|-
| rsEmailProduct
| string
| Rackspace Email product type. "rse-basic" = "Basic (Email)". "rse-plus" = "Plus (Email, Mobile Sync, Drive, and Docs)"
|-
| 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',
{
'maxNumMailboxes' => '5',
'extraStorage' => '1024'
}
</pre>

<pre>
put '/customers/123455/domains/newcompany.com',
{
'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
|}

''Notes'':

When setting <code>rsEmailProduct</code>, there is a short delay before the change is reflected, while the upgrade (or downgrade) process is happening.

=== Move (Reseller Only)===

''URL'':

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

''Description'':

Moves a domain among your account and subaccounts.

{| 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',
{
'moveDomain' => 'true'
}
</pre>

=== Transfer ===

Transfers ownership of a domain to another customer. You can start, read, and cancel the transfer. The other customer can finish the transfer.

==== Start ====

''URL'':

<pre>
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/transfer
</pre>

''Description'':

Creates a transfer, which is represented by a token. A transfer also has an expiration, which is represented by an RFC 3339 formatted timestamp. After the expiration, the transfer is automatically canceled.

''Example'':

<pre>
post'/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The domain does not exist or is not accessible by the admin
| 404
| example.com not found
|}

==== Read ====

''URL'':

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

''Description'':

Retrieves the domain transfer information for the domain that was returned by the request to start the transfer.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| No transfer has been started, or the transfer has expired
| 404
| Domain transfer offer not found.
|}

==== Cancel ====

''URL'':

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

''Description'':

Cancels a domain transfer.

''Example'':

<pre>
delete '/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

==== Finish ====

''URL'':

<pre>
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/transfer/finish
</pre>

''Description'':

Finish a domain transfer. This API request must be made by an admin that is on the account that will accept the domain. When the request completes successfully, assigns ownership of the domain to the company of the authenticated admin. That company will have full control of the domain, and accepts billing for services associated with the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| token
| string
| the token returned by the POST or GET to this resource by an admin with access to the domain
|}

''Example'':

<pre>
post '/customers/12345678/domains/company.com/transfers/finish', 'application/json',
{
'Token' => 'b77b8460-5019-48e0-a5eb-4951640ea3cd'
}
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>
''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The domain does not exist or is not accessible by the admin
| 404
| example.com not found
|-
| The transfer token is invalid
| 404
| example.com not found
|}

=== Delete (Reseller Only)===

''URL'':

<nowiki>[DELETE] https://api.emailsrvr.com/v1/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'
</pre>

=== Alternate Domains ===

==== Index (Reseller Only) ====

''URL'':

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

''Example'':

<pre>
get '/customers/12345678/domains/test.com/alternatedomains'
</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/v1/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',
{
'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/v1/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/v1/customers/(customer account number)/domains/(domain)/splitdomainrouting</nowiki>

''Description'':
Shows the current external email server.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/splitdomainrouting'
</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/v1/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',
{
'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/v1/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'
</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/v1/customers/(customer account number)/domains/(domain name)/ex/publicfolders
</nowiki>

''Description'':

Retrieves the Exchange Public Folders status for the domain.
''Example'':

<pre>
get '/customers/12345678/domains/company.com/ex/publicFolders'
</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/v1/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',
{
'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/v1/customers/(customer account number)/domains/(domain name)/emaileveryone
[POST] https://api.emailsrvr.com/v1/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',
{
'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/v1/customers/(customer account number)/domains/(domain name)/catchalladdress</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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'
</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/v1/customers/(customer account number)/domains/(domain name)/catchalladdress</nowiki>
<nowiki>[PUT] https://api.emailsrvr.com/v1/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',
{
'address' => 'abc@example.com'
}
</pre>

Rackspace Mailbox (Rest API)

2017-01-24T16:38:53Z

Appscp: /* Add/Edit */ document displayName field

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

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

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

''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', 'enabled', 'createdDate', and 'lastLogin'

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

=== Show ===

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith'
</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>
<customID>0123456789</customID>
<organizationalStatus>OrgStatus</organizationalStatus>
<employeeType>Full-Time</employeeType>
</contactInfo>
<enabled>true</enabled>
</rsMailbox>
</pre>

''Json Result Example'':

<pre>
{
"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",
"customID": "0123456789"
},
"name": "unittestexist",
"saveForwardedEmail": false,
"size": 10240,
"vacationMessage": "Test Vacation Message",
"createdDate": "4\/10\/2006 7:47:34 PM",
"currentUsage": 1024,
"visibleInExchangeGAL": false,
"visibleInRackspaceEmailCompanyDirectory": false
}
</pre>

==== Recoverable Mailboxes ====

If the mailbox does not exist, the API will return the regular <tt>[[Errors#404_Not_Found|itemNotFound]]</tt> data. In addition, it will also return a boolean value <tt>isRecoverable</tt> which is set to <tt>true</tt> if the mailbox is recoverable. If <tt>isRecoverable</tt> is <tt>true</tt>, <tt>deletedDate</tt> will also be set, otherwise <tt>deletedDate</tt> will not be included.

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<itemNotFoundFault
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://api.emailsrvr.com/v0/Schemas"
code="404">
<additionalData>
<isRecoverable>
<boolean>true</boolean>
</isRecoverable>
<deletedDate>
<dateTime>2015-01-10T21:59:55.5645572Z</dateTime>
</deletedDate>
</additionalData>
<message>Entity of type Mailbox identified by some.deleted.mailbox@example.comwas not found</message>
<details>1/12/2015 4:59:55 PM</details>
<resourceType>Mailbox</resourceType>
</itemNotFoundFault>
</pre>

''Json Result Example'':

<pre>
{
"itemNotFoundFault": {
"resourceType": "Mailbox",
"additionalData": {
"isRecoverable": true,
"deletedDate": "2015-01-10T21:50:26.9430015Z"
},
"message": "Entity of type Mailbox identified by some.deleted.mailbox@example.com was not found",
"details": "1/12/2015 4:50:26 PM",
"code": 404
}
}
</pre>

=== Add/Edit ===

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)
Edit: [PUT] https://api.emailsrvr.com/v1/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)
|-
| recoverDeleted
| boolean
| If set to true, any retained messages will be recovered. See [[#Recoverable_Mailboxes|Recoverable Mailboxes]].
|-
| 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
|-
| displayName
| string
| Display name
|-
| 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
|-
| customID
| string
| A custom field that can be used to tie user mailboxes to external user systems
|-
| 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',
{
'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',
'customID' => '0123456789',
'organizationalStatus' => 'OrgStatus',
'employeeType' => 'Full-Time'
'visibleInExchangeGAL'=>'true',
'visibleInRackspaceEmailCompanyDirectory' => 'false'

}
</pre>

==== Rename ====

To rename a mailbox, include the ''name'' form key in the put request. If the call is successful, the old email address will be created as an alias to ensure email is still received when sent to the old email address.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith',
{
'name' => 'alex.renamed'
}
</pre>

=== Delete ===
''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/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'
</pre>

=== Create Login Tokens ===

''URL'':

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

''Description'':

Generate a login Token which can be used to log in to a user's mailbox. The POST will return a loginToken, created date, and expiration date.

''Note:''

This route is not available to customers who access the Cloud Office Control Panel via my.rackspace.com and have an admin account with API keys.

''Example'':

<pre>
post '/customers/460896/domains/testapidomain.net/rs/mailboxes/testmailbox/loginToken', {}

</pre>

Create a login Token for testmailbox@testapidomain.net

<pre>

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

<rsMailboxLoginToken xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailboxLoginToken">

<token>5b5e27419a363fc5b65bbb63d1c2d3f8</token>

<dateCreated>9/22/2010 9:33:15 AM</dateCreated>

<expirationDate>9/22/2010 9:53:14 AM</expirationDate>

</rsMailboxLoginToken>

</pre>

The login token is valid until the current time (EST) passes the expiration date, and can be used until that point.

Using the above created login token a user can SSO into testmailbox@testapidomain.net using the following URL:

<pre>
https://{webmail address}/mail/src/redirect.php?user_name={testmailbox@testapidomain.net}&emailaddress=testmailbox@testapidomain.net&sessionID=5b5e27419a363fc5b65bbb63d1c2d3f8
</pre>

Alternatively, the login token can be used to SSO into the webmail mobile site using the following URL:

<pre>
https://{webmail address}/mobile/login.php?user_name=address@domain.com&emailaddress=address@domain.com&sessionID=5b5e27419a363fc5b65bbb63d1c2d3f8
</pre>

Resource Mailbox (Rest API)

2017-01-12T21:51:52Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

=== Index ===

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

''Description'':

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

''Remarks'':

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/resources?size=100&page=1&contains=conference'
</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'
</pre>

''XML Result Example''

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

''Json Result Example'':

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

''Errors'':

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

=== Add/Edit ===

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

''Description'':

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

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

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

<pre>
put '/customers/12345678/domains/example.com/ex/resources/all.employees',
{
'displayName' => 'Conference Room A'
'password' => 'ABCd4321'
}
</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'
</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'
</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', {}
</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'
</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.
|}

Customer (Rest API)

2017-01-12T21:50:49Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index (Reseller Only) ===

''URL'':

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

''Description'':

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

''Filter/Search'':

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

''Example'':

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

''XML Result Example'':

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

''JSON Result Example'':

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

=== Show (Reseller Only) ===

''URL'':

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

''Description'':

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

''Remarks'':

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

The show operation only supports the GET HTTP verb.

''Reference Number''

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

''Examples'':

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

''XML Result Example'':

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

''JSON Result Example'':

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

''Example of querying with Reference Number''

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

''XML Result Example'':

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

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

''URL'':

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

''Description'':

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

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

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

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

''Example'':

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

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

''Errors'':

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

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

''URL'':

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

''Description'':

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

''Example'':

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

''Errors'':

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

=== Delete (Reseller Only) ===

''URL'':

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

''Description'':

Deletes the account.

''Example'':

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

=== Create Login Tokens ===

''URL'':

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

''Description'':

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

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

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

''Example'':

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

</pre>

Create login token for virtual user 'dev_cust_limitedadmin'.

<pre>

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

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

xmlns="urn:xml:loginToken">

<user>dev_cust_limitedadmin_460896_vu</user>

<token>EEB0012D8DBC2CAC26E28365D44B537FFF0D79350</token>

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

</loginToken>
</pre>

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

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

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

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

== v2 - Current ==

=== Company contacts ===

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

==== View contacts ====

''Description'':

View all contacts for an account.

''Request'':

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

''Response'':

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

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

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

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

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

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

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

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

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

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

''Description'':

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

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

''Request'':

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

''Response'':

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

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

''Description'':

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

''Request'':

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

''Response'':

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

==== Add a contact ====

''Description'':

Create a new contact.

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

''Request'':

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

==== Update a contact ====

''Description'':

Update information for the contact you specify.

''Request'':

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

''Response'':

<pre>
200 OK
</pre>

==== Delete a contact ====

''Description'':

Remove a contact from the account.

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

''Request'':

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

''Response'':

<pre>
200 OK
</pre>

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

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

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

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

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

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

Admin (Rest API)

2017-01-12T21:49:49Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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'
}
</pre>

<pre>
put '/customers/999999/admins/admin2',
{
'enabled' => 'true',
'locked' => 'false',
'passwordExpiration' => '0',
'allowSimultaneousLogins' => 'true',
'restrictedIps' => '1.1.1.1'
}
</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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Current ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

SharePoint (Rest API)

2017-01-12T21:49:16Z

Appscp: remove accept header from examples to avoid confusion

Exchange Contact (Rest API)

2017-01-12T21:48:31Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index ===

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

''Description'':

Returns a list of contacts under the domain.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts?contains=john'
</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/v1/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)</nowiki>

''Description'':

Returns the contact's details.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts/alex.smith'
</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/v1/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)

Edit: [PUT] https://api.emailsrvr.com/v1/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',
{
'displayName' => 'Johnny Customer',
'externalEmail' => 'jonny@apple.com'
}
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/contacts/alex.smith',
{
'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/v1/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'
</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
|}

Exchange Mailbox Spam (Rest API)

2017-01-12T21:47:55Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings'
</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/v1/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',
{
'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/v1/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.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist'
</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/v1/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', {}
</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/v1/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'
</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/v1/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'
}
</pre>

=== IP Blacklist ===

==== Index ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist'
</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/v1/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', {}
</pre>

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/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'
</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/v1/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.%.%.%'
}
</pre>

=== Safelist ===

==== Index ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist'
</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/v1/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', {}
</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/v1/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'
</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/v1/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'
}
</pre>

=== IP Safelist ===

==== Index ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipsafelist'
</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/v1/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', {}
</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/v1/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'
</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/v1/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.%.%.%'
}
</pre>

Rackspace Alias(Rest API)

2017-01-12T21:46:50Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/aliases'
</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/v1/customers/(customer account number)/domains/(domain name)
/rs/aliases/(alias name)</nowiki>

''Description'':

Creates an alias.

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

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

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

''Errors'':

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

=== Show ===

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

''Description'':

Returns detailed information about the specified alias.

''Remarks'':

The show operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/100018/domains/resellerallservices.net/rs/aliases/alias1'
</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/v1/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'
</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/v1/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', {}

</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/v1/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', {}
</pre>

''Errors'':

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

=== Bulk Modify Alias List ===

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

''Description'':

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

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

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

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

''Form Fields:''

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

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

''Errors'':

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

Rackspace Storage Notification (Rest API)

2017-01-12T21:45:07Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Show ===

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/storageNotification'
</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/v1/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',
{
'enabled' => 'true',
'notificationPercentage' => '90',
'notificationMessage' => 'Your mailbox "<*USER*>@<*DOMAIN*>" is almost full.',
'notificationCC' => 'test@testdomain.com'
}
</pre>

Rackspace Mailbox Spam (Rest API)

2017-01-12T21:44:26Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/settings'
</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/v1/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/v1/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.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/blacklist'
</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/v1/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', {}
</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/v1/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'
</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/v1/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'
}
</pre>

=== IP Blacklist ===

==== Index ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipblacklist'
</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/v1/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', {}
</pre>

==== Delete ====

''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/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'
</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/v1/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.%.%.%'
}
</pre>

=== Safelist ===

==== Index ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/safelist'
</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/v1/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', {}
</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/v1/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'
</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/v1/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'
}
</pre>

=== IP Safelist ===

==== Index ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith/spam/ipsafelist'
</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/v1/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', {}
</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/v1/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'
</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/v1/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.%.%.%'
}
</pre>

Rackspace Mailbox (Rest API)

2017-01-12T21:42:40Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

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

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

''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', 'enabled', 'createdDate', and 'lastLogin'

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

=== Show ===

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith'
</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>
<customID>0123456789</customID>
<organizationalStatus>OrgStatus</organizationalStatus>
<employeeType>Full-Time</employeeType>
</contactInfo>
<enabled>true</enabled>
</rsMailbox>
</pre>

''Json Result Example'':

<pre>
{
"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",
"customID": "0123456789"
},
"name": "unittestexist",
"saveForwardedEmail": false,
"size": 10240,
"vacationMessage": "Test Vacation Message",
"createdDate": "4\/10\/2006 7:47:34 PM",
"currentUsage": 1024,
"visibleInExchangeGAL": false,
"visibleInRackspaceEmailCompanyDirectory": false
}
</pre>

==== Recoverable Mailboxes ====

If the mailbox does not exist, the API will return the regular <tt>[[Errors#404_Not_Found|itemNotFound]]</tt> data. In addition, it will also return a boolean value <tt>isRecoverable</tt> which is set to <tt>true</tt> if the mailbox is recoverable. If <tt>isRecoverable</tt> is <tt>true</tt>, <tt>deletedDate</tt> will also be set, otherwise <tt>deletedDate</tt> will not be included.

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<itemNotFoundFault
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://api.emailsrvr.com/v0/Schemas"
code="404">
<additionalData>
<isRecoverable>
<boolean>true</boolean>
</isRecoverable>
<deletedDate>
<dateTime>2015-01-10T21:59:55.5645572Z</dateTime>
</deletedDate>
</additionalData>
<message>Entity of type Mailbox identified by some.deleted.mailbox@example.comwas not found</message>
<details>1/12/2015 4:59:55 PM</details>
<resourceType>Mailbox</resourceType>
</itemNotFoundFault>
</pre>

''Json Result Example'':

<pre>
{
"itemNotFoundFault": {
"resourceType": "Mailbox",
"additionalData": {
"isRecoverable": true,
"deletedDate": "2015-01-10T21:50:26.9430015Z"
},
"message": "Entity of type Mailbox identified by some.deleted.mailbox@example.com was not found",
"details": "1/12/2015 4:50:26 PM",
"code": 404
}
}
</pre>

=== Add/Edit ===

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)
Edit: [PUT] https://api.emailsrvr.com/v1/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)
|-
| recoverDeleted
| boolean
| If set to true, any retained messages will be recovered. See [[#Recoverable_Mailboxes|Recoverable Mailboxes]].
|-
| 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
|-
| customID
| string
| A custom field that can be used to tie user mailboxes to external user systems
|-
| 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',
{
'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',
'customID' => '0123456789',
'organizationalStatus' => 'OrgStatus',
'employeeType' => 'Full-Time'
'visibleInExchangeGAL'=>'true',
'visibleInRackspaceEmailCompanyDirectory' => 'false'

}
</pre>

==== Rename ====

To rename a mailbox, include the ''name'' form key in the put request. If the call is successful, the old email address will be created as an alias to ensure email is still received when sent to the old email address.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith',
{
'name' => 'alex.renamed'
}
</pre>

=== Delete ===
''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/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'
</pre>

=== Create Login Tokens ===

''URL'':

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

''Description'':

Generate a login Token which can be used to log in to a user's mailbox. The POST will return a loginToken, created date, and expiration date.

''Note:''

This route is not available to customers who access the Cloud Office Control Panel via my.rackspace.com and have an admin account with API keys.

''Example'':

<pre>
post '/customers/460896/domains/testapidomain.net/rs/mailboxes/testmailbox/loginToken', {}

</pre>

Create a login Token for testmailbox@testapidomain.net

<pre>

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

<rsMailboxLoginToken xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailboxLoginToken">

<token>5b5e27419a363fc5b65bbb63d1c2d3f8</token>

<dateCreated>9/22/2010 9:33:15 AM</dateCreated>

<expirationDate>9/22/2010 9:53:14 AM</expirationDate>

</rsMailboxLoginToken>

</pre>

The login token is valid until the current time (EST) passes the expiration date, and can be used until that point.

Using the above created login token a user can SSO into testmailbox@testapidomain.net using the following URL:

<pre>
https://{webmail address}/mail/src/redirect.php?user_name={testmailbox@testapidomain.net}&emailaddress=testmailbox@testapidomain.net&sessionID=5b5e27419a363fc5b65bbb63d1c2d3f8
</pre>

Alternatively, the login token can be used to SSO into the webmail mobile site using the following URL:

<pre>
https://{webmail address}/mobile/login.php?user_name=address@domain.com&emailaddress=address@domain.com&sessionID=5b5e27419a363fc5b65bbb63d1c2d3f8
</pre>

Domain Spam (Rest API)

2017-01-12T21:36:35Z

Appscp: remove accept header from examples to avoid confusion

== v1 - Current ==

=== Spam Settings ===

==== Show Spam Setting ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/settings'
</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/v1/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',
{
'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/v1/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.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/blacklist'
</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/v1/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'
</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/v1/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'
</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/v1/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'
}
</pre>

=== IP Blacklist ===

==== Index IP Blacklist ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipblacklist'
</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/v1/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'
</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/v1/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'
</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/v1/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.%.%.%'
}
</pre>

=== Safelist ===

==== Index Safelist ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/safelist'
</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/v1/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'
</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/v1/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'
</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/v1/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'
}
</pre>

=== IP Safelist ===

==== Index IP Safelist ====

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

''Example'':
<pre>
get '/customers/12345678/domains/example.com/spam/ipsafelist'
</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/v1/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'
</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/v1/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'
</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/v1/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.%.%.%'
}
</pre>

Domain (Rest API)

2017-01-12T21:35:18Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/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. <nowiki>'https://api.emailsrvr.com/v1/customers/all/domains'</nowiki>.
*To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. <nowiki>'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains'</nowiki>.
*Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me
<nowiki>'https://api.emailsrvr.com/v1/domains'</nowiki>.

*The index operation only supports the GET HTTP verb.

''Example'':

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

''domainNames Parameter '''(V1 only)''''':
The optional query string parameter "domainNames" can be used to retrieve a specific subset of domains by hostname. Up to 100 hostnames can be given at once in a comma-delimited list.
<pre>
get '/customers/all/domains?domainNames=apidomain53.com,apidomain66.com,apidomain68.com', 'application/json'
</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>
<exchangeMaxNumMailboxes>10</exchangeMaxNumMailboxes>
<exchangeUsedStorage>4</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>10</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>9</rsEmailUsedStorage>
</domain>
<domain>
<name>apidomain66.com</name>
<accountNumber>100001</accountNumber>
<serviceType>rsemail</serviceType>
<exchangeMaxNumMailboxes>0</exchangeMaxNumMailboxes>
<exchangeUsedStorage>0</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>100</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>40</rsEmailUsedStorage>
</domain>
<domain>
<name>apidomain68.com</name>
<accountNumber>100002</accountNumber>
<serviceType>exchange</serviceType>
<exchangeMaxNumMailboxes>50</exchangeMaxNumMailboxes>
<exchangeUsedStorage>10</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>0</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>0</rsEmailUsedStorage>
</domain>
</domains>
</domainList>
</pre>

''Json Result Example'':

<pre>
{"offset":0,"size":50,"total":3,"domains":
[{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both","exchangeMaxNumMailboxes":"10","exchangeUsedStorage":"4","rsEmailMaxNumberMailboxes":"10","rsEmailUsedStorage":"9"},
{"name":"apidomain66.com","accountNumber":"100001","serviceType":"rsemail","exchangeMaxNumMailboxes":"0","exchangeUsedStorage":"0","rsEmailMaxNumberMailboxes":"100","rsEmailUsedStorage":"40"},
{"name":"apidomain68.com","accountNumber":"100002","serviceType":"exchange","exchangeMaxNumMailboxes":"50","exchangeUsedStorage":"10","rsEmailMaxNumberMailboxes":"0","rsEmailUsedStorage":"0"}]}
</pre>

=== Export ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains?exportTo={email address}</nowiki>

''Description'':

Use this route to export a file that includes details for domains on an account.

''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/v1/customers/me/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number. <nowiki>'https://api.emailsrvr.com/v1/customers/all/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. <nowiki>'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me
<nowiki>'https://api.emailsrvr.com/v1/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*The export route supports 'contains' and 'startswith' filtering

=== Show ===

''URL'':

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

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

''Example'':

<pre>
get '/customers/999999/domains/example.com'
</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/v1/customers/(customer account number)/domains/(domain name)
Edit: [PUT] https://api.emailsrvr.com/v1/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',
{
'maxNumMailboxes' => '5',
'extraStorage' => '1024'
}
</pre>

<pre>
put '/customers/123455/domains/newcompany.com',
{
'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/v1/customers/
(new customer account number)/domains/(domain name)</nowiki>

''Description'':

Moves a domain among your account and subaccounts.

{| 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',
{
'moveDomain' => 'true'
}
</pre>

=== Transfer ===

Transfers ownership of a domain to another customer. You can start, read, and cancel the transfer. The other customer can finish the transfer.

==== Start ====

''URL'':

<pre>
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/transfer
</pre>

''Description'':

Creates a transfer, which is represented by a token. A transfer also has an expiration, which is represented by an RFC 3339 formatted timestamp. After the expiration, the transfer is automatically canceled.

''Example'':

<pre>
post'/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The domain does not exist or is not accessible by the admin
| 404
| example.com not found
|}

==== Read ====

''URL'':

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

''Description'':

Retrieves the domain transfer information for the domain that was returned by the request to start the transfer.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| No transfer has been started, or the transfer has expired
| 404
| Domain transfer offer not found.
|}

==== Cancel ====

''URL'':

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

''Description'':

Cancels a domain transfer.

''Example'':

<pre>
delete '/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

==== Finish ====

''URL'':

<pre>
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/transfer/finish
</pre>

''Description'':

Finish a domain transfer. This API request must be made by an admin that is on the account that will accept the domain. When the request completes successfully, assigns ownership of the domain to the company of the authenticated admin. That company will have full control of the domain, and accepts billing for services associated with the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| token
| string
| the token returned by the POST or GET to this resource by an admin with access to the domain
|}

''Example'':

<pre>
post '/customers/12345678/domains/company.com/transfers/finish', 'application/json',
{
'Token' => 'b77b8460-5019-48e0-a5eb-4951640ea3cd'
}
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>
''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The domain does not exist or is not accessible by the admin
| 404
| example.com not found
|-
| The transfer token is invalid
| 404
| example.com not found
|}

=== Delete (Reseller Only)===

''URL'':

<nowiki>[DELETE] https://api.emailsrvr.com/v1/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'
</pre>

=== Alternate Domains ===

==== Index (Reseller Only) ====

''URL'':

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

''Example'':

<pre>
get '/customers/12345678/domains/test.com/alternatedomains'
</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/v1/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',
{
'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/v1/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/v1/customers/(customer account number)/domains/(domain)/splitdomainrouting</nowiki>

''Description'':
Shows the current external email server.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/splitdomainrouting'
</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/v1/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',
{
'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/v1/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'
</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/v1/customers/(customer account number)/domains/(domain name)/ex/publicfolders
</nowiki>

''Description'':

Retrieves the Exchange Public Folders status for the domain.
''Example'':

<pre>
get '/customers/12345678/domains/company.com/ex/publicFolders'
</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/v1/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',
{
'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/v1/customers/(customer account number)/domains/(domain name)/emaileveryone
[POST] https://api.emailsrvr.com/v1/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',
{
'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/v1/customers/(customer account number)/domains/(domain name)/catchalladdress</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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'
</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/v1/customers/(customer account number)/domains/(domain name)/catchalladdress</nowiki>
<nowiki>[PUT] https://api.emailsrvr.com/v1/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',
{
'address' => 'abc@example.com'
}
</pre>

Admin (Rest API)

2017-01-12T21:34:41Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''Example'':

<pre>
get '/customers/999999/admins?size=5&page=1'
</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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''Example'':

<pre>
get '/customers/999999/admins/admin1'
</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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Current ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Exchange Mailbox (Rest API)

2017-01-12T21:32:08Z

Appscp: remove accept header from examples to avoid confusion

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Filter/Search'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

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

''Json Result Example'':

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

''Custom Fields'':

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

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

=== Show ===

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

''Description'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

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

''XML Result Example'':

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

''Json Result Example'':

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

=== Add/Edit ===

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

''Description'':

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

{{RouteRequiresFormEncoded}}

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

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

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

''Errors'':

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

=== Delete ===

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

''Description'':

Deletes the mailbox.

''Remarks'':

The mailbox and mailbox contents are deleted permanently.

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

=== Add Email Address ===

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

''Description'':

Adds a mailbox's email address.

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

=== Delete Email Address ===

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

''Description'':

Deletes the email address.

''Remarks'':

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

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

=== Spam Settings ===

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

=== Mailbox Permissions ===

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

permissionType:= (SendAs | FullAccess | Both)

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

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

''Description'':

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

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

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

''Json Result Example'':

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

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

==== Adding Permission ====

''URL'':

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

''Description'':

Grants user2 the specified permission on mailbox of user1.

{{RouteRequiresFormEncoded}}

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

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

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

==== Editing Permission ====

''URL'':

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

''Description'':

Modifies permission granted to user2 on the mailbox of user1.

{{RouteRequiresFormEncoded}}

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

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

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

==== Deleting Permission ====

''URL'':

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

''Description'':

Deletes permission granted to user2 on the mailbox of user1.

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

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

=== BlackBerry Mobile Service ===

==== Index ====

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''XML Result Example'':

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

''Json Result Example'':

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

==== Add ====

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

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

{{RouteRequiresFormEncoded}}

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

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

''Errors'':

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

==== Delete ====

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

''Description'':

Detaches a BlackBerry mobile service from a mailbox.

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

=== ActiveSync Mobile Service ===

==== Index ====

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''XML Result Example'':

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

''Json Result Example'':

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

==== Show ====

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''XML Result Example'':

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

''Json Result Example'':

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

''Errors'':

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

==== Add ====

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

''Description'':

Attaches a ActiveSync service to the mailbox.

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

''Errors'':

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

==== Delete ====

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

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

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

Exchange Mailbox (Rest API)

2017-01-09T22:06:37Z

Appscp: add note to routes requiring application/x-www-form-urlencoded

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Filter/Search'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

''Description'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

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

''XML Result Example'':

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

''Json Result Example'':

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

=== Add/Edit ===

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

''Description'':

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

{{RouteRequiresFormEncoded}}

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Display name (Required for Add)
|-
| password
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| isHidden
| boolean
| Indicates whether or not the mailbox is hidden from the Global Address List
|-
| isPublicFolderAdmin
| boolean
| Indicates whether or not the account is a public folder administrator
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| jobTitle
| string
| Job title
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| businessNumber
| string
| Business phone number
|-
| pagerNumber
| string
| Pager phone number
|-
| homeNumber
| string
| Home phone number
|-
| mobileNumber
| string
| Mobile phone number
|-
| faxNumber
| string
| Fax phone number
|-
| notes
| string
| Notes field
|-
| customID
| string
| A custom field that can be used to tie user mailboxes to external user systems
|-
| emailForwardingAddress
| string
| Forwarding email address (If this field is assigned an email address, then email forwarding will be turned on. If this field is not assigned or assigned an empty string, then email forwarding will be disabled.)
|-
| 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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)</nowiki>

''Description'':

Deletes the mailbox.

''Remarks'':

The mailbox and mailbox contents are deleted permanently.

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

=== Add Email Address ===

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

''Description'':

Adds a mailbox's email address.

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

=== Delete Email Address ===

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

''Description'':

Deletes the email address.

''Remarks'':

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

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/emailaddresses/alex@example.com', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user)/permissions</nowiki>

''Description'':

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

''Example'':
<pre>
get '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Grants user2 the specified permission on mailbox of user1.

{{RouteRequiresFormEncoded}}

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

''Example'':
<pre>
post '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe', {'permission' => 'fullAccess'}, '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Modifies permission granted to user2 on the mailbox of user1.

{{RouteRequiresFormEncoded}}

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

''Example'':
<pre>
put '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe',
{'permission' => 'both'}, '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Deletes permission granted to user2 on the mailbox of user1.

''Example'':
<pre>
delete '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/blackberrymobileservices</nowiki>

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

{{RouteRequiresFormEncoded}}

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

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/blackberrymobileservice', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/blackberrymobileservice</nowiki>

''Description'':

Detaches a BlackBerry mobile service from a mailbox.

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

=== ActiveSync Mobile Service ===

==== Index ====

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Attaches a ActiveSync service to the mailbox.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

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

Template:RouteRequiresFormEncoded

2017-01-09T21:48:39Z

Appscp: Created page with "'''Note''': this route requires that you submit the request body in <code>Content-Type: application/x-www-form-urlencoded</code> format"

'''Note''': this route requires that you submit the request body in <code>Content-Type: application/x-www-form-urlencoded</code> format

Exchange Mailbox (Rest API)

2017-01-09T21:39:27Z

Appscp: Undo revision 720 by Appscp (talk)

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Filter/Search'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

''Description'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

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

''XML Result Example'':

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

''Json Result Example'':

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

=== Add/Edit ===

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

''Description'':

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

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Display name (Required for Add)
|-
| password
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| isHidden
| boolean
| Indicates whether or not the mailbox is hidden from the Global Address List
|-
| isPublicFolderAdmin
| boolean
| Indicates whether or not the account is a public folder administrator
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| jobTitle
| string
| Job title
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| businessNumber
| string
| Business phone number
|-
| pagerNumber
| string
| Pager phone number
|-
| homeNumber
| string
| Home phone number
|-
| mobileNumber
| string
| Mobile phone number
|-
| faxNumber
| string
| Fax phone number
|-
| notes
| string
| Notes field
|-
| customID
| string
| A custom field that can be used to tie user mailboxes to external user systems
|-
| emailForwardingAddress
| string
| Forwarding email address (If this field is assigned an email address, then email forwarding will be turned on. If this field is not assigned or assigned an empty string, then email forwarding will be disabled.)
|-
| 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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)</nowiki>

''Description'':

Deletes the mailbox.

''Remarks'':

The mailbox and mailbox contents are deleted permanently.

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

=== Add Email Address ===

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

''Description'':

Adds a mailbox's email address.

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

=== Delete Email Address ===

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

''Description'':

Deletes the email address.

''Remarks'':

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

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/emailaddresses/alex@example.com', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user)/permissions</nowiki>

''Description'':

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

''Example'':
<pre>
get '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions', '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/v1/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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Modifies permission granted to user2 on the mailbox of user1.

{| 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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Deletes permission granted to user2 on the mailbox of user1.

''Example'':
<pre>
delete '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/blackberrymobileservices</nowiki>

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Description'':

Detaches a BlackBerry mobile service from a mailbox.

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

=== ActiveSync Mobile Service ===

==== Index ====

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Attaches a ActiveSync service to the mailbox.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

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

Exchange Mailbox (Rest API)

2017-01-09T21:37:16Z

Appscp: Reverted edits by Appscp (talk) to last revision by Zhen.wei

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

SharePoint (Rest API)

2016-03-01T15:49:55Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Settings ===

==== Show ====

''URL'':

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

''Description'':

Returns the status and quota size of the SharePoint service.

''Example'':

<pre>
get '/customers/999999/sharepoint/settings', 'text/xml'
</pre>

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<SharePointSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:SharePointSettings">
<enabled>true</enabled>
<size>0.25</size>
</SharePointSettings>
</pre>

''Json Result Example'':
<pre>
{"enabled":true,"size":0.25}
</pre>

==== Edit (Reseller Only) ====

''URL'':
<nowiki>[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/sharepoint/settings</nowiki>

''Description'':

This operation will modify SharePoint's settings.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| enabled
| boolean
| Whether SharePoint is enabled or not. By enabling SharePoint you and/or your customers are agreeing to Rackspace's [http://www.rackspace.com/information/legal/sharepointappterms.php SharePoint Services Terms and Conditions].
|-
| size
| double
| SharePoint's storage size in GB. Valid values are .25 and any integer between 1 and 50 inclusive. This field will be ignored when SharePoint is disabled. (default value is 0.25GB)
|}

''Example'':
<pre>
put '/customers/123456/sharepoint/settings', 'text/xml',
{
'enabled' => 'true',
'size' => '10.0'
}
</pre>

Exchange Contact (Rest API)

2016-03-01T15:48:52Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Index ===

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

''Description'':

Returns a list of contacts under the domain.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts?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/v1/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)</nowiki>

''Description'':

Returns the contact's details.

''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/v1/customers/(customer account number)/domains/(domain name)
/ex/contacts/(contact name)

Edit: [PUT] https://api.emailsrvr.com/v1/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/v1/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
|}

Exchange Mailbox Spam (Rest API)

2016-03-01T15:48:02Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

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

''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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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>

Exchange Mailbox (Rest API)

2016-03-01T15:46:26Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

''Description'':

Shows a list of mailboxes under the domain

''Filter/Search'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

''Description'':

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

''Remarks'':

The show operation only supports the GET HTTP verb.

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

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

''XML Result Example'':

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

''Json Result Example'':

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

=== Add/Edit ===

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

''Description'':

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

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Display name (Required for Add)
|-
| password
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| isHidden
| boolean
| Indicates whether or not the mailbox is hidden from the Global Address List
|-
| isPublicFolderAdmin
| boolean
| Indicates whether or not the account is a public folder administrator
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| jobTitle
| string
| Job title
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| businessNumber
| string
| Business phone number
|-
| pagerNumber
| string
| Pager phone number
|-
| homeNumber
| string
| Home phone number
|-
| mobileNumber
| string
| Mobile phone number
|-
| faxNumber
| string
| Fax phone number
|-
| notes
| string
| Notes field
|-
| customID
| string
| A custom field that can be used to tie user mailboxes to external user systems
|-
| emailForwardingAddress
| string
| Forwarding email address (If this field is assigned an email address, then email forwarding will be turned on. If this field is not assigned or assigned an empty string, then email forwarding will be disabled.)
|-
| 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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)</nowiki>

''Description'':

Deletes the mailbox.

''Remarks'':

The mailbox and mailbox contents are deleted permanently.

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

=== Add Email Address ===

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

''Description'':

Adds a mailbox's email address.

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

=== Delete Email Address ===

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

''Description'':

Deletes the email address.

''Remarks'':

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

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/emailaddresses/alex@example.com', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user)/permissions</nowiki>

''Description'':

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

''Example'':
<pre>
get '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions', '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/v1/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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Modifies permission granted to user2 on the mailbox of user1.

{| 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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(user1)/permissions/(user2)</nowiki>

''Description'':

Deletes permission granted to user2 on the mailbox of user1.

''Example'':
<pre>
delete '/customers/100012/domains/enterpriseallservices.net/ex/mailboxes/jane.doe/permissions/john.doe', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/blackberrymobileservices</nowiki>

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Description'':

Detaches a BlackBerry mobile service from a mailbox.

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

=== ActiveSync Mobile Service ===

==== Index ====

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Attaches a ActiveSync service to the mailbox.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/john.smith/activesyncmobileservice', '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/v1/customers/(customer account number)/domains/(domain name)
/ex/mailboxes/(mailbox name)/activesyncmobileservice</nowiki>

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

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

Rackspace Alias(Rest API)

2016-03-01T15:45:12Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

''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/v1/customers/(customer account number)/domains/(domain name)
/rs/aliases/(alias name)</nowiki>

''Description'':

Creates an alias.

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

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

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

''Errors'':

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

=== Show ===

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

''Description'':

Returns detailed information about the specified alias.

''Remarks'':

The show operation only supports the GET HTTP verb.

''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/v1/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/v1/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/v1/customers/(customer account number)/domains/(domain name)
/rs/aliases/(alias name)/(email address)
</nowiki>

''Description'':

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

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

''Errors'':

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

=== Bulk Modify Alias List ===

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

''Description'':

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

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

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

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

''Form Fields:''

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

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

''Errors'':

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

Rackspace Storage Notification (Rest API)

2016-03-01T15:44:46Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Show ===

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

''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/v1/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>

Rackspace Mailbox Spam (Rest API)

2016-03-01T15:44:26Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Spam Settings ===

==== Show ====

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

''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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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>

Rackspace Mailbox (Rest API)

2016-03-01T15:42:24Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

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

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

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

''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', 'enabled', 'createdDate', and 'lastLogin'

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

=== Show ===

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

''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>
<customID>0123456789</customID>
<organizationalStatus>OrgStatus</organizationalStatus>
<employeeType>Full-Time</employeeType>
</contactInfo>
<enabled>true</enabled>
</rsMailbox>
</pre>

''Json Result Example'':

<pre>
{
"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",
"customID": "0123456789"
},
"name": "unittestexist",
"saveForwardedEmail": false,
"size": 10240,
"vacationMessage": "Test Vacation Message",
"createdDate": "4\/10\/2006 7:47:34 PM",
"currentUsage": 1024,
"visibleInExchangeGAL": false,
"visibleInRackspaceEmailCompanyDirectory": false
}
</pre>

==== Recoverable Mailboxes ====

If the mailbox does not exist, the API will return the regular <tt>[[Errors#404_Not_Found|itemNotFound]]</tt> data. In addition, it will also return a boolean value <tt>isRecoverable</tt> which is set to <tt>true</tt> if the mailbox is recoverable. If <tt>isRecoverable</tt> is <tt>true</tt>, <tt>deletedDate</tt> will also be set, otherwise <tt>deletedDate</tt> will not be included.

''XML Result Example'':

<pre>
<?xml version="1.0" encoding="utf-8"?>
<itemNotFoundFault
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://api.emailsrvr.com/v0/Schemas"
code="404">
<additionalData>
<isRecoverable>
<boolean>true</boolean>
</isRecoverable>
<deletedDate>
<dateTime>2015-01-10T21:59:55.5645572Z</dateTime>
</deletedDate>
</additionalData>
<message>Entity of type Mailbox identified by some.deleted.mailbox@example.comwas not found</message>
<details>1/12/2015 4:59:55 PM</details>
<resourceType>Mailbox</resourceType>
</itemNotFoundFault>
</pre>

''Json Result Example'':

<pre>
{
"itemNotFoundFault": {
"resourceType": "Mailbox",
"additionalData": {
"isRecoverable": true,
"deletedDate": "2015-01-10T21:50:26.9430015Z"
},
"message": "Entity of type Mailbox identified by some.deleted.mailbox@example.com was not found",
"details": "1/12/2015 4:50:26 PM",
"code": 404
}
}
</pre>

=== Add/Edit ===

''URL'':
<nowiki>Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
/rs/mailboxes/(mailbox name)
Edit: [PUT] https://api.emailsrvr.com/v1/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)
|-
| recoverDeleted
| boolean
| If set to true, any retained messages will be recovered. See [[#Recoverable_Mailboxes|Recoverable Mailboxes]].
|-
| 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
|-
| customID
| string
| A custom field that can be used to tie user mailboxes to external user systems
|-
| 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',
'customID' => '0123456789',
'organizationalStatus' => 'OrgStatus',
'employeeType' => 'Full-Time'
'visibleInExchangeGAL'=>'true',
'visibleInRackspaceEmailCompanyDirectory' => 'false'

}
</pre>

==== Rename ====

To rename a mailbox, include the ''name'' form key in the put request. If the call is successful, the old email address will be created as an alias to ensure email is still received when sent to the old email address.

''Example'':
<pre>
put '/customers/12345678/domains/example.com/rs/mailboxes/alex.smith', 'text/xml',
{
'name' => 'alex.renamed'
}
</pre>

=== Delete ===
''URL'':
<nowiki>[DELETE] https://api.emailsrvr.com/v1/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>

=== Create Login Tokens ===

''URL'':

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

''Description'':

Generate a login Token which can be used to log in to a user's mailbox. The POST will return a loginToken, created date, and expiration date.

''Note:''

This route is not available to customers who access the Cloud Office Control Panel via my.rackspace.com and have an admin account with API keys.

''Example'':

<pre>
post '/customers/460896/domains/testapidomain.net/rs/mailboxes/testmailbox/loginToken', {}, 'text/xml'

</pre>

Create a login Token for testmailbox@testapidomain.net

<pre>

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

<rsMailboxLoginToken xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:rsMailboxLoginToken">

<token>5b5e27419a363fc5b65bbb63d1c2d3f8</token>

<dateCreated>9/22/2010 9:33:15 AM</dateCreated>

<expirationDate>9/22/2010 9:53:14 AM</expirationDate>

</rsMailboxLoginToken>

</pre>

The login token is valid until the current time (EST) passes the expiration date, and can be used until that point.

Using the above created login token a user can SSO into testmailbox@testapidomain.net using the following URL:

<pre>
https://{webmail address}/mail/src/redirect.php?user_name={testmailbox@testapidomain.net}&emailaddress=testmailbox@testapidomain.net&sessionID=5b5e27419a363fc5b65bbb63d1c2d3f8
</pre>

Alternatively, the login token can be used to SSO into the webmail mobile site using the following URL:

<pre>
https://{webmail address}/mobile/login.php?user_name=address@domain.com&emailaddress=address@domain.com&sessionID=5b5e27419a363fc5b65bbb63d1c2d3f8
</pre>

Domain Spam (Rest API)

2016-03-01T15:41:28Z

Appscp: /* v1 - Current */

== v1 - Current ==

=== Spam Settings ===

==== Show Spam Setting ====

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

''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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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/v1/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.

''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/v1/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/v1/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/v1/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>

Domain (Rest API)

2016-03-01T15:40:22Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/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. <nowiki>'https://api.emailsrvr.com/v1/customers/all/domains'</nowiki>.
*To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. <nowiki>'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains'</nowiki>.
*Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me
<nowiki>'https://api.emailsrvr.com/v1/domains'</nowiki>.

*The index operation only supports the GET HTTP verb.

''Example'':

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

''domainNames Parameter '''(V1 only)''''':
The optional query string parameter "domainNames" can be used to retrieve a specific subset of domains by hostname. Up to 100 hostnames can be given at once in a comma-delimited list.
<pre>
get '/customers/all/domains?domainNames=apidomain53.com,apidomain66.com,apidomain68.com', 'application/json'
</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>
<exchangeMaxNumMailboxes>10</exchangeMaxNumMailboxes>
<exchangeUsedStorage>4</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>10</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>9</rsEmailUsedStorage>
</domain>
<domain>
<name>apidomain66.com</name>
<accountNumber>100001</accountNumber>
<serviceType>rsemail</serviceType>
<exchangeMaxNumMailboxes>0</exchangeMaxNumMailboxes>
<exchangeUsedStorage>0</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>100</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>40</rsEmailUsedStorage>
</domain>
<domain>
<name>apidomain68.com</name>
<accountNumber>100002</accountNumber>
<serviceType>exchange</serviceType>
<exchangeMaxNumMailboxes>50</exchangeMaxNumMailboxes>
<exchangeUsedStorage>10</exchangeUsedStorage>
<rsEmailMaxNumberMailboxes>0</rsEmailMaxNumberMailboxes>
<rsEmailUsedStorage>0</rsEmailUsedStorage>
</domain>
</domains>
</domainList>
</pre>

''Json Result Example'':

<pre>
{"offset":0,"size":50,"total":3,"domains":
[{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both","exchangeMaxNumMailboxes":"10","exchangeUsedStorage":"4","rsEmailMaxNumberMailboxes":"10","rsEmailUsedStorage":"9"},
{"name":"apidomain66.com","accountNumber":"100001","serviceType":"rsemail","exchangeMaxNumMailboxes":"0","exchangeUsedStorage":"0","rsEmailMaxNumberMailboxes":"100","rsEmailUsedStorage":"40"},
{"name":"apidomain68.com","accountNumber":"100002","serviceType":"exchange","exchangeMaxNumMailboxes":"50","exchangeUsedStorage":"10","rsEmailMaxNumberMailboxes":"0","rsEmailUsedStorage":"0"}]}
</pre>

=== Export ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains?exportTo={email address}</nowiki>

''Description'':

Use this route to export a file that includes details for domains on an account.

''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/v1/customers/me/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number. <nowiki>'https://api.emailsrvr.com/v1/customers/all/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. <nowiki>'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me
<nowiki>'https://api.emailsrvr.com/v1/domains?exportTo=myAdminEmail@example.com'</nowiki>.
*The export route supports 'contains' and 'startswith' filtering

=== Show ===

''URL'':

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

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

''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/v1/customers/(customer account number)/domains/(domain name)
Edit: [PUT] https://api.emailsrvr.com/v1/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/v1/customers/
(new customer account number)/domains/(domain name)</nowiki>

''Description'':

Moves a domain among your account and subaccounts.

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

=== Transfer ===

Transfers ownership of a domain to another customer. You can start, read, and cancel the transfer. The other customer can finish the transfer.

==== Start ====

''URL'':

<pre>
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/transfer
</pre>

''Description'':

Creates a transfer, which is represented by a token. A transfer also has an expiration, which is represented by an RFC 3339 formatted timestamp. After the expiration, the transfer is automatically canceled.

''Example'':

<pre>
post'/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The domain does not exist or is not accessible by the admin
| 404
| example.com not found
|}

==== Read ====

''URL'':

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

''Description'':

Retrieves the domain transfer information for the domain that was returned by the request to start the transfer.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>

''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| No transfer has been started, or the transfer has expired
| 404
| Domain transfer offer not found.
|}

==== Cancel ====

''URL'':

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

''Description'':

Cancels a domain transfer.

''Example'':

<pre>
delete '/customers/12345678/domains/company.com/transfer', 'application/json'
</pre>

==== Finish ====

''URL'':

<pre>
[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/transfer/finish
</pre>

''Description'':

Finish a domain transfer. This API request must be made by an admin that is on the account that will accept the domain. When the request completes successfully, assigns ownership of the domain to the company of the authenticated admin. That company will have full control of the domain, and accepts billing for services associated with the domain.

{| class="wikitable"
!''Field Name''
!''Data Type''
!''Description''
|-
| token
| string
| the token returned by the POST or GET to this resource by an admin with access to the domain
|}

''Example'':

<pre>
post '/customers/12345678/domains/company.com/transfers/finish', 'application/json',
{
'Token' => 'b77b8460-5019-48e0-a5eb-4951640ea3cd'
}
</pre>

''JSON Result Example'':

<pre>
{
"Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
"Expiration": "2014-08-20T17:28:44Z"
}
</pre>
''Errors'':

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| The domain does not exist or is not accessible by the admin
| 404
| example.com not found
|-
| The transfer token is invalid
| 404
| example.com not found
|}

=== Delete (Reseller Only)===

''URL'':

<nowiki>[DELETE] https://api.emailsrvr.com/v1/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/v1/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.

''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/v1/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/v1/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/v1/customers/(customer account number)/domains/(domain)/splitdomainrouting</nowiki>

''Description'':
Shows the current external email server.

''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/v1/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/v1/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/v1/customers/(customer account number)/domains/(domain name)/ex/publicfolders
</nowiki>

''Description'':

Retrieves the Exchange Public Folders status for the domain.
''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/v1/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/v1/customers/(customer account number)/domains/(domain name)/emaileveryone
[POST] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/domains/(domain name)/catchalladdress</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/domains/(domain name)/catchalladdress</nowiki>
<nowiki>[PUT] https://api.emailsrvr.com/v1/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>

Admin (Rest API)

2016-03-01T15:38:51Z

Appscp: /* v1 - Current */

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/customers/me/domains'</nowiki>.

The index operation only supports the GET HTTP verb.

''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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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.

''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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Current ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Customer (Rest API)

2016-03-01T15:38:01Z

Appscp:

__TOC__

== v1 - Current ==

=== Index (Reseller Only) ===

''URL'':

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

''Description'':

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

''Filter/Search'':

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

''Example'':

<pre>
get '/customers?size=100&offset=10', '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/v1/customers/(customer account number)</nowiki>

''Description'':

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

''Remarks'':

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

The show operation only supports the GET HTTP verb.

''Reference Number''

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

''Examples'':

<pre>
get '/customers/me', '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>
<addressLine1>555 Address</addressLine1>
<addressLine2>Suite 555</addressLine2>
<city>Austin</city>
<state>TX</state>
<zip>78703</zip>
<country>US</country>
<phone>1-555-555-5555</phone>
<email>user@example.com</email>
</customer>
</pre>

''JSON Result Example'':

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

''Example of querying with Reference Number''

<pre>
get '/customers?referenceNumber=49', '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>
<addressLine1>555 Address</addressLine1>
<addressLine2>Suite 555</addressLine2>
<city>Austin</city>
<state>TX</state>
<zip>78703</zip>
<country>US</country>
<phone>1-555-555-5555</phone>
<email>user@example.com</email>
</customer>
</pre>

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

''URL'':

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

''Description'':

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

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

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

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

''Example'':

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

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

''Errors'':

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

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

''URL'':

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

''Description'':

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

''Example'':

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

''Errors'':

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

=== Delete (Reseller Only) ===

''URL'':

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

''Description'':

Deletes the account.

''Example'':

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

=== Create Login Tokens ===

''URL'':

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

''Description'':

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

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

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

''Example'':

<pre>
post '/customers/460896/loginToken', {'userName' => 'dev_cust_limitedadmin', 'virtualUser' => 'true'}, '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).

== v2 - Current ==

=== Company contacts ===

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

==== View contacts ====

''Description'':

View all contacts for an account.

''Request'':

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

''Response'':

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

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

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

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

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

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

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

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

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

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

''Description'':

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

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

''Request'':

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

''Response'':

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

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

''Description'':

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

''Request'':

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

''Response'':

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

==== Add a contact ====

''Description'':

Create a new contact.

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

''Request'':

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

==== Update a contact ====

''Description'':

Update information for the contact you specify.

''Request'':

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

''Response'':

<pre>
200 OK
</pre>

==== Delete a contact ====

''Description'':

Remove a contact from the account.

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

''Request'':

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

''Response'':

<pre>
200 OK
</pre>

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

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

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

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

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

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

Admin (Rest API)

2016-01-05T17:18:50Z

Appscp:

__TOC__

== v1 - Current ==

=== Index ===

''URL'':

<nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/v1/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/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[GET] https://api.emailsrvr.com/v1/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/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/v1/customers/(customer account number)/admins/(admin name)
[POST] https://api.emailsrvr.com/v1/admins/(admin name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[PUT] https://api.emailsrvr.com/v1/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/v1/customers/(customer account number)/admins/(admin name)</nowiki>
<nowiki>[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)</nowiki>

''Description'':

Deletes the admin.

''Example'':

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

== v2 - Current ==



=== Enable and Disable Two-Factor Authentication ===

Enabling two-factor authentication requires installing [[https://support.google.com/accounts/answer/1066447?hl=en Google Authenticator]] or another TOTP-compatible app on a mobile device. The authenticator provides the verification code required to set a key.

You can set and remove keys for any admin on the account, including your own.

==== Generate a Secret Key ====

''Description'':

Generate a [[https://tools.ietf.org/html/rfc6238#page-4 TOTP]] secret key for two-factor authentication.

Generating a new key changes no server state. The server does not store the key, nor is two-factor authentication enabled or disabled for that admin.

''Request'':

<pre>
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
</pre>

''Response'':

<pre>
200 OK
{
"Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}
</pre>

==== Enable Two-Factor Authentication ====

''Description'':

Provide a secret key and verification code to enable two-factor authentication for an admin.

''Request'':

<pre>
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

==== Disable Two-Factor Authentication ====

''Description'':

Disable two-factor authentication for an admin.

''Request'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

''Response'':

<code>204 No Content</code>

''Example'':

<pre>
post /v2/customers/me/admins/999999999/twoFactorAuth
{
"Enabled": false
},
'application/json'
</pre>

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

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method
| 404 Not Found
| Make sure the URL is correct. (Did you include <nowiki>/newKey</nowiki> in the path?)
|}

==== Errors for POST requests ====

{| class="wikitable"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Invalid method (GET requests only)
| 404 Not Found
| Make sure the URL is correct. (Did you include <code>/newKey</code> in the path?)
|-
| POST body is empty
| 400 Bad Request
| Payload must be a valid JSON object. Make sure the POST body contains content.
|-
| Wrong content type
| 400 Bad Request
| Payload must be a valid JSON object. Verify that the content type is <code>application/json</code>.
|-
| Missing fields
| 400 Bad Request
| Must send a "secretKey" property. Correctly populate empty fields in the POST body.
|-
| Missing verification code
| 400 Bad Request
| Must send a "verificationCode" property.
|-
| Secret key is invalid
| 400 Bad Request
| "secretKey" contains invalid characters.
|-
| Secret key is null
| 400 Bad Request
| Must send a "secretKey" property.
|-
| Verification code is an int
| 400 Bad Request
| Must send "verificationCode" as a string in quotes.
|}

Customer (Rest API)

2016-01-05T17:18:06Z

Appscp:

__TOC__

== v1 - Current ==

=== Index (Reseller Only) ===

''URL'':

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

''Description'':

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

''Filter/Search'':

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

''Example'':

<pre>
get '/customers?size=100&offset=10', '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/v1/customers/(customer account number)</nowiki>

''Description'':

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

''Remarks'':

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

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [http://api.emailsrvr.com/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>
<addressLine1>555 Address</addressLine1>
<addressLine2>Suite 555</addressLine2>
<city>Austin</city>
<state>TX</state>
<zip>78703</zip>
<country>US</country>
<phone>1-555-555-5555</phone>
<email>user@example.com</email>
</customer>
</pre>

''JSON Result Example'':

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

''Example of querying with Reference Number''

<pre>
get '/customers?referenceNumber=49', '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>
<addressLine1>555 Address</addressLine1>
<addressLine2>Suite 555</addressLine2>
<city>Austin</city>
<state>TX</state>
<zip>78703</zip>
<country>US</country>
<phone>1-555-555-5555</phone>
<email>user@example.com</email>
</customer>
</pre>

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

''URL'':

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

''Description'':

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

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

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

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

''Example'':

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

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

''Errors'':

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

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

''URL'':

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

''Description'':

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

''Example'':

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

''Errors'':

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

=== Delete (Reseller Only) ===

''URL'':

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

''Description'':

Deletes the account.

''Example'':

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

=== Create Login Tokens ===

''URL'':

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

''Description'':

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

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

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

''Example'':

<pre>
post '/customers/460896/loginToken', {'userName' => 'dev_cust_limitedadmin', 'virtualUser' => 'true'}, '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).

== v2 - Current ==

=== Company contacts ===

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

==== View contacts ====

''Description'':

View all contacts for an account.

''Request'':

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

''Response'':

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

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

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

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

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

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

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

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

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

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

''Description'':

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

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

''Request'':

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

''Response'':

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

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

''Description'':

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

''Request'':

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

''Response'':

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

==== Add a contact ====

''Description'':

Create a new contact.

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

''Request'':

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

==== Update a contact ====

''Description'':

Update information for the contact you specify.

''Request'':

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

''Response'':

<pre>
200 OK
</pre>

==== Delete a contact ====

''Description'':

Remove a contact from the account.

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

''Request'':

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

''Response'':

<pre>
200 OK
</pre>

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

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

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

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

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

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

Reseller

2015-11-02T20:47:59Z

Appscp:

== SOAP Access ==

Functions for the Reseller API should be accessed using these paramenters:

* WSDL URI:  https://admin.webmail.us/excedentsoap/excedentsoap.wsdl

* Service Name:   excedentsoap

* Service Port:   UtilsSoapPort

== Categories ==

[[Companies|Companies/Sub-accounts]] 
[[Domains]] 
[[Users]] 
[[Aliases]] 

[[AllReseller|All Reseller API Functions]]

Business

2015-11-02T20:45:00Z

Appscp:

== SOAP Access ==

Functions for the Business API can be accessed using these paramenters:

* WSDL URI:  https://admin.webmail.us/mailaccounts/mailaccounts.wsdl

* Service Name:   mailaccounts

* Service Port:   UtilsSoapPort

== Functions ==

* [[BusinessAll|Complete list]]
* [[BusinessUser|Users and aliases]]
* [[BusinessDomain|Domain and bulk operations]]

Main Page

2015-10-13T18:59:18Z

Appscp: /* Operations */

== Introduction ==

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

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

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

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

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

== Operations ==

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

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

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

== Quick Start ==

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

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

== Accessing the API ==

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

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

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

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

=== Versions ===

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

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

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

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

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

=== Authentication ===

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

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

An unsuccessful authentication will result in a 403 HTTP code.

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

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

Remember to include the colons between the data strings!

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

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

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

'''SHA1 Hash''':

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

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

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

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

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

== Using the API ==

=== Requests ===

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

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

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

==== URL ====

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

==== HTTP Method ====

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

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

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

==== HTTP Headers ====

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

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

==== Form Data ====

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

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

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

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

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

==== Throttling ====

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

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

{| class="wikitable"
!''Operation Category''
!''Request Limit''
|-
| GET
| 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 /v1/customers/12345678/domains/example.com/ex/mailboxes?size=100&offset=100 HTTP/1.1
Host: api.emailsrvr.com
User-Agent: Rackspace Management Interface
X-Api-Signature: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=
Accept: text/xml
</pre>

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

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

</pre>

=== Responses ===

==== HTTP Status Code ====

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

==== HTTP Response Body ====

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

===== Formats =====

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

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

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

==== HTTP Headers ====

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

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

==== Errors ====

See [[Errors]].

==== Paging ====

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

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

===== Example =====

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

==== Examples ====

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

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

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

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

== Examples ==

=== Ruby ===

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

<pre>
require 'server.rb'

server = Server.new

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

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

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

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

class Server
include Test::Unit::Assertions

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

# Response Type Enums

def xml_format
'text/xml'
end

def json_format
'application/json'
end

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

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

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

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

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

response
end

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

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

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

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

data_to_sign = apiKey + userAgent + timestamp + secretKey

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

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

=== C# ===

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

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

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

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

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

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

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

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

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

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

}

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

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

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

=== PHP ===

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

Exchange Lync (Rest API)

2015-10-13T18:57:35Z

Appscp: Appscp moved page Exchange Lync (Rest API) to Exchange Skype For Business (Rest API)

#REDIRECT [[Exchange Skype For Business (Rest API)]]