View source for Rackspace Mailbox (Rest API)

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