Rackspace Email & Apps API - User contributions [en]

Domain (Rest API)

2009-08-30T08:10:50Z

Brian.hartsock:

== Domain ==

=== Index ===

''URL'':

[GET] /customers/(customer account number)/domains

''Description'':

This operation returns a list of domains under the account. If a customer account is specified, then a list of domains under that specific account will be returned.

''Remarks'':

Keyword "me" can be used as customer account number to retrieve reseller's own domain list. Similarly, keyword "all" can be used retrieve reseller's own domains and all sub-accounts' domains.

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

''Example'':

<pre>
get '/customers/all/domains?size=100&page=1', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Customer account number is invalid
| 404
| Invalid account number
|}

=== Show ===

''URL'':

[GET] /customers/(customer account number)/domains/(domain name)

''Description'':

The show operation will return detailed information about the specified domain name.

''Remarks'':

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

''Example'':

<pre>
get '/customers/999999/domains/example.com', 'text/xml'
</pre>

''Errors'':

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

=== Add/Edit ===

''URL'':

Add: [POST] /customers/(customer account number)/domains/(domain name) 
Edit: [PUT] /customers/(customer account number)/domains/(domain name)

''Description'':

Adds/edits a new domain to the account with the data specified. To add a domain to your own account, use your own account id.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| serviceType
| string
| Domain service type. "rsemail" = "Rackspace Email Only". "exchange" = "Exchange Only". "both" = "Rackspace Email and Exchange"
|-
| exchangeExtraStorage
| int
| Exchange service extra storage in megabytes
|-
| exchangeMaxNumMailboxes
| int
| Maximum number of mailboxes allowed under the domain Exchange service. Required for Adding Exchange service
|-
| rsEmailBaseMailboxSize
| int
| Rackspace Email base mailbox size in megabytes
|-
| rsEmailMaxNumberMailboxes
| int
| Maximum number of mailboxes allowed under the domain Rackspace Email service. Required for Adding Rackspace Email service
|-
| rsEmailExtraStorage
| int
| Rackspace Email service extra storage in megabytes
|-
| hasArchivingService
| boolean
| Enable or disable domain archiving service
|-
|}

''Example'':

<pre>
post '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '5',
'extraStorage' => '1024'
}
</pre>

<pre>
put '/customers/123455/domains/newcompany.com', 'text/xml',
{
'maxNumMailboxes' => '25',
'extraStorage' => '2048'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Customer account number is invalid
| 404
| Invalid account number
|-
| Form data has unrecognized field
| 400
| Unrecognized field: size
|-
| Required form field is missing
| 400
| Missing required field: maxNumMailboxes
|-
| Required form field has null or empty string input
| 400
| Required field name cannot be empty
|-
| Integer form field has non-integer input
| 400
| Invalid format for maxNumMailboxes, input must be an integer
|-
| New domain name doesn't meet the naming requirements
| 400
| Invalid domain name
|-
| New domain name already exists
| 400
| abc.com already exists as a domain or alternate domain
|}

=== Move ===

''URL'':

[PUT] /customers/(new customer account number)/domains/(domain name)

''Description'':

Moves the domain to another customer account.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| moveDomain
| boolean
| Indicate whether or not moving the domain
|}

''Remarks'':

Note 'Move Domain' and 'Edit Domain' share the same URI and HTTP verb. When the domain doesn't belong to the customer and 'moveDomain' is set to 'true', API will take the request as a 'Move Domain' call.

''Example'':

<pre>
put '/customers/123456/domains/newcompany.com', 'text/xml',
{
'moveDomain' => 'true'
}
</pre>

''Errors'':

{| 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
|-
| Customer is not found
| 404
| Customer not found
|}

=== Delete ===

''URL'':

[DELETE] /customers/(customer account number)/domains/(domain name)

''Description'':

Deletes the domain.

''Remarks'':

The domain and all the mailboxes, mailbox contents, groups, and contacts are deleted permanently.

''Example'':

<pre>
delete '/customers/12345678/domains/newcompany.com', 'text/xml'
</pre>

''Errors'':

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

=== Archiving SSO Login URL ===

''URL'':

[GET] /customers/(customer account number)/domains/(domain)/archivingSSOLoginURL

''Description'':

Gets the domain archiving service SSO login URL.

''Remarks'':

The retrieved URL can be used in browser to access the domain archiving control panel.

''Example'':

<pre>
get '/customers/12345678/domains/company.com/archivingSSOLoginURL', 'text/xml'
</pre>

''Errors'':

{| 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
|-
| No archiving service
| 404
| Domain abc.com has no archiving service enabled
|}

Exchange Contact (Rest API)

2009-08-30T07:05:46Z

Brian.hartsock:

== Exchange Contact ==

=== Index ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/contacts

''Description'':

Returns a list of contacts under the domain.

''Remarks'':

For the text/xml format, refer to the following schema document: [Contacts.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts?size=100&page=1&contains=john', 'text/xml'
</pre>

''Errors'':

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

=== Show ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name)

''Description'':

