Difference between revisions of "Admin (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
(Reformatted example JSON result for readability)
 
(16 intermediate revisions by 2 users not shown)
Line 6: Line 6:
  
  
''URL'':  
+
''URL'':
  
 
  <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
 
  <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins</nowiki>
Line 21: Line 21:
 
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>.
 
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]
+
The index operation only supports the GET HTTP verb.
  
  
Line 27: Line 27:
  
 
<pre>
 
<pre>
get '/customers/999999/admins?size=5&page=1', 'text/xml'
+
get '/customers/999999/admins?size=5&page=1'
 
</pre>
 
</pre>
  
Line 42: Line 42:
 
     <admin>
 
     <admin>
 
       <adminId>apiadmin37</adminId>
 
       <adminId>apiadmin37</adminId>
 +
      <firstName>John</firstName>
 +
      <lastName>Doe</lastName>
 
       <type>super</type>
 
       <type>super</type>
 +
      <email>john.doe@example.com</email>
 
       <enabled>true</enabled>
 
       <enabled>true</enabled>
 
       <locked>false</locked>
 
       <locked>false</locked>
 +
      <twoFactorEnabled>true</twoFactorEnabled>
 
     </admin>
 
     </admin>
 
     <admin>
 
     <admin>
 
       <adminId>apiadmin76</adminId>
 
       <adminId>apiadmin76</adminId>
 +
      <firstName>Jane</firstName>
 +
      <lastName>Doe</lastName>
 
       <type>super</type>
 
       <type>super</type>
 +
      <email>jane.doe@example.com</email>
 
       <enabled>true</enabled>
 
       <enabled>true</enabled>
 
       <locked>false</locked>
 
       <locked>false</locked>
 +
      <twoFactorEnabled>true</twoFactorEnabled>
 
     </admin>
 
     </admin>
 
     <admin>
 
     <admin>
 
       <adminId>apiadmin94</adminId>
 
       <adminId>apiadmin94</adminId>
 +
      <firstName>Test</firstName>
 +
      <lastName>User</lastName>
 
       <type>super</type>
 
       <type>super</type>
 +
      <email>test.user@example.com</email>
 
       <enabled>true</enabled>
 
       <enabled>true</enabled>
 
       <locked>false</locked>
 
       <locked>false</locked>
 +
      <twoFactorEnabled>false</twoFactorEnabled>
 
     </admin>
 
     </admin>
 
   </admins>
 
   </admins>
Line 66: Line 78:
  
 
<pre>
 
