Rackspace Email & Apps API - User contributions [en]

Customer (Rest API)

2015-11-17T20:21:10Z

Zach7981: Adding routes for company contacts, additional customer information fields

__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 - Coming soon ==

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

2015-11-17T20:15:13Z

Zach7981: Adding endpoints for two-factor authentication.

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

Customer (Rest API)

2015-10-21T17:21:45Z

Zach7981:

Customer (Rest API)

2015-10-19T21:33:11Z

Zach7981: Undo revision 698 by Zach7981 (talk)

Customer (Rest API)

2015-10-19T21:32:38Z

Zach7981: Added fields for customer information.

Admin (Rest API)

2015-10-15T23:57:01Z

Zach7981: /* 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. 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.

''URL'':

<pre>
[GET] /v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey
Accept: application/json
</pre>

''HTTP response'':

<code>200 OK</code> with a JSON response:

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

''Example'':

<pre>
get '/v2/customers/me/admins/999999999/twoFactorAuth/newKey', 'application/json'
</pre>

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

''Description'':

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

''URL'':

<pre>
[POST] /v2/customers/me/admins/(admin ID)/twoFactorAuth
Content-type: application/json

{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
}
</pre>

''HTTP response'':

<code>204 No Content</code>

''Example'':

<pre>
post '/v2/customers/me/admins/999999999/twoFactorAuth',
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

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

''Description'':

Disable two-factor authentication for an admin.

''URL'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
Content-Type: application/json

{
"Enabled": false
}
</pre>

''HTTP 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 contains a leading zero
| 400 Bad Request
| The "verificationCode" value is not valid for the "secretKey" value. Enter a new verification code without a leading zero.
|}

Admin (Rest API)

2015-10-13T22:27:38Z

Zach7981: Edited example JSON result for readability

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

''URL'':

<pre>
[GET] /v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey
Accept: application/json
</pre>

''HTTP response'':

<code>200 OK</code> with a JSON response:

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

''Example'':

<pre>
get '/v2/customers/me/admins/999999999/twoFactorAuth/newKey', 'application/json'
</pre>

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

''Description'':

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

''URL'':

<pre>
[POST] /v2/customers/me/admins/(admin ID)/twoFactorAuth
Content-type: application/json

{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
}
</pre>

''HTTP response'':

<code>204 No Content</code>

''Example'':

<pre>
post '/v2/customers/me/admins/999999999/twoFactorAuth',
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

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

''Description'':

Disable two-factor authentication for an admin.

''URL'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
Content-Type: application/json

{
"Enabled": false
}
</pre>

''HTTP 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 contains a leading zero
| 400 Bad Request
| The "verificationCode" value is not valid for the "secretKey" value. Enter a new verification code without a leading zero.
|}

Admin (Rest API)

2015-10-13T22:25:37Z

Zach7981: Reformatted example JSON result for readability

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

''URL'':

<pre>
[GET] /v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey
Accept: application/json
</pre>

''HTTP response'':

<code>200 OK</code> with a JSON response:

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

''Example'':

<pre>
get '/v2/customers/me/admins/999999999/twoFactorAuth/newKey', 'application/json'
</pre>

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

''Description'':

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

''URL'':

<pre>
[POST] /v2/customers/me/admins/(admin ID)/twoFactorAuth
Content-type: application/json

{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
}
</pre>

''HTTP response'':

<code>204 No Content</code>

''Example'':

<pre>
post '/v2/customers/me/admins/999999999/twoFactorAuth',
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

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

''Description'':

Disable two-factor authentication for an admin.

''URL'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
Content-Type: application/json

{
"Enabled": false
}
</pre>

''HTTP 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 contains a leading zero
| 400 Bad Request
| The "verificationCode" value is not valid for the "secretKey" value. Enter a new verification code without a leading zero.
|}

Admin (Rest API)

2015-10-13T22:14:57Z

Zach7981: Added paths for two-factor authentication.

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

''URL'':

<pre>
[GET] /v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey
Accept: application/json
</pre>

''HTTP response'':

<code>200 OK</code> with a JSON response:

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

''Example'':

<pre>
get '/v2/customers/me/admins/999999999/twoFactorAuth/newKey', 'application/json'
</pre>

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

''Description'':

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

''URL'':

<pre>
[POST] /v2/customers/me/admins/(admin ID)/twoFactorAuth
Content-type: application/json

{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
}
</pre>

''HTTP response'':

<code>204 No Content</code>

''Example'':

<pre>
post '/v2/customers/me/admins/999999999/twoFactorAuth',
{
"SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
"VerificationCode": "123456"
},
'application/json'
</pre>

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

''Description'':

Disable two-factor authentication for an admin.

''URL'':
<pre>
POST /v2/customers/me/admins/reseller/twoFactorAuth
Content-Type: application/json

{
"Enabled": false
}
</pre>

''HTTP 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 contains a leading zero
| 400 Bad Request
| The "verificationCode" value is not valid for the "secretKey" value. Enter a new verification code without a leading zero.
|}