Returns the contact's details.

''Remarks'':

For the text/xml format, refer to the following schema document: [Contact.xsd]

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

''Errors'':

{| 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
|-
| Contact is not found
| 404
| Contact not found
|}

=== Add/Edit ===

''URL'':
Add: [POST] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name) 
Edit: [PUT] /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.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Name of contact when displayed (Required for add)
|-
| externalEmail
| string
| Email address (Required for add)
|-
| isHidden
| boolean
| Whether the contact is hidden from the Global List
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| jobTitle
| string
| Job title
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| businessnumber
| string
| Business phone number
|-
| homenumber
| string
| Home phone number
|-
| mobilenumber
| string
| Mobile phone number
|-
| faxnumber
| string
| Fax number
|-
| pagernumber
| string
| Pager number
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| notes
| string
| Notes field
|}

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

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

''Errors'':

{| 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
|-
| 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
|-
| 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
| 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] /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'':
<pre>
delete '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Contact is not found
| 404
| No user with the email address jane.doe@abc.com exists
|}

Exchange Distribution List (Rest API)

2009-08-30T07:05:33Z

Brian.hartsock:

== Exchange Distribution List ==

=== Index ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/distributionlists

''Description'':

This operation returns a list of distribution lists associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [Groups.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists?size=100&page=1&contains=mailing', 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution List is not found
| 404
| Distribution List not found
|}

=== Show ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)

''Description'':

Returns the distribution list's details.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [Group.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Add/Edit ===

''URL'':
Add: [POST] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)
Edit: [PUT] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)

''Description'':

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

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| name
| string
| Distribution list name (Required for Add, not available for Edit)
|-
| displayName
| string
| Distribution list display name (Required)
|-
| isHidden
| boolean
| Whether or not the distribution list is hidden from the Global Address List (Defaults to false)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'name' => 'all.employees',
'displayName' => 'Employees'
},
'text/xml'
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'displayName' => 'Example.com Employees'
},
'text/xml',
</pre>

''Errors'':

{| 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
|-
| Required form field is missing
| 400
| Missing required field: name
|-
| Required form field has null or empty string input
| 400
| Required field displayName cannot be empty
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for isHidden, input must be True or False
|-
| Form data has unrecognized field
| 400
| Unrecognized field: size
|-
| New distribution list name already exists
| 400
| The email address john.doe@abc.com is already in use
|-
| New distribution list name doesn't meet the naming requirements
| 400
| Invalid user name
|-
| New distribution list display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Distribution list is not found
| 404
| Distribution List not found
|-
| Display name doesn't meet the naming requirements
| 400
| Invalid display name
|}

=== Delete ===

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)

''Description'':

Deletes the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Email Addresses ===

This refers to the email addresses a distribution list can appear as.

==== Add Email Address ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/emailaddresses/(email address)

''Description'':

Adds an email address that the distribution list is associated with to the list. This address' domain name must be the same as the domain the distribution list is under.

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

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution list not found
|}

==== Delete Email Address ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/emailaddresses/(email address)

''Description'':

Deletes the email address that is tied to the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/emailaddresses/alex@example.com', 'text/xml'
</pre>

=== Member ===

This refers to the recipients of the distribution list.

==== Add Member ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/members/(member name)

''Description'':

Adds an email address to the distribution list.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| Required form field is missing
| 400
| Missing field: addmember
|-
| Form data has unrecognized field
| 400
| Unrecognized field: deletemember
|-
| New member is not found
| 400
| No user with the email address jane.doe exists
|}

==== Delete Member ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/members/(member name)

''Description'':

Delete an email address from the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| Member is not found
| 400
| Invalid group member name
|}

Exchange Mailbox (Rest API)

2009-08-30T07:05:15Z

Brian.hartsock:

== Exchange Mailbox ==

=== Index ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes

''Description'':

Shows a list of mailboxes under the domain

''Remarks'':

The show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [Mailboxes.xsd]

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Show ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)

''Description'':

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

''Remarks'':

The show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [Mailbox.xsd]

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

=== Add/Edit ===

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)
[PUT] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)

''Description'':

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

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Display name (Required for Add)
|-
| initialPassword
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| isHidden
| boolean
| Indicates whether or not the mailbox is hidden from the Global Address List
|-
| isPublicFolderAdmin
| boolean
| Indicates whether or not the account is a public folder administrator
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| jobTitle
| string
| Job title
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| businessnumber
| string
| Business phone number
|-
| pagernumber
| string
| Pager phone number
|-
| homenumber
| string
| Home phone number
|-
| mobilenumber
| string
| Mobile phone number
|-
| faxnumber
| string
| Fax phone number
|-
| notes
| string
| Notes field
|-
| emailForwardingAddress
| string
| Forwarding email address (If this field is assigned an email address, then email forwarding will be turned on. If this field is not assigned or assigned an empty string, then email forwarding will be disabled.)
|-
| enabled
| string
| Enable/Disable mailbox, input must be "true" or "false"
|}

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| 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 mailbox name (user name) doesn't meet the naming requirements
| 400
| Invalid user name
|-
| New mailbox display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Integer form field has non-integer input
| 400
| Invalid format for size, input must be an integer
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for Enabled, input must be True or False
|-
| New mailbox password doesn't meet the password pattern requirements
| 400
| Password must be at least 8 characters long
|-
| Form data has unrecognized field
| 400
| Unrecognized field: extraStorage
|-
| New mailbox name (user name) already exists
| 400
| The email address john.doe@abc.com is already in use
|}

