Difference between revisions of "Exchange Contact (Rest API)"

From Rackspace Email & Apps API
Jump to: navigation, search
m
(remove accept header from examples to avoid confusion)
 
(17 intermediate revisions by 4 users not shown)
Line 1: Line 1:
−
[[PageOutline]]
+
__TOC__
  
−
== Contact ==
+
== v1 - Current ==
  
 
=== Index ===
 
=== Index ===
  
 
''URL'':
 
''URL'':
−
  [GET] /customers/(customer account number)/domains/(domain name)/ex/contacts
+
  <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
 +
        /ex/contacts</nowiki>
  
  
Line 13: Line 14:
 
Returns a list of contacts under the domain.
 
Returns a list of contacts under the domain.
  
 +
''Example'':
 +
<pre>
 +
get '/customers/12345678/domains/example.com/ex/contacts?contains=john'
 +
</pre>
  
−
''Remarks'':
 
−
 
−
For the text/xml format, refer to the following schema document: [https://trac.iad.mlsrvr.com/trac/controlpanel3/browser/Api/trunk/lib/ControlPanel.Api/Schemas/Contacts.xsd Contacts.xsd]
 
  
 +
''XML Result Example'':
  
−
''Example'':
 
 
<pre>
 
<pre>
−
get '/customers/12345678/domains/example.com/ex/contacts?size=100&page=1&contains=john', 'text/xml'
+
<?xml version="1.0" encoding="utf-8"?>
 +
<contactList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contactList">
 +
  <offset>0</offset>
 +
  <size>50</size>
 +
  <total>3</total>
 +
  <contacts>
 +
    <contact>
 +
      <name>apiexcontact66</name>
 +
      <displayName>API Test</displayName>
 +
      <externalEmail>externalemail58@yahoo.com</externalEmail>
 +
    </contact>
 +
    <contact>
 +
      <name>apiexcontact73</name>
 +
      <displayName>API Test</displayName>
 +
      <externalEmail>externalemail98@yahoo.com</externalEmail>
 +
    </contact>
 +
    <contact>
 +
      <name>apiexcontact81</name>
 +
      <displayName>API Test</displayName>
 +
      <externalEmail>externalemail46@yahoo.com</externalEmail>
 +
    </contact>
 +
  </contacts>
 +
</contactList>
 
</pre>
 
</pre>
  
  
−
''Errors'':
+
''Json Result Example'':
−
 
 
−
{| border=1 class="simple"
 
−
!''Description''
 
−
!''HTTP Response Code''
 
−
!''Sample Message''
 
−
|-
 
−
| Format is invalid
 
−
| 406
 
−
| Invalid format
 
−
|-
 
−
| Domain is not found
 
−
| 404
 
−
| abc.com not found
 
−
|}
 
  
 +
{"offset":0,"size":50,"total":3,"contacts":[{"name":"apiexcontact66","displayName":"API Test","externalEmail":"externalemail58@yahoo.com"},{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com"},{"name":"apiexcontact81","displayName":"API Test","externalEmail":"externalemail46@yahoo.com"}]}
  
 
=== Show ===
 
=== Show ===
  
 
''URL'':
 
''URL'':
−
  [GET] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name)
+
  <nowiki>[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
 +
        /ex/contacts/(contact name)</nowiki>
  
  
Line 53: Line 65:
  
  
−
''Remarks'':
+
''Example'':
 +
<pre>
 +
get '/customers/12345678/domains/example.com/ex/contacts/alex.smith'
 +
</pre>
  
−
For the text/xml format, refer to the following schema document: [https://trac.iad.mlsrvr.com/trac/controlpanel3/browser/Api/trunk/lib/ControlPanel.Api/Schemas/Contact.xsd Contact.xsd]
 
  
 +
''XML Result Example'':
  
−
''Example'':
 
 
<pre>
 
<pre>
−
get '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
+
<?xml version="1.0" encoding="utf-8"?>
 +
<contact xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contact">
 +
  <name>apiexcontact73</name>
 +
  <displayName>API Test</displayName>
 +
  <externalEmail>externalemail98@yahoo.com</externalEmail>
 +
  <isHidden>false</isHidden>
 +
  <contactInfo>
 +
    <firstName>API</firstName>
 +
    <lastName>Test</lastName>
 +
    <jobTitle>Dev</jobTitle>
 +
    <company>My Company</company>
 +
    <department>R&amp;D</department>
 +
    <businessNumber>111-1111</businessNumber>
 +
    <homeNumber>222-2222</homeNumber>
 +
    <mobileNumber>333-3333</mobileNumber>
 +
    <faxNumber>444-4444</faxNumber>
 +
    <pagerNumber>1234</pagerNumber>
 +
    <addressLine1>123 Main Street</addressLine1>
 +
    <city>Blacksburg</city>
 +
    <state>VA</state>
 +
    <zip>24060</zip>
 +
    <country>USA</country>
 +
    <notes>My Notes</notes>
 +
  </contactInfo>
 +
</contact>
 
</pre>
 
</pre>
 +
 +
 +
''Json Result Example'':
 +
 +
{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com","isHidden":false,"contactInfo":{"firstName":"API","lastName":"Test","jobTitle":"Dev","company":"My Company","department":"R&D","businessNumber":"111-1111","homeNumber":"222-2222","mobileNumber":"333-3333","faxNumber":"444-4444","pagerNumber":"1234","addressLine1":"123 Main Street","city":"Blacksburg","state":"VA","zip":"24060","country":"USA","notes":"My Notes"}}
  
  
 
''Errors'':
 
''Errors'':
  
−
{| border=1 class="simple"
+
{| class="wikitable"
 
!''Description''
 
!''Description''
 
!''HTTP Response Code''
 
!''HTTP Response Code''
 
!''Sample Message''
 
!''Sample Message''
−
|-
+
|-
−
| Format is invalid
 
−
| 406
 
−
| Invalid format
 
−
|-
 
−
| Domain is not found
 
−
| 404
 
−
| abc.com not found
 
−
|-  
 
 
| Contact is not found
 
| Contact is not found
 
| 404
 
| 404
 
| Contact not found
 
| Contact not found
 
|}
 
|}
−
 
  
 
=== Add/Edit ===
 
=== Add/Edit ===
  
 
''URL'':
 
''URL'':
−
  Add: [POST] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name)<br>
+
  <nowiki>Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
−
Edit: [PUT] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name)
+
                /ex/contacts/(contact name)
 +
 
 +
Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
 +
                /ex/contacts/(contact name)</nowiki>
  
  
Line 97: Line 134:
  
  
−
{| border=1 class="simple"
+
{| class="wikitable"
 
!''Field Name''
 
!''Field Name''
 
!''Data Type''
 
!''Data Type''
 
!''Description''
 
!''Description''
−
|-  
+
|-
 
| displayName
 
| displayName
 
| string
 
| string
 
| Name of contact when displayed (Required for add)
 
| Name of contact when displayed (Required for add)
−
|-  
+
|-
 
| externalEmail
 
| externalEmail
 
| string
 
| string
 
| Email address (Required for add)
 
| Email address (Required for add)
−
|-  
+
|-
 
| isHidden
 
| isHidden
 
| boolean
 
| boolean
 
| Whether the contact is hidden from the Global List
 
| Whether the contact is hidden from the Global List
−
|-  
+
|-
 
| firstName
 
| firstName
 
| string
 
| string
 
| First name
 
| First name
−
|-  
+
|-
 
| lastName
 
| lastName
 
| string
 
| string
 
| Last name
 
| Last name
−
|-  
+
|-
 
| jobTitle
 
| jobTitle
 
| string
 
| string
 
| Job title
 
| Job title
−
|-  
+
|-
 
| company
 
| company
 
| string
 
| string
 
| Company
 
| Company
−
|-  
+
|-
 
| department
 
| department
 
| string
 
| string
 
| Department
 
| Department
−
|-  
+
|-
−
| businessnumber
+
| businessNumber
 
| string
 
| string
 
| Business phone number
 
| Business phone number
−
|-  
+
|-
−
| homenumber
+
| homeNumber
 
| string
 
| string
 
| Home phone number
 
| Home phone number
−
|-  
+
|-
−
| mobilenumber
+
| mobileNumber
 
| string
 
| string
 
| Mobile phone number
 
| Mobile phone number
−
|-  
+
|-
−
| faxnumber
+
| faxNumber
 
| string
 
| string
 
| Fax number
 
| Fax number
−
|-  
+
|-
−
| pagernumber
+
| pagerNumber
 
| string
 
| string
 
| Pager number
 
| Pager number
−
|-  
+
|-
 
| addressLine1
 
| addressLine1
 
| string
 
| string
 
| Street address
 
| Street address
−
|-  
+
|-
 
| city
 
| city
 
| string
 
| string
 
| City
 
| City
−
|-  
+
|-
 
| state
 
| state
 
| string
 
| string
 
| State
 
| State
−
|-  
+
|-
 
| zip
 
| zip
 
| string
 
| string
 
| Zip or postal code
 
| Zip or postal code
−
|-  
+
|-
 
| country
 
| country
 
| string
 
| string
 
| Country
 
| Country
−
|-  
+
|-
 
| notes
 
| notes
 
| string
 
| string
Line 182: Line 219:
 
''Example'':
 
''Example'':
 
<pre>
 
<pre>
−
post '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml',
+
post '/customers/12345678/domains/example.com/ex/contacts/alex.smith',
 
{
 
{
 
   'displayName' => 'Johnny Customer',
 
   'displayName' => 'Johnny Customer',
−
   'externalEmail' => 'jonny@apple.com'  
+
   'externalEmail' => 'jonny@apple.com'
 
}
 
}
 
</pre>
 
</pre>
  
 
<pre>
 
<pre>
−
put '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml',
+
put '/customers/12345678/domains/example.com/ex/contacts/alex.smith',
 
{
 
{
 
   'externalEmail' => 'jonnysNewEmail@microsoft.com',
 
   'externalEmail' => 'jonnysNewEmail@microsoft.com',
 
   'company' => 'Microsoft',
 
   'company' => 'Microsoft',
−
   'businessnumber' => '425 555 5555'  
+
   'businessnumber' => '425 555 5555'
 
}
 
}
 
</pre>
 
</pre>
Line 201: Line 238:
 
''Errors'':
 
''Errors'':
  
−
{| border=1 class="simple"
+
{| class="wikitable"
 
!''Description''
 
!''Description''
 
!''HTTP Response Code''
 
!''HTTP Response Code''
 
!''Sample Message''
 
!''Sample Message''
−
|-
+
|-
−
| Format is invalid
 
−
| 406
 
−
| Invalid format
 
−
|-
 
−
| Domain is not found
 
−
| 404
 
−
| abc.com not found
 
−
|-  
 
 
| Contact is not found
 
| Contact is not found
 
| 404
 
| 404
 
| No user with the email address jane.doe@abc.com exists
 
| No user with the email address jane.doe@abc.com exists
−
|-  
+
|-
 
| New display name doesn't meet the naming requirements
 
| New display name doesn't meet the naming requirements
 
| 400
 
| 400
 
| Invalid display name
 
| Invalid display name
−
|-
+
|-
−
| Boolean form field has non-boolean input
 
−
| 400
 
−
| Invalid format for Enabled, input must be True or False
 
−
|-
 
−
| Form data has unrecognized field
 
−
| 400
 
−
| Unrecognized field: size
 
−
|-
 
−
| Required form field is missing
 
−
| 400
 
−
| Missing required field: displayName
 
−
|-
 
−
| Required form field has null or empty string input
 
−
| 400
 
−
| Required field displayName cannot be empty
 
−
|-  
 
 
| New display name doesn't meet the naming requirements
 
| New display name doesn't meet the naming requirements
 
| 400
 
| 400
 
| Invalid display name
 
| Invalid display name
−
|-  
+
|-
 
| New contact name (user name) already exists
 
| New contact name (user name) already exists
 
| 400
 
| 400
 
| The email address john.doe@abc.com is already in use
 
| The email address john.doe@abc.com is already in use
−
|-  
+
|-
 
| New contact name (user name) is reserved by Exchange
 
| New contact name (user name) is reserved by Exchange
 
| 400
 
| 400
Line 255: Line 268:
  
 
''URL'':
 
''URL'':
−
  [DELETE] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name)
+
  <nowiki>[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
 +
            /ex/contacts/(contact name)</nowiki>
  
  
Line 270: Line 284:
 
''Example'':
 
''Example'':
 
<pre>
 
<pre>
−
delete '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
+
delete '/customers/12345678/domains/example.com/ex/contacts/alex.smith'
 
</pre>
 
</pre>
  
 
''Errors'':
 
''Errors'':
  
−
{| border=1 class="simple"
+
{| class="wikitable"
 
!''Description''
 
!''Description''
 
!''HTTP Response Code''
 
!''HTTP Response Code''
 
!''Sample Message''
 
!''Sample Message''
−
|-
+
|-
−
| Domain is not found
 
−
| 404
 
−
| abc.com not found
 
−
|-  
 
 
| Contact is not found
 
| Contact is not found
 
| 404
 
| 404
 
| No user with the email address jane.doe@abc.com exists
 
| No user with the email address jane.doe@abc.com exists
 
|}
 
|}

Latest revision as of 13:48, 12 January 2017

v1 - Current

Index

URL: 

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


Description:

Returns a list of contacts under the domain.

Example: 

get '/customers/12345678/domains/example.com/ex/contacts?contains=john'


XML Result Example: 

<?xml version="1.0" encoding="utf-8"?>
<contactList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contactList">
  <offset>0</offset>
  <size>50</size>
  <total>3</total>
  <contacts>
    <contact>
      <name>apiexcontact66</name>
      <displayName>API Test</displayName>
      <externalEmail>externalemail58@yahoo.com</externalEmail>
    </contact>
    <contact>
      <name>apiexcontact73</name>
      <displayName>API Test</displayName>
      <externalEmail>externalemail98@yahoo.com</externalEmail>
    </contact>
    <contact>
      <name>apiexcontact81</name>
      <displayName>API Test</displayName>
      <externalEmail>externalemail46@yahoo.com</externalEmail>
    </contact>
  </contacts>
</contactList>


Json Result Example:

{"offset":0,"size":50,"total":3,"contacts":[{"name":"apiexcontact66","displayName":"API Test","externalEmail":"externalemail58@yahoo.com"},{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com"},{"name":"apiexcontact81","displayName":"API Test","externalEmail":"externalemail46@yahoo.com"}]}

Show

URL: 

[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
        /ex/contacts/(contact name)


Description:

Returns the contact's details.


Example: 

get '/customers/12345678/domains/example.com/ex/contacts/alex.smith'


XML Result Example: 

<?xml version="1.0" encoding="utf-8"?>
<contact xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:contact">
  <name>apiexcontact73</name>
  <displayName>API Test</displayName>
  <externalEmail>externalemail98@yahoo.com</externalEmail>
  <isHidden>false</isHidden>
  <contactInfo>
    <firstName>API</firstName>
    <lastName>Test</lastName>
    <jobTitle>Dev</jobTitle>
    <company>My Company</company>
    <department>R&D</department>
    <businessNumber>111-1111</businessNumber>
    <homeNumber>222-2222</homeNumber>
    <mobileNumber>333-3333</mobileNumber>
    <faxNumber>444-4444</faxNumber>
    <pagerNumber>1234</pagerNumber>
    <addressLine1>123 Main Street</addressLine1>
    <city>Blacksburg</city>
    <state>VA</state>
    <zip>24060</zip>
    <country>USA</country>
    <notes>My Notes</notes>
  </contactInfo>
</contact>


Json Result Example:

{"name":"apiexcontact73","displayName":"API Test","externalEmail":"externalemail98@yahoo.com","isHidden":false,"contactInfo":{"firstName":"API","lastName":"Test","jobTitle":"Dev","company":"My Company","department":"R&D","businessNumber":"111-1111","homeNumber":"222-2222","mobileNumber":"333-3333","faxNumber":"444-4444","pagerNumber":"1234","addressLine1":"123 Main Street","city":"Blacksburg","state":"VA","zip":"24060","country":"USA","notes":"My Notes"}}


Errors:

Description HTTP Response Code Sample Message
Contact is not found 404 Contact not found

Add/Edit

URL: 

Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
                /ex/contacts/(contact name)

Edit: [PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
                /ex/contacts/(contact name)


Description:

Adds or edits the contact's details as specified. If the contact does not exist, use Add, if it does, use Edit.


Field Name Data Type Description
displayName string Name of contact when displayed (Required for add)
externalEmail string Email address (Required for add)
isHidden boolean Whether the contact is hidden from the Global List
firstName string First name
lastName string Last name
jobTitle string Job title
company string Company
department string Department
businessNumber string Business phone number
homeNumber string Home phone number
mobileNumber string Mobile phone number
faxNumber string Fax number
pagerNumber string Pager number
addressLine1 string Street address
city string City
state string State
zip string Zip or postal code
country string Country
notes string Notes field


Example: 

post '/customers/12345678/domains/example.com/ex/contacts/alex.smith',
{
  'displayName' => 'Johnny Customer',
  'externalEmail' => 'jonny@apple.com'
}

put '/customers/12345678/domains/example.com/ex/contacts/alex.smith',
{
  'externalEmail' => 'jonnysNewEmail@microsoft.com',
  'company' => 'Microsoft',
  'businessnumber' => '425 555 5555'
}


Errors:

Description HTTP Response Code Sample Message
Contact is not found 404 No user with the email address jane.doe@abc.com exists
New display name doesn't meet the naming requirements 400 Invalid display name
New display name doesn't meet the naming requirements 400 Invalid display name
New contact name (user name) already exists 400 The email address john.doe@abc.com is already in use
New contact name (user name) is reserved by Exchange 400 user name reserved


Delete

URL: 

[DELETE] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
            /ex/contacts/(contact name)


Description:

Deletes the contact.


Remarks:

Contact is deleted immediately without verification and data is lost permanently.


Example: 

delete '/customers/12345678/domains/example.com/ex/contacts/alex.smith'

Errors:

Description HTTP Response Code Sample Message
Contact is not found 404 No user with the email address jane.doe@abc.com exists
Retrieved from "http://api-wiki.apps.rackspace.com/api-wiki/index.php?title=Exchange_Contact_(Rest_API)&oldid=734"