<pre>
{ "admins":
+
{
     [
+
  "admins":[
        {  
+
     {
            "adminId":"apiadmin37",
+
      "adminId":"apiadmin37",
            "enabled":true,
+
      "firstName": "John",
            "locked":false,
+
      "lastName": "Doe",
            "type":"super"
+
      "enabled":true,
        },
+
      "locked":false,
        {
+
      "type":"super",
            "adminId":"apiadmin76",
+
      "email":"john.doe@example.com",
            "enabled":true,
+
      "twoFactorEnabled":true
            "locked":false,
+
    },
            "type":"super"
+
    {
        },
+
      "adminId":"apiadmin76",
        {
+
      "firstName": "Jane",
            "adminId":"apiadmin94",
+
      "lastName": "Doe",
            "enabled":true,
+
      "enabled":true,
            "locked":false,
+
      "locked":false,
            "type":"super"
+
      "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,
 
   "offset":0,
 
   "size":50,
 
   "size":50,
Line 95: Line 119:
 
=== Show ===
 
=== Show ===
  
''URL'':  
+
''URL'':
  
 
  <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
 
  <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)</nowiki>
Line 108: Line 132:
 
''Remarks'':
 
''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]
+
The show operation only supports the GET HTTP verb.
 
 
  
 
''Example'':
 
''Example'':
  
 
<pre>
 
<pre>
get '/customers/999999/admins/admin1', 'text/xml'
+
get '/customers/999999/admins/admin1'
 
</pre>
 
</pre>
  
Line 147: Line 170:
 
=== Add/Edit ===
 
=== Add/Edit ===
  
''URL'':  
+
''URL'':
 
  <nowiki>
 
  <nowiki>
 
  Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
 
  Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
Line 161: Line 184:
 
Add a new admin or edit an existing admin under the specified account.
 
Add a new admin or edit an existing admin under the specified account.
  
+
 
 
{| class="wikitable"
 
{| class="wikitable"
 
!''Field Name''
 
!''Field Name''
Line 220: Line 243:
  
 
<pre>
 
<pre>
post '/customers/999999/admins/admin1',  
+
post '/customers/999999/admins/admin1',
     {  
+
     {
 
       'type' => 'super',
 
       'type' => 'super',
 
       'password' => 'password',
 
       'password' => 'password',
Line 229: Line 252:
 
       'securityQuestion' => 'Q',
 
       'securityQuestion' => 'Q',
 
       'securityAnswer' => 'A'
 
       'securityAnswer' => 'A'
     },
+
     }
    'text/xml'
 
 
</pre>
 
</pre>
  
 
<pre>
 
<pre>
put '/customers/999999/admins/admin2',  
+
put '/customers/999999/admins/admin2',
     {  
+
     {
 
       'enabled' => 'true',
 
       'enabled' => 'true',
 
       'locked' => 'false',
 
       'locked' => 'false',
Line 241: Line 263:
 
       'allowSimultaneousLogins' => 'true',
 
       'allowSimultaneousLogins' => 'true',
 
       'restrictedIps' => '1.1.1.1'
 
       'restrictedIps' => '1.1.1.1'
     },
+
     }
    'text/xml'
 
 
</pre>
 
</pre>
  
Line 265: Line 286:
 
| IP addresses must be valid addresses separated by commas. A maximum of 3 addresses may be entered.
 
| IP addresses must be valid addresses separated by commas. A maximum of 3 addresses may be entered.
 
|}
 
|}
 
  
 
=== Delete ===
 
=== Delete ===
Line 279: Line 299:
 
Deletes the admin.
 
Deletes the admin.
  
+
 
 
''Example'':
 
''Example'':
  
 
<pre>
 
<pre>
delete '/customers/999999/admins/admin1', 'text/xml'
+
delete '/customers/999999/admins/admin1'
 
</pre>
 
</pre>
  
== v2 - Coming Soon ==
+
== v2 - Current ==
  
 
<!--
 
<!--
Line 313: Line 333:
  
  
''URL'':  
+
''Request'':
  
 
<pre>
 
<pre>
[GET] /v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey
+
GET '/v2/customers/me/admins/(admin ID)/twoFactorAuth/newKey', 'application/json'
Accept: application/json
 
 
</pre>
 
</pre>
  
  
''HTTP response'':
+
''Response'':
 
 
<code>200 OK</code> with a JSON response:
 
  
 
<pre>
 
<pre>
 +
200 OK
 
{
 
{
 
     "Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
 
     "Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
 
}
 
}
</pre>
 
 
 
''Example'':
 
 
<pre>
 
get '/v2/customers/me/admins/999999999/twoFactorAuth/newKey', 'application/json'
 
 
</pre>
 
</pre>
  
Line 347: Line 358:
  
  
''URL'':
+
''Request'':
  
 
<pre>
 
<pre>
[POST] /v2/customers/me/admins/(admin ID)/twoFactorAuth
+
POST /v2/customers/me/admins/(admin ID)/twoFactorAuth
Content-type: application/json
 
 
 
 
{
 
{
 
   "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
 
   "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
 
   "VerificationCode": "123456"
 
   "VerificationCode": "123456"
}
+
},
 +
'application/json'
 
</pre>
 
</pre>
  
  
''HTTP response'':  
+
''Response'':
  
 
<code>204 No Content</code>
 
<code>204 No Content</code>
 
 
''Example'':
 
 
<pre>
 
post '/v2/customers/me/admins/999999999/twoFactorAuth',
 
    {
 
        "SecretKey": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2",
 
        "VerificationCode": "123456"
 
    },
 
    'application/json'
 
</pre>
 
  
  
Line 385: Line 383:
  
  
''URL'':
+
''Request'':
 
<pre>
 
<pre>
 
POST /v2/customers/me/admins/reseller/twoFactorAuth
 
POST /v2/customers/me/admins/reseller/twoFactorAuth
Content-Type: application/json
 
 
 
{
 
{
 
   "Enabled": false
 
   "Enabled": false
}
+
},
 +
'application/json'
 
</pre>
 
</pre>
  
''HTTP response'':  
+
''Response'':
  
 
<code>204 No Content</code>
 
<code>204 No Content</code>
Line 403: Line 400:
  
 
<pre>
 
<pre>
post '/v2/customers/me/admins/999999999/twoFactorAuth',
+
post /v2/customers/me/admins/999999999/twoFactorAuth
 
     {
 
     {
 
         "Enabled": false
 
         "Enabled": false
Line 451: Line 448:
 
| Missing verification code
 
| Missing verification code
 
| 400 Bad Request
 
| 400 Bad Request
| Must send a "verificationCode" property.  
+
| Must send a "verificationCode" property.
 
|-
 
|-
 
| Secret key is invalid
 
| Secret key is invalid
Line 461: Line 458:
 
| Must send a "secretKey" property.
 
| Must send a "secretKey" property.
 
|-
 
|-
| Verification code contains a leading zero
+
| Verification code is an int
 
| 400 Bad Request
 
| 400 Bad Request
| The "verificationCode" value is not valid for the "secretKey" value. Enter a new verification code without a leading zero.
+
| Must send "verificationCode" as a string in quotes.
 +
|}
 +
 
 +
== v3 - Current ==
 +
 
 +
=== List ===
 +
''URL'':
 +
 
 +
<nowiki>[GET] https://api.emailsrvr.com/v3/customers/(customer account number)/admins</nowiki>
 +
<nowiki>[GET] https://api.emailsrvr.com/v3/admins</nowiki>
 +
 
 +
''Description'':
 +
 
 +
List administrators on an account.
 +
 
 +
''Query Params'':
 +
 
 +
{| class="wikitable"
 +
!''Param Name''
 +
!''Data Type''
 +
!''Description''
 +
|-
 +
| contains
 +
| string
 +
| filter list to match on user name, first name, last name, or email address
 +
|-
 +
| start
 +
| int
 +
| Paging parameter indicating the starting record. (Default: 0)
 +
|-
 +
| pageSize
 +
| int
 +
| The number of records from the overall result set that should be returned (Default: 10)
 +
|-
 +
| sortDirection
 +
| string
 +
| Direction to sort. (Default: 'asc')
 +
|-
 +
| sortProperty
 +
| string
 +
| Sort list by this property. Valid values are active, name (first + last), adminType, and primary. (Default: name)
 +
|-
 +
| username
 +
| string
 +
| Search specifically by username
 +
|-
 +
| primaryContact
 +
| boolean
 +
| Return only the primary contacts
 +
|-
 +
| notificationType
 +
| string list
 +
| Filter by the comma delimited list of notification types to include. Valid items: alerts, billing, updates
 +
|-
 
|}
 
|}
 +
 +
''JSON Response Example'':
 +
 +
<pre>
 +
{
 +
  "start": 0,
 +
  "pageSize": 50,
 +
  "sortDirection": "desc",
 +
  "sortProperty": "username",
 +
  "total": 2,
 +
  "contains": "",
 +
  "adminLimit": 20,
 +
  "results": [
 +
    {
 +
      "id": "a0910b79-b14d-4240-a5f5-2dc47e9a4beb",
 +
      "firstName": "Jane",
 +
      "lastName": "Doe",
 +
      "userName": "jane.doe",
 +
      "adminType": "Standard",
 +
      "emailAddress": "jane.doe@example.com",
 +
      "phoneNumber": "555-555-1234",
 +
      "lastLogin": "2018-08-22T13:34:55.000Z",
 +
      "securityQuestions": [
 +
        {
 +
          "question": "Question 1?"
 +
        },
 +
        {
 +
          "question": "Question 2?"
 +
        }
 +
      ],
 +
      "isActive": true,
 +
      "primaryContact": true
 +
    },
 +
    {
 +
      "id": "cc073092-9ee9-4771-9e16-6ffcf11c0c73",
 +
      "firstName": "Ralph",
 +
      "lastName": "Doe",
 +
      "userName": "ralph.doe",
 +
      "adminType": "Standard",
 +
      "emailAddress": "jane.doe@example.com",
 +
      "phoneNumber": "555-555-1234",
 +
      "lastLogin": "2018-08-22T07:34:55.000Z",
 +
      "securityQuestions": [],
 +
      "isActive": false,
 +
      "primaryContact": true
 +
    }
 +
  ]
 +
}
 +
</pre>
 +
 +
=== Read ===
 +
''URL'':
 +
 +
<nowiki>[GET] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(adminId)</nowiki>
 +
<nowiki>[GET] https://api.emailsrvr.com/v3/admins/(adminId)</nowiki>
 +
 +
''Description'':
 +
 +
Get a single administrator by their Id.
 +
 +
''JSON Response Example'':
 +
<pre>
 +
{
 +
  "id": "a0910b79-b14d-4240-a5f5-2dc47e9a4beb",
 +
  "firstName": "Jane",
 +
  "lastName": "Doe",
 +
  "userName": "jane.doe",
 +
  "adminType": "Standard",
 +
  "emailAddress": "jane.doe@example.com",
 +
  "phoneNumber": "555-555-1234",
 +
  "isActive": true,
 +
  "isLocked": false,
 +
  "lastLogin": "2018-09-11T13:11:41.000Z",
 +
  "lastVerified": "2018-09-11T13:11:41.000Z",
 +
  "title": "",
 +
  "ipAllowed": [
 +
    "192.168.14.22"
 +
  ],
 +
  "numFailedLogin": 1,
 +
  "multifactorRequired": false,
 +
  "passwordExpirationInDays": 30,
 +
  "passwordLastModified": "2018-09-11T13:11:41.000Z",
 +
  "primaryContact": true,
 +
  "alerts": true,
 +
  "billing": true,
 +
  "updates": true,
 +
  "securityQuestions": [
 +
    {
 +
      "question": "Question 1?"
 +
    },
 +
    {
 +
      "question": "Question 2?"
 +
    }
 +
  ]
 +
}
 +
</pre>
 +
 +
=== Create ===
 +
 +
''Description'':
 +
 +
Create a new administrator
 +
 +
 +
''Request'':
 +
 +
<pre>
 +
[POST] https://api.emailsrvr.com/v3/customers/(customer account number)/admins
 +
{
 +
  "accountNumber": "12345",
 +
  "firstName": "Jane",
 +
  "lastName": "Doe",
 +
  "userName": "jane.doe",
 +
  "adminType": "Standard",
 +
  "emailAddress": "jane.doe@example.com",
 +
  "phoneNumber": "555-555-1234",
 +
  "securityQuestion": "",
 +
  "securityAnswer": "",
 +
  "multifactorRequired": true,
 +
  "ipAllowed": [
 +
    "192.168.34.2"
 +
  ],
 +
  "authorizationClaims": [
 +
    {
 +
      "category": "email-hosting",
 +
      "claim": "aliases"
 +
    },
 +
    {
 +
      "category": "domain",
 +
      "claim": "braineaters.org"
 +
    }
 +
  ],
 +
  "password": "Asdfasdf1",
 +
  "primaryContact": true,
 +
  "alerts": true,
 +
  "billing": true,
 +
  "updates": true
 +
}
 +
</pre>
 +
 +
''Response'':
 +
<pre>
 +
200 OK
 +
{
 +
  "id": "admin12"
 +
}
 +
</pre>
 +
 +
=== Update ===
 +
 +
''Description'':
 +
 +
Update an administrator. Fields not included will not be updated.
 +
 +
''Request'':
 +
 +
<pre>
 +
[PUT] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(administrator id)
 +
{
 +
  "firstName": "Jane",
 +
  "lastName": "Doe",
 +
  "adminType": "Standard",
 +
  "emailAddress": "jane.doe@example.com",
 +
  "phoneNumber": "555-555-1234",
 +
  "securityQuestion": "",
 +
  "securityAnswer": "",
 +
  "isActive": true,
 +
  "lastVerified": "2015-01-01T22:23:54.000Z",
 +
  "ipAllowed": [
 +
    "127.0.0.1"
 +
  ],
 +
  "passwordExpirationInDays": 30,
 +
  "primaryContact": true,
 +
  "alerts": true,
 +
  "billing": true,
 +
  "updates": true,
 +
  "authorizationClaims": {
 +
    "allow": [
 +
      {
 +
        "category": "email-hosting",
 +
        "claim": "aliases"
 +
      },
 +
      {
 +
        "category": "domain",
 +
        "claim": "braineaters.org"
 +
      }
 +
    ],
 +
    "deny": []
 +
  },
 +
  "deleteContactQuestion": true
 +
}
 +
</pre>
 +
 +
''Response'':
 +
 +
<pre>
 +
204 No Content
 +
</pre>
 +
 +
=== Delete ===
 +
 +
''Description'':
 +
 +
Delete an administrator.
 +
 +
''Request'':
 +
 +
<pre>
 +
[DELETE] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(administrator id)
 +
</pre>
 +
 +
''Response'':
 +
 +
<pre>
 +
204 No Content
 +
</pre>

Latest revision as of 07:14, 2 July 2019

v1 - Current

Index

URL:

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


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. 'https://api.emailsrvr.com/v1/customers/me/domains'.

The index operation only supports the GET HTTP verb.


Example:

get '/customers/999999/admins?size=5&page=1'


XML Result Example:

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


Json Result Example:

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

Show

URL:

[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[GET] https://api.emailsrvr.com/v1/admins/(admin name)


Description:

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


Remarks:

The show operation only supports the GET HTTP verb.

Example:

get '/customers/999999/admins/admin1'

XML Result Example:

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


Json Result Example:

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

Add/Edit

URL:

 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)
 


Description:

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


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:

post '/customers/999999/admins/admin1',
     {
       'type' => 'super',
       'password' => 'password',
       'firstName' => 'First',
       'lastName' => 'Last',
       'email' => 'first.last@rackspace.com',
       'securityQuestion' => 'Q',
       'securityAnswer' => 'A'
     }
put '/customers/999999/admins/admin2',
     {
       'enabled' => 'true',
       'locked' => 'false',
       'passwordExpiration' => '0',
       'allowSimultaneousLogins' => 'true',
       'restrictedIps' => '1.1.1.1'
     }


Errors:

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:

[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/admins/(admin name)
[DELETE] https://api.emailsrvr.com/v1/admins/(admin name)


Description:

Deletes the admin.


Example:

delete '/customers/999999/admins/admin1'

v2 - Current

Enable and Disable Two-Factor Authentication

Enabling two-factor authentication requires installing [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 [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:

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


Response:

200 OK
{
    "Key": "YZ2DHHG5TFC47COKWLQ3GB3Y5RDRG4Q2"
}


Enable Two-Factor Authentication

Description:

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


Request:

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


Response:

204 No Content


Disable Two-Factor Authentication

Description:

Disable two-factor authentication for an admin.


Request:

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

Response:

204 No Content


Example:

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


Errors for GET requests

Description HTTP Response Code Sample Message
Invalid method 404 Not Found Make sure the URL is correct. (Did you include /newKey in the path?)


Errors for POST requests

Description HTTP Response Code Sample Message
Invalid method (GET requests only) 404 Not Found Make sure the URL is correct. (Did you include /newKey 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 application/json.
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.

v3 - Current

List

URL:

[GET] https://api.emailsrvr.com/v3/customers/(customer account number)/admins
[GET] https://api.emailsrvr.com/v3/admins

Description:

List administrators on an account.

Query Params:

Param Name Data Type Description
contains string filter list to match on user name, first name, last name, or email address
start int Paging parameter indicating the starting record. (Default: 0)
pageSize int The number of records from the overall result set that should be returned (Default: 10)
sortDirection string Direction to sort. (Default: 'asc')
sortProperty string Sort list by this property. Valid values are active, name (first + last), adminType, and primary. (Default: name)
username string Search specifically by username
primaryContact boolean Return only the primary contacts
notificationType string list Filter by the comma delimited list of notification types to include. Valid items: alerts, billing, updates

JSON Response Example:

{
  "start": 0,
  "pageSize": 50,
  "sortDirection": "desc",
  "sortProperty": "username",
  "total": 2,
  "contains": "",
  "adminLimit": 20,
  "results": [
    {
      "id": "a0910b79-b14d-4240-a5f5-2dc47e9a4beb",
      "firstName": "Jane",
      "lastName": "Doe",
      "userName": "jane.doe",
      "adminType": "Standard",
      "emailAddress": "jane.doe@example.com",
      "phoneNumber": "555-555-1234",
      "lastLogin": "2018-08-22T13:34:55.000Z",
      "securityQuestions": [
        {
          "question": "Question 1?"
        },
        {
          "question": "Question 2?"
        }
      ],
      "isActive": true,
      "primaryContact": true
    },
    {
      "id": "cc073092-9ee9-4771-9e16-6ffcf11c0c73",
      "firstName": "Ralph",
      "lastName": "Doe",
      "userName": "ralph.doe",
      "adminType": "Standard",
      "emailAddress": "jane.doe@example.com",
      "phoneNumber": "555-555-1234",
      "lastLogin": "2018-08-22T07:34:55.000Z",
      "securityQuestions": [],
      "isActive": false,
      "primaryContact": true
    }
  ]
}

Read

URL:

[GET] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(adminId)
[GET] https://api.emailsrvr.com/v3/admins/(adminId)

Description:

Get a single administrator by their Id.

JSON Response Example:

{
  "id": "a0910b79-b14d-4240-a5f5-2dc47e9a4beb",
  "firstName": "Jane",
  "lastName": "Doe",
  "userName": "jane.doe",
  "adminType": "Standard",
  "emailAddress": "jane.doe@example.com",
  "phoneNumber": "555-555-1234",
  "isActive": true,
  "isLocked": false,
  "lastLogin": "2018-09-11T13:11:41.000Z",
  "lastVerified": "2018-09-11T13:11:41.000Z",
  "title": "",
  "ipAllowed": [
    "192.168.14.22"
  ],
  "numFailedLogin": 1,
  "multifactorRequired": false,
  "passwordExpirationInDays": 30,
  "passwordLastModified": "2018-09-11T13:11:41.000Z",
  "primaryContact": true,
  "alerts": true,
  "billing": true,
  "updates": true,
  "securityQuestions": [
    {
      "question": "Question 1?"
    },
    {
      "question": "Question 2?"
    }
  ]
}

Create

Description:

Create a new administrator


Request:

[POST] https://api.emailsrvr.com/v3/customers/(customer account number)/admins
{
  "accountNumber": "12345",
  "firstName": "Jane",
  "lastName": "Doe",
  "userName": "jane.doe",
  "adminType": "Standard",
  "emailAddress": "jane.doe@example.com",
  "phoneNumber": "555-555-1234",
  "securityQuestion": "",
  "securityAnswer": "",
  "multifactorRequired": true,
  "ipAllowed": [
    "192.168.34.2"
  ],
  "authorizationClaims": [
    {
      "category": "email-hosting",
      "claim": "aliases"
    },
    {
      "category": "domain",
      "claim": "braineaters.org"
    }
  ],
  "password": "Asdfasdf1",
  "primaryContact": true,
  "alerts": true,
  "billing": true,
  "updates": true
}

Response:

200 OK
{
  "id": "admin12"
}

Update

Description:

Update an administrator. Fields not included will not be updated.

Request:

[PUT] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(administrator id)
{
  "firstName": "Jane",
  "lastName": "Doe",
  "adminType": "Standard",
  "emailAddress": "jane.doe@example.com",
  "phoneNumber": "555-555-1234",
  "securityQuestion": "",
  "securityAnswer": "",
  "isActive": true,
  "lastVerified": "2015-01-01T22:23:54.000Z",
  "ipAllowed": [
    "127.0.0.1"
  ],
  "passwordExpirationInDays": 30,
  "primaryContact": true,
  "alerts": true,
  "billing": true,
  "updates": true,
  "authorizationClaims": {
    "allow": [
      {
        "category": "email-hosting",
        "claim": "aliases"
      },
      {
        "category": "domain",
        "claim": "braineaters.org"
      }
    ],
    "deny": []
  },
  "deleteContactQuestion": true
}

Response:

204 No Content

Delete

Description:

Delete an administrator.

Request:

[DELETE] https://api.emailsrvr.com/v3/customers/(customer account number)/admins/(administrator id)

Response:

204 No Content