=== Delete ===

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)

''Description'':

Deletes the domain.

''Remarks'':

The mailbox and mailbox contents are deleted permanently.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

=== Add Email Address ===

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/emailaddresses/(email address)

''Description'':

Adds a mailbox's email address.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Delete Email Address ===

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/emailaddresses/(email address)

''Description'':

The delete email address.

''Remarks'':

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Spam ===

==== Index Blacklist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/blacklist

''Description'':

This operation returns email address blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Index IP Blacklist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipblacklist

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Index Safelist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Index IP Safelist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipsafelist

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Add Blacklist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/blacklist/(email address)

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@spam.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

==== Add IP Blacklist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/216.12.34.%', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Add Safelist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist/(email address)

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Add IP Safelist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist/(ip address)

''Description'':

Adds an IP to the safelist.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete Blacklist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/blacklist/(email address)

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the blacklist
|}

==== Delete IP Blacklist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist/216.12.34.%', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

==== Delete Safelist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist/(email address)

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

==== Delete IP Safelist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipsafelist/(email address)

''Description'':

Removes an IP from the safelist.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

==== Show Spam Setting ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/settings

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

==== Edit Spam Setting ====

''URL'':
[PUT] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/settings

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on'/'off'/'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Required form field is missing
| 400
| Missing required field: filterlevel
|-
| Required form field has null or empty string input
| 400
| Required field filterlevel cannot be empty
|-
| Form data has unrecognized field
| 400
| Unrecognized field: address
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for sendtodomainquarantine, input must be true or false
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

=== BlackBerry Mobile Service ===

==== Index ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/blackberrymobileservices

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

==== Add ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/blackberrymobileservice

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| Mailbox already has BlackBerry Service
| 400
| User john.smith@example.com has BlackBerry Mobile Service already
|}

==== Delete ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/blackberrymobileservice

''Description'':

Detaches a BlackBerry mobile service from a mailbox.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

=== ActiveSync Mobile Service ===

==== Index ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/activesyncmobileservices

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

==== Add ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/activesyncmobileservice

''Description'':

Attaches a ActiveSync service to the mailbox.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| Mailbox already has BlackBerry Service
| 400
| User john.smith@example.com has BlackBerry Mobile Service already
|}

==== Delete ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/blackberrymobileservice

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

Rest API

2009-08-30T07:04:54Z

Brian.hartsock:

The Email API is a RESTful web service based on the Hypertext Transfer Protocol (HTTP). Actions and data requests are performed by using HTTP based commands. For more information on RESTful web services try the following sites:

http://en.wikipedia.org/wiki/Representational_State_Transfer

http://java.sun.com/developer/technicalArticles/WebServices/restful/

== Resources ==

The following sections detail the operations that the API supports. The operations are grouped into sections based on the entity/object types that each operation interacts with.

{| border=1 class="simple"
!Resource
!Example URI
|-
| [[RestAPI/Customer| Customer]]
| /customers/123456789
|-
| [[RestAPI/Domain| Domain]]
| /customers/123456789/domains/example.com
|-
| [[RestAPI/Mailbox| Exchange Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
|-
| [[RestAPI/Distributionlist| Exchange Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
|-
| [[RestAPI/Contact| Exchange Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
|}

== Authentication ==

To gain access to the API, you must have keys generated from the Control Panel Web interface. These keys will be used to sign your request. The two keys are:

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

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

{| border=1 class="simple"
!Header Name
!Description
!Example
|-
| '''User-Agent'''
| An identifier you choose to identify your client software with
| ''Rackspace Management Interface''
|-
| '''X-Api-Signature'''
| A string ending with a signature constructed as specified below
| ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''
|}

An unsuccessful authentication will result in a 403 HTTP code.

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

Format is as follows:

<'''User Key'''>:<'''Timestamp'''>:<'''Signature'''>

Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

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

{| border=1 class="simple"
!YYYY
!Four-digit year
|-
| MM
| Month
|-
| DD
| Day
|-
| HH
| Hour in 24h format
|-
| mm
| Minute
|-
| ss
| Second
|-
| ff
| Millisecond
|}

 
'''Signature''':

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

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

Using the above example data, the string before hashing is: ''eGbq9/2hcZsRlr1JV1PiRackspace Management Interface20010317143725QHOvchm/40czXhJ1OxfxK7jDHr3t''

Resulting base-64 SHA1 Hash: ''HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

== Throttling ==

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

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

== Formats ==

The Email API supports two different response formats, XML and JSON. The response format is determined by HTTP 'Accept' header.

For XML, populate the header with 'text/xml' (ex: Headers!["Accept"] = "text/xml"). The XML document returned will conform to a published XSD (XML Schema Document).

For JSON, populate the header with 'application/json' (ex: Headers!["Accept"] = "application/json").

== Versions ==

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

Note: Pre-release versions of the API will be located at http://api.emailsrvr.com/v0/.

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

The version number has been omitted from URLs in this documentation.

=== Paging ===

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

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

== Filter/Search ==

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

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

{| border=1 class="simple"
!''Index Actions''
!''Where the key word will be searched''
|-
| Customer
| Customer name, account number, reference number
|-
| Domain
| Domain name
|-
| Mailbox
| Mailbox name, mailbox display name
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

'''Reference Number'''

For the customer object only, the query string "referenceNumber=xxx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

== Examples ==

=== Ruby ===

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

<pre>
module NetMethods
def get(url_string, format)
url = URI.parse('http://' + server_host + server_port + version + url_string)
@response = Net::HTTP::start(url.host, url.port) do |http|
sign_request
assign_format(format)
@request = Net::HTTP::Get.new(url.path, @headers)

http.request(@request)
end
end

def post(url_string, format, fields_hash)
url = URI.parse('http://' + server_host + server_port + version + url_string)

sign_request
assign_format(format)
@request = Net::HTTP::Post.new(url.path, @headers)

@request.set_form_data(fields_hash)
@response = Net::HTTP::start(url.host, url.port) do |http|
http.request(@request)
end
end

def assign_format (format)
@headers['Accept'] = format
end

def sign_request
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S00')
apiKey = 'XXXXXXXXXXXXXXXXXXXX'
secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

data_to_sign = apiKey + userAgent + timestamp + secretKey

signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))

@headers = Hash.new
@headers['User-Agent'] = userAgent
@headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature
end

def server_host
'api.emailsrvr.com'
end

def server_port
'80'
end

def version
'/v0'
end
end
</pre>

=== C# ===

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

<pre>
using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = userAgent;

var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmssff");

var dataToSign = apiKey + userAgent + dateTime + secretKey;
var hash = SHA1.Create();
var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
var signature = Convert.ToBase64String(signedBytes);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

<pre>
<?php
class WebMethods
{
public function get($url, $format)
{
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);

$session = curl_init($url);
curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);
}

public function post($url, $fields, $format)
{
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);

$session = curl_init($url);
curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_POST, true);
curl_setopt($session, CURLOPT_POSTFIELDS, $fields);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);
}

public function signRequest(&$headers)
{
$user_agent = 'Api Test';
$time_stamp = 'YYYYMMDDHHmmssff';
$api_key = 'XXXXXXXXXXXXXXXXXXXX';
$secret_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

$data_to_sign = $api_key . $user_agent . $time_stamp . $secret_key;
$signature = base64_encode(sha1($data_to_sign, true));

$headers[] = "User-Agent: $user_agent";
$headers[] = "X-Api-Signature: $api_key:$time_stamp:$signature";
}

public function assignFormat(&$headers, $format)
{
$headers[] = "Accept: $format";
}
}
?>
</pre>

Beta

2009-08-30T06:56:11Z

Brian.hartsock: Redirecting to RestAPI

#REDIRECT [[RestAPI]]

Exchange Contact (Rest API)

2009-08-30T06:17:38Z

Brian.hartsock:

== Contact ==

=== Index ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/contacts

''Description'':

Returns a list of contacts under the domain.

''Remarks'':

For the text/xml format, refer to the following schema document: [Contacts.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/contacts?size=100&page=1&contains=john', 'text/xml'
</pre>

''Errors'':

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

=== Show ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name)

''Description'':

Returns the contact's details.

''Remarks'':

For the text/xml format, refer to the following schema document: [Contact.xsd]

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

''Errors'':

{| 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
|-
| Contact is not found
| 404
| Contact not found
|}

=== Add/Edit ===

''URL'':
Add: [POST] /customers/(customer account number)/domains/(domain name)/ex/contacts/(contact name) 
Edit: [PUT] /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.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Name of contact when displayed (Required for add)
|-
| externalEmail
| string
| Email address (Required for add)
|-
| isHidden
| boolean
| Whether the contact is hidden from the Global List
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| jobTitle
| string
| Job title
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| businessnumber
| string
| Business phone number
|-
| homenumber
| string
| Home phone number
|-
| mobilenumber
| string
| Mobile phone number
|-
| faxnumber
| string
| Fax number
|-
| pagernumber
| string
| Pager number
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| notes
| string
| Notes field
|}

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

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

''Errors'':

{| 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
|-
| 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
|-
| 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
| 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] /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'':
<pre>
delete '/customers/12345678/domains/example.com/ex/contacts/alex.smith', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Contact is not found
| 404
| No user with the email address jane.doe@abc.com exists
|}

Exchange Distribution List (Rest API)

2009-08-30T06:16:27Z

Brian.hartsock:

== Distribution List ==

=== Index ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/distributionlists

''Description'':

This operation returns a list of distribution lists associated with the domain.

''Remarks'':

The Index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [Groups.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists?size=100&page=1&contains=mailing', 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution List is not found
| 404
| Distribution List not found
|}

=== Show ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)

''Description'':

Returns the distribution list's details.

''Remarks'':

The show operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: [Group.xsd]

''Example'':
<pre>
get '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Add/Edit ===

''URL'':
Add: [POST] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)
Edit: [PUT] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)

''Description'':

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

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| name
| string
| Distribution list name (Required for Add, not available for Edit)
|-
| displayName
| string
| Distribution list display name (Required)
|-
| isHidden
| boolean
| Whether or not the distribution list is hidden from the Global Address List (Defaults to false)
|}

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'name' => 'all.employees',
'displayName' => 'Employees'
},
'text/xml'
</pre>

<pre>
put '/customers/12345678/domains/example.com/ex/distributionlists/all.employees',
{
'displayName' => 'Example.com Employees'
},
'text/xml',
</pre>

''Errors'':

{| 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
|-
| Required form field is missing
| 400
| Missing required field: name
|-
| Required form field has null or empty string input
| 400
| Required field displayName cannot be empty
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for isHidden, input must be True or False
|-
| Form data has unrecognized field
| 400
| Unrecognized field: size
|-
| New distribution list name already exists
| 400
| The email address john.doe@abc.com is already in use
|-
| New distribution list name doesn't meet the naming requirements
| 400
| Invalid user name
|-
| New distribution list display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Distribution list is not found
| 404
| Distribution List not found
|-
| Display name doesn't meet the naming requirements
| 400
| Invalid display name
|}

=== Delete ===

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)

''Description'':

Deletes the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees', 'text/xml'
</pre>

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Distribution list is not found
| 404
| Distribution List not found
|}

=== Email Addresses ===

This refers to the email addresses a distribution list can appear as.

==== Add Email Address ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/emailaddresses/(email address)

''Description'':

Adds an email address that the distribution list is associated with to the list. This address' domain name must be the same as the domain the distribution list is under.

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

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution list not found
|}

==== Delete Email Address ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/emailaddresses/(email address)

''Description'':

Deletes the email address that is tied to the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/emailaddresses/alex@example.com', 'text/xml'
</pre>

=== Member ===

This refers to the recipients of the distribution list.

==== Add Member ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/members/(member name)

''Description'':

Adds an email address to the distribution list.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| Required form field is missing
| 400
| Missing field: addmember
|-
| Form data has unrecognized field
| 400
| Unrecognized field: deletemember
|-
| New member is not found
| 400
| No user with the email address jane.doe exists
|}

==== Delete Member ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/distributionlists/(distribution list name)/members/(member name)

''Description'':

Delete an email address from the distribution list.

''Example'':
<pre>
delete '/customers/12345678/domains/example.com/ex/distributionlists/all.employees/members/john.smith', {}, 'text/xml'
</pre>

''Errors'':

{| 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
|-
| Distribution list is not found
| 404
| Distribution list not found
|-
| Member is not found
| 400
| Invalid group member name
|}

Exchange Mailbox (Rest API)

2009-08-30T06:16:05Z

Brian.hartsock:

== Mailbox ==

=== Index ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes

''Description'':

Shows a list of mailboxes under the domain

''Remarks'':

The show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [Mailboxes.xsd]

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Show ===

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)

''Description'':

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

''Remarks'':

The show operation only supports the GET HTTP verb. For .xml format refer to the following schema document: [Mailbox.xsd]

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

=== Add/Edit ===

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)
[PUT] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)

''Description'':

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

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| displayName
| string
| Display name (Required for Add)
|-
| initialPassword
| string
| Password (Required for Add)
|-
| size
| positive integer
| Mailbox size in megabytes (Required for Add)
|-
| isHidden
| boolean
| Indicates whether or not the mailbox is hidden from the Global Address List
|-
| isPublicFolderAdmin
| boolean
| Indicates whether or not the account is a public folder administrator
|-
| firstName
| string
| First name
|-
| lastName
| string
| Last name
|-
| company
| string
| Company
|-
| department
| string
| Department
|-
| jobTitle
| string
| Job title
|-
| addressLine1
| string
| Street address
|-
| city
| string
| City
|-
| state
| string
| State
|-
| zip
| string
| Zip or postal code
|-
| country
| string
| Country
|-
| businessnumber
| string
| Business phone number
|-
| pagernumber
| string
| Pager phone number
|-
| homenumber
| string
| Home phone number
|-
| mobilenumber
| string
| Mobile phone number
|-
| faxnumber
| string
| Fax phone number
|-
| notes
| string
| Notes field
|-
| emailForwardingAddress
| string
| Forwarding email address (If this field is assigned an email address, then email forwarding will be turned on. If this field is not assigned or assigned an empty string, then email forwarding will be disabled.)
|-
| enabled
| string
| Enable/Disable mailbox, input must be "true" or "false"
|}

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| 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 mailbox name (user name) doesn't meet the naming requirements
| 400
| Invalid user name
|-
| New mailbox display name doesn't meet the naming requirements
| 400
| Invalid display name
|-
| Integer form field has non-integer input
| 400
| Invalid format for size, input must be an integer
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for Enabled, input must be True or False
|-
| New mailbox password doesn't meet the password pattern requirements
| 400
| Password must be at least 8 characters long
|-
| Form data has unrecognized field
| 400
| Unrecognized field: extraStorage
|-
| New mailbox name (user name) already exists
| 400
| The email address john.doe@abc.com is already in use
|}

=== Delete ===

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)

''Description'':

Deletes the domain.

''Remarks'':

The mailbox and mailbox contents are deleted permanently.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

=== Add Email Address ===

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/emailaddresses/(email address)

''Description'':

Adds a mailbox's email address.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Delete Email Address ===

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/emailaddresses/(email address)

''Description'':

The delete email address.

''Remarks'':

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

=== Spam ===

==== Index Blacklist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/blacklist

''Description'':

This operation returns email address blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Index IP Blacklist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipblacklist

''Description'':

This operation returns IP blacklist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Index Safelist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist

''Description'':

This operation returns email address safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Index IP Safelist ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipsafelist

''Description'':

This operation returns IP safelist associated with the mailbox.

''Remarks'':

The Index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|}

==== Add Blacklist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/blacklist/(email address)

''Description'':

Adds an email address or domain to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@spam.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered current domain
| 400
| Adding example.com would blacklist the current domain
|}

==== Add IP Blacklist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)

''Description'':

Adds an IP to the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/216.12.34.%', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Add Safelist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist/(email address)

''Description'':

Adds an email address or domain to the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|}

==== Add IP Safelist ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist/(ip address)

''Description'':

Adds an IP to the safelist.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|}

==== Delete Blacklist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/blacklist/(email address)

''Description'':

Removes an email address or domain from the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/blacklist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current blacklist
| 400
| abc@junkmail.com is not found on the blacklist
|}

==== Delete IP Blacklist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipblacklist/(ip address)

''Description'':

Removes an IP from the blacklist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/ipblacklist/216.12.34.%', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current blacklist
| 400
| 216.12.34.1 is not found on the blacklist
|}

==== Delete Safelist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/safelist/(email address)

''Description'':

Removes an email address or domain from the safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/safelist/anyone@yahoo.com', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid email or domain
| 400
| invalid email address: abc
|-
| Entered email or domain is not on the current safelist
| 400
| anyone@yahoo.com is not found on the safelist
|}

==== Delete IP Safelist ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/ipsafelist/(email address)

''Description'':

Removes an IP from the safelist.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Entered invalid IP address
| 400
| invalid ip address: 123
|-
| Entered IP is not on the current safelist
| 400
| 216.12.34.1 is not found on the safelist
|}

==== Show Spam Setting ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/settings

''Description'':

This operation returns the spam settings associated with the mailbox.

''Remarks'':

The Show operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

==== Edit Spam Setting ====

''URL'':
[PUT] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/spam/settings

''Description'':

This operation will modify the mailbox spam setting. Only 'filterlevel' is the required form field.

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| filterlevel
| string
| Spam filter status, must be 'on'/'off'/'exclusive' (Required)
|-
| sendtodomainquarantine
| boolean
| Indicates whether or not send spam to domain quarantine
|-
| quarantineowner
| string
| The email address that quarantine notifications be sent to
|}

''Remarks'':

Form field "filterlevel" is always required. 
When "filterlevel" is "on", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". 
Changing "filterlevel" to "off" will force "sendtodomainquarantine" to be "false". 
When "filterlevel" is "exclusive", spam will be sent to mailbox quarantine as default, unless "sendtodomainquarantine" is set to "true". In addition, mailbox will only receive email from addresses and IPs on its safelist.

''Example'':
<pre>
post '/customers/12345678/domains/example.com/ex/mailboxes/alex.smith/spam/settings', 'text/xml',
{
'filterlevel' => 'off'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| No user with the email address alex.smith@example.com exists
|-
| Required form field is missing
| 400
| Missing required field: filterlevel
|-
| Required form field has null or empty string input
| 400
| Required field filterlevel cannot be empty
|-
| Form data has unrecognized field
| 400
| Unrecognized field: address
|-
| Boolean form field has non-boolean input
| 400
| Invalid format for sendtodomainquarantine, input must be true or false
|-
| Invalid input for form field 'filterlevel'
| 400
| Invalid filterLevel, input must be: on/off/exclusive
|}

=== BlackBerry Mobile Service ===

==== Index ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/blackberrymobileservices

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

==== Add ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/blackberrymobileservice

''Description'':

Attaches a BlackBerry mobile service to the mailbox.

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

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| Mailbox already has BlackBerry Service
| 400
| User john.smith@example.com has BlackBerry Mobile Service already
|}

==== Delete ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/blackberrymobileservice

''Description'':

Detaches a BlackBerry mobile service from a mailbox.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

=== ActiveSync Mobile Service ===

==== Index ====

''URL'':
[GET] /customers/(customer account number)/domains/(domain name)/ex/activesyncmobileservices

''Description'':

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

''Remarks'':

The index operation only supports the GET HTTP verb.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|}

==== Add ====

''URL'':
[POST] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/activesyncmobileservice

''Description'':

Attaches a ActiveSync service to the mailbox.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 404
| Invalid format
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|-
| Mailbox already has BlackBerry Service
| 400
| User john.smith@example.com has BlackBerry Mobile Service already
|}

==== Delete ====

''URL'':
[DELETE] /customers/(customer account number)/domains/(domain name)/ex/mailboxes/(mailbox name)/blackberrymobileservice

''Description'':

Detaches a ActiveSync mobile service from a mailbox.

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Domain is not found
| 404
| abc.com not found
|-
| Mailbox is not found
| 404
| Mailbox not found
|}

Customer (Rest API)

2009-08-30T06:15:26Z

Brian.hartsock:

== Customer ==

=== Index ===

''URL'':

[GET] /customers

''Description'':

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

''Remarks'':

For the text/xml format, refer to the following schema document: [http://api.emailsrvr.com/v0/Schemas/CustomerList.xsd CustomerList.xsd]

''Example'':

<pre>
get '/customers?size=100&page=1&referenceNumber=102486', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|}

=== Show ===

''URL'':

[GET] /customers/(customer account number)

''Description'':

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

''Remarks'':

Keyword "me" is equivalent to the reseller's own account number.

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

''Example'':

<pre>
get '/customers/me', 'text/xml'
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| Customer account number is invalid
| 404
| Invalid account number
|}

=== Add/Edit ===

''URL'':

Add: [POST] /customers 
Edit: [PUT] /customers/(customer account number)

''Description'':

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

{| border=1 class="simple"
!''Field Name''
!''Data Type''
!''Description''
|-
| name
| string
| The customer's display name (Required for Add)
|-
| referenceNumber
| string
| The reference number of this account
|}

''Example'':

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

<pre>
put '/customers/999999', 'text/xml',
{
'name' => 'NewName',
'referenceNumber' => '12345'
}
</pre>

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| The name field was not specified
| 400
| Missing required field: name
|-
| The name field cannot be blank
| 400
| Required field name cannot be empty
|-
| Names cannot start with a space
| 400
| Improper Customer Name
|-
| The customer account was not found
| 404
| Customer Not Found
|}

=== Delete ===

''URL'':

[DELETE] /customers/(customer account number)

''Description'':

Deletes the account.

''Example'':

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

''Errors'':

{| border=1 class="simple"
!''Description''
!''HTTP Response Code''
!''Sample Message''
|-
| Format is invalid
| 406
| Invalid format
|-
| The customer account was not found
| 404
| Customer Not Found
|}

Rest API

2009-08-25T21:54:04Z

Brian.hartsock:

The Email API is a RESTful web service based on the Hypertext Transfer Protocol (HTTP). Actions and data requests are performed by using HTTP based commands. For more information on RESTful web services try the following sites:

http://en.wikipedia.org/wiki/Representational_State_Transfer

http://java.sun.com/developer/technicalArticles/WebServices/restful/

== Resources ==

The following sections detail the operations that the API supports. The operations are grouped into sections based on the entity/object types that each operation interacts with.

{| border=1 class="simple"
!Resource
!Example URI
|-
| [[RestAPI/Customer| Customer]]
| /customers/123456789
|-
| [[RestAPI/Domain| Domain]]
| /customers/123456789/domains/example.com
|-
| [[RestAPI/Mailbox| Mailbox]]
| /customers/123456789/domains/example.com/ex/mailboxes/john.smith
|-
| [[RestAPI/Distributionlist| Distribution List]]
| /customers/123456789/domains/example.com/ex/distributionlists/group.name
|-
| [[RestAPI/Contact| Contact]]
| /customers/123456789/domains/example.com/ex/contacts/john.smith
|}

== Authentication ==

To gain access to the API, you must have keys generated from the Control Panel Web interface. These keys will be used to sign your request. The two keys are:

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

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

{| border=1 class="simple"
!Header Name
!Description
!Example
|-
| '''User-Agent'''
| An identifier you choose to identify your client software with
| ''Rackspace Management Interface''
|-
| '''X-Api-Signature'''
| A string ending with a signature constructed as specified below
| ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''
|}

An unsuccessful authentication will result in a 403 HTTP code.

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

Format is as follows:

<'''User Key'''>:<'''Timestamp'''>:<'''Signature'''>

Example: ''eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

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

{| border=1 class="simple"
!YYYY
!Four-digit year
|-
| MM
| Month
|-
| DD
| Day
|-
| HH
| Hour in 24h format
|-
| mm
| Minute
|-
| ss
| Second
|-
| ff
| Millisecond
|}

 
'''Signature''':

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

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

Using the above example data, the string before hashing is: ''eGbq9/2hcZsRlr1JV1PiRackspace Management Interface20010317143725QHOvchm/40czXhJ1OxfxK7jDHr3t''

Resulting base-64 SHA1 Hash: ''HKUn0aajpSDx7qqGK3vqzn3FglI=''

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

== Throttling ==

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

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

== Formats ==

The Email API supports two different response formats, XML and JSON. The response format is determined by HTTP 'Accept' header.

For XML, populate the header with 'text/xml' (ex: Headers!["Accept"] = "text/xml"). The XML document returned will conform to a published XSD (XML Schema Document).

For JSON, populate the header with 'application/json' (ex: Headers!["Accept"] = "application/json").

== Versions ==

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

Note: Pre-release versions of the API will be located at http://api.emailsrvr.com/v0/.

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

The version number has been omitted from URLs in this documentation.

=== Paging ===

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

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

== Filter/Search ==

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

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

{| border=1 class="simple"
!''Index Actions''
!''Where the key word will be searched''
|-
| Customer
| Customer name, account number, reference number
|-
| Domain
| Domain name
|-
| Mailbox
| Mailbox name, mailbox display name
|-
| Contact
| Contact display name, external email
|-
| Group
| Group name, group display name
|-
| Mobile Service
| Associated mailbox name, mailbox display name
|}

'''Reference Number'''

For the customer object only, the query string "referenceNumber=xxx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

== Examples ==

=== Ruby ===

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

<pre>
module NetMethods
def get(url_string, format)
url = URI.parse('http://' + server_host + server_port + version + url_string)
@response = Net::HTTP::start(url.host, url.port) do |http|
sign_request
assign_format(format)
@request = Net::HTTP::Get.new(url.path, @headers)

http.request(@request)
end
end

def post(url_string, format, fields_hash)
url = URI.parse('http://' + server_host + server_port + version + url_string)

sign_request
assign_format(format)
@request = Net::HTTP::Post.new(url.path, @headers)

@request.set_form_data(fields_hash)
@response = Net::HTTP::start(url.host, url.port) do |http|
http.request(@request)
end
end

def assign_format (format)
@headers['Accept'] = format
end

def sign_request
userAgent = 'Ruby Test Client'
timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S00')
apiKey = 'XXXXXXXXXXXXXXXXXXXX'
secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

data_to_sign = apiKey + userAgent + timestamp + secretKey

signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))

@headers = Hash.new
@headers['User-Agent'] = userAgent
@headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature
end

def server_host
'api.emailsrvr.com'
end

def server_port
'80'
end

def version
'/v0'
end
end
</pre>

=== C# ===

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

<pre>
using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
private WebClientBase client;
private string baseUrl;
private string apiKey;
private string secretKey;

public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
{
this.client = client;
this.baseUrl = baseUrl;
this.apiKey = apiKey;
this.secretKey = secretKey;
}

public virtual string Get(string url)
{
return MakeRemoteCall((client) =>
{
return client.DownloadString(baseUrl + url);
},
format);
}

public virtual string Post(string url, NameValueCollection data)
{
return MakeRemoteCall((client) =>
{
var bytes = client.UploadValues(baseUrl + url, data);
return Encoding.UTF8.GetString(bytes);
},
format);
}

private void SignMessage()
{
var userAgent = "C# Client Library";
client.Headers["User-Agent"] = userAgent;

var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmssff");

var dataToSign = apiKey + userAgent + dateTime + secretKey;
var hash = SHA1.Create();
var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
var signature = Convert.ToBase64String(signedBytes);

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

private void AssignFormat(string format)
{
client.Headers["Accept"] = format;
}

private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
{
try
{
SignMessage();
AssignFormat(format);
return remoteCall.Invoke(client);
}
catch (WebException e)
{
throw new ApiException(e);
}
}
}
</pre>

=== PHP ===

<pre>
<?php
class WebMethods
{
public function get($url, $format)
{
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);

$session = curl_init($url);
curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);
}

public function post($url, $fields, $format)
{
$headers = array();
$this->signRequest($headers);
$this->assignFormat($headers, $format);

$session = curl_init($url);
curl_setopt($session, CURLOPT_HEADER, true);
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_POST, true);
curl_setopt($session, CURLOPT_POSTFIELDS, $fields);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($session);
curl_close($session);
}

public function signRequest(&$headers)
{
$user_agent = 'Api Test';
$time_stamp = 'YYYYMMDDHHmmssff';
$api_key = 'XXXXXXXXXXXXXXXXXXXX';
$secret_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

$data_to_sign = $api_key . $user_agent . $time_stamp . $secret_key;
$signature = base64_encode(sha1($data_to_sign, true));

$headers[] = "User-Agent: $user_agent";
$headers[] = "X-Api-Signature: $api_key:$time_stamp:$signature";
}

public function assignFormat(&$headers, $format)
{
$headers[] = "Accept: $format";
}
}
?>
</pre>