Difference between revisions of "Domain (Rest API)"

Latest revision as of 10:31, 5 April 2017

v1 - Current

Index

URL:

[GET] https://api.emailsrvr.com/v1/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:

• To retrieve a list of domains owned by the account that is logged in, use "me" as the customer account number i.e. 'https://api.emailsrvr.com/v1/customers/me/domains'.
• To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number. 'https://api.emailsrvr.com/v1/customers/all/domains'.
• To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. 'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains'.
• Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me

'https://api.emailsrvr.com/v1/domains'. 

• The index operation only supports the GET HTTP verb.

Example:

get '/customers/all/domains?size=100&offset=10'

domainNames Parameter (V1 only): The optional query string parameter "domainNames" can be used to retrieve a specific subset of domains by hostname. Up to 100 hostnames can be given at once in a comma-delimited list.

get '/customers/all/domains?domainNames=apidomain53.com,apidomain66.com,apidomain68.com', 'application/json'

XML Result Example:

<?xml version="1.0" encoding="utf-8"?>
<domainList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainList">
  <offset>0</offset>
  <size>50</size>
  <total>3</total>
  <domains>
    <domain>
      <name>apidomain53.com</name>
      <accountNumber>100000</accountNumber>
      <serviceType>both</serviceType>
      <exchangeMaxNumMailboxes>10</exchangeMaxNumMailboxes>
      <exchangeUsedStorage>4</exchangeUsedStorage>
      <rsEmailMaxNumberMailboxes>10</rsEmailMaxNumberMailboxes>
      <rsEmailUsedStorage>9</rsEmailUsedStorage>
    </domain>
    <domain>
      <name>apidomain66.com</name>
      <accountNumber>100001</accountNumber>
      <serviceType>rsemail</serviceType>
      <exchangeMaxNumMailboxes>0</exchangeMaxNumMailboxes>
      <exchangeUsedStorage>0</exchangeUsedStorage>
      <rsEmailMaxNumberMailboxes>100</rsEmailMaxNumberMailboxes>
      <rsEmailUsedStorage>40</rsEmailUsedStorage>
    </domain>
    <domain>
      <name>apidomain68.com</name>
      <accountNumber>100002</accountNumber>
      <serviceType>exchange</serviceType>
      <exchangeMaxNumMailboxes>50</exchangeMaxNumMailboxes>
      <exchangeUsedStorage>10</exchangeUsedStorage>
      <rsEmailMaxNumberMailboxes>0</rsEmailMaxNumberMailboxes>
      <rsEmailUsedStorage>0</rsEmailUsedStorage>
    </domain>
  </domains>
</domainList>

Json Result Example:

{"offset":0,"size":50,"total":3,"domains":
[{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both","exchangeMaxNumMailboxes":"10","exchangeUsedStorage":"4","rsEmailMaxNumberMailboxes":"10","rsEmailUsedStorage":"9"},
{"name":"apidomain66.com","accountNumber":"100001","serviceType":"rsemail","exchangeMaxNumMailboxes":"0","exchangeUsedStorage":"0","rsEmailMaxNumberMailboxes":"100","rsEmailUsedStorage":"40"},
{"name":"apidomain68.com","accountNumber":"100002","serviceType":"exchange","exchangeMaxNumMailboxes":"50","exchangeUsedStorage":"10","rsEmailMaxNumberMailboxes":"0","rsEmailUsedStorage":"0"}]}

Export

URL:

[GET] https://api.emailsrvr.com/v1/customers/(customer account number)/domains?exportTo={email address}

Description:

Use this route to export a file that includes details for domains on an account.

Remarks:

• To retrieve a list of domains owned by the account that is logged in, use "me" as the customer account number i.e. 'https://api.emailsrvr.com/v1/customers/me/domains?exportTo=myAdminEmail@example.com'.
• To retrieve a list of domains owned by all customer sub-accounts and your own account, use "all" as the customer account number. 'https://api.emailsrvr.com/v1/customers/all/domains?exportTo=myAdminEmail@example.com'.
• To retrieve a list of domains owned by a single customer sub-account, use the subaccounts account number in the url. 'https://api.emailsrvr.com/v1/customers/{subaccount number}/domains?exportTo=myAdminEmail@example.com'.
• Leaving the customers/{customer account number} out of the url is acceptable and returns the sames results as /customers/me

'https://api.emailsrvr.com/v1/domains?exportTo=myAdminEmail@example.com'. 

• The export route supports 'contains' and 'startswith' filtering

Show

URL:

[GET] https://api.emailsrvr.com/v1/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.

Notes:

1. These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.
2. Due to a performance issue Domain Public Folder Status is now returned from an individual URL. See Public Folders Status. The field 'publicFoldersEnabled' from Show Domain result always returns 'false'.

Example:

get '/customers/999999/domains/example.com'

XML Result Example:

<?xml version="1.0" encoding="utf-8"?>
<domain xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domain">
  <name>apidomain21.com</name>
  <accountNumber>100000</accountNumber>
  <serviceType>both</serviceType>
  <exchangeBaseMailboxSize>2048</exchangeBaseMailboxSize>
  <exchangeUsedStorage>0</exchangeUsedStorage>
  <exchangeTotalStorage>18432</exchangeTotalStorage>
  <exchangeExtraStorage>10240</exchangeExtraStorage>
  <exchangeMaxNumMailboxes>4</exchangeMaxNumMailboxes>
  <rsEmailBaseMailboxSize>2048</rsEmailBaseMailboxSize>
  <rsEmailMaxNumberMailboxes>4</rsEmailMaxNumberMailboxes>
  <rsEmailExtraStorage>10240</rsEmailExtraStorage>
  <rsEmailUsedStorage>0</rsEmailUsedStorage>
  <aliases />
  <archivingServiceEnabled>false</archivingServiceEnabled>
  <publicFoldersEnabled>false</publicFoldersEnabled>
  <blackBerryMobileServiceEnabled>true</blackBerryMobileServiceEnabled>
  <blackBerryLicenses>4</blackBerryLicenses>
  <activeSyncMobileServiceEnabled>true</activeSyncMobileServiceEnabled>
  <activeSyncLicenses>4</activeSyncLicenses>
</domain>

Json Result Example:

{"name":"apidomain21.com","accountNumber":"100000","serviceType":"both",
"exchangeBaseMailboxSize":2048,"exchangeUsedStorage":0,"exchangeTotalStorage":18432,
"exchangeExtraStorage":10240,"exchangeMaxNumMailboxes":4,"rsEmailBaseMailboxSize":2048,
"rsEmailMaxNumberMailboxes":4,"rsEmailExtraStorage":10240,"rsEmailUsedStorage":0,
"aliases":[],"archivingServiceEnabled":false,"publicFoldersEnabled":false,
"blackBerryMobileServiceEnabled":true,"blackBerryLicenses":4,"activeSyncMobileServiceEnabled":true,
"activeSyncLicenses":4}

Add/Edit (Reseller Only)

URL:

 Add: [POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)
 Edit: [PUT] https://api.emailsrvr.com/v1/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.

Example:

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

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

Errors:

Notes:

When setting rsEmailProduct, there is a short delay before the change is reflected, while the upgrade (or downgrade) process is happening.

Move (Reseller Only)

URL:

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

Description:

Moves a domain among your account and subaccounts.

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:

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

Transfer

Transfers ownership of a domain to another customer. You can start, read, and cancel the transfer. The other customer can finish the transfer.

Start

URL:

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

Description:

Creates a transfer, which is represented by a token. A transfer also has an expiration, which is represented by an RFC 3339 formatted timestamp. After the expiration, the transfer is automatically canceled.

Example:

post'/customers/12345678/domains/company.com/transfer', 'application/json'

JSON Result Example:

{
  "Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
  "Expiration": "2014-08-20T17:28:44Z"
}

Errors:

Read

URL:

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

Description:

Retrieves the domain transfer information for the domain that was returned by the request to start the transfer.

Example:

get '/customers/12345678/domains/company.com/transfer', 'application/json'

JSON Result Example:

{
  "Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
  "Expiration": "2014-08-20T17:28:44Z"
}

Errors:

Cancel

URL:

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

Description:

Cancels a domain transfer.

Example:

delete '/customers/12345678/domains/company.com/transfer', 'application/json'

Finish

URL:

[POST] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain name)/transfer/finish

Description:

Finish a domain transfer. This API request must be made by an admin that is on the account that will accept the domain. When the request completes successfully, assigns ownership of the domain to the company of the authenticated admin. That company will have full control of the domain, and accepts billing for services associated with the domain.

Example:

post '/customers/12345678/domains/company.com/transfers/finish', 'application/json',
{
  'Token' => 'b77b8460-5019-48e0-a5eb-4951640ea3cd'
}

JSON Result Example:

{
  "Token": "b77b8460-5019-48e0-a5eb-4951640ea3cd",
  "Expiration": "2014-08-20T17:28:44Z"
}

Errors:

Delete (Reseller Only)

URL:

[DELETE] https://api.emailsrvr.com/v1/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:

delete '/customers/12345678/domains/newcompany.com'

Alternate Domains

Index (Reseller Only)

URL:

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

Description:

This operation returns a list of Domain Aliases and Accepted Domains for the domain. The type of the alternate domain is indicated by the 'type' data field.

Example:

get '/customers/12345678/domains/test.com/alternatedomains'

XML Result Example:

<?xml version="1.0" encoding="utf-8"?>
<alternateDomainList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainAlternateList">
  <alternateDomains>
    <alternateDomain>
      <name>domainalias.com</name>
      <type>DomainAlias</type>
    </alternateDomain>
    <alternateDomain>
      <name>accepteddomain.com</name>
      <type>AcceptedDomain</type>
    </alternateDomain>
  </alternateDomains>
</alternateDomainList>

Json Result Example:

{"alternateDomains":[{"name":"domainalias.com","type":"DomainAlias"},{"name":"accepteddomain.com","type":"AcceptedDomain"}]}

Add (Reseller Only)

URL:

 [POST] https://api.emailsrvr.com/v1/customers/(customer account number)
    /domains/(domain name)/alternatedomains/(alternate domain name)
 

Description:

Adds either a Domain Alias or Accepted Domain to the domain.

Example:

post '/customers/123456/domains/example.com/alternatedomains/accepteddomain.com',
{
  'type' => 'AcceptedDomain'
  'createForExistingRecipients' => 'true'
}

Errors:

Delete (Reseller Only)

URL:

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

Description:

Deletes the alternate domain.

Example:

delete '/customers/12345678/domains/example.com/alternatedomains/accepteddomain.com'

Split Domain Routing

Show Settings

URL:

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

Description: Shows the current external email server.

Example:

get '/customers/12345678/domains/company.com/splitdomainrouting'

XML Result Example:

<?xml version="1.0" encoding="utf-8"?>
<splitDomainRouting xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:splitDomainRouting">
  <externalServer>email.externalserver.com</externalServer>
</splitDomainRouting>

JSON Result Example:

{"externalServer":"email.externalserver.com"}

Edit Settings

URL:

[PUT] https://api.emailsrvr.com/v1/customers/(customer account number)/domains/(domain)/splitdomainrouting

Description:

This command sets the external email server. This command will return a success when the verification passes. Since this involves communication to the external server the request may take some time. If the verification fails a 400 return code will be sent back with the verification's error message.

Example:

put '/customers/12345678/domains/company.com/splitdomainrouting',
{
  'externalServer' => 'email.externalserver.com',
  'verificationAddress' => 'externalaccount@company.com',
}

Archiving SSO Login URL

URL:

[GET] https://api.emailsrvr.com/v1/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:

get '/customers/12345678/domains/company.com/archivingSSOLoginURL'

Errors:

Domain Public Folders

Show Status

URL:

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

Description:

Retrieves the Exchange Public Folders status for the domain. Example:

get '/customers/12345678/domains/company.com/ex/publicFolders'

XML Result Example:

<?xml version="1.0" encoding="utf-8"?>
<?xml version="1.0" encoding="utf-8"?>
<domainPublicFolders xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:domainPublicFolders">
  <enabled>true</enabled>
</domainPublicFolders>

Enable

URL:

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

Description:

Enables the Exchange Public Folders feature on the domain. Once enabled, it cannot be disabled.

Example:

put '/customers/12345678/domains/company.com/ex/publicFolders',
{
  'enabled' => 'true'
}

Errors:

Domain Email Everyone

URL:

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

Description: Send an email to all mailboxes for the domain. This request returns a list of recipients.

Example:

post'/customers/12345678/domains/example.com/emaileveryone',
{
  'fromName' => 'John Doe',
  'fromAddress' => 'john.doe@test.com',
  'subject' => 'Hi All',
  'body' => 'Hello World.',
}

XML Result Example:

<?xml version="1.0" encoding="utf-8"?>
<emailAddressList xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddressList">
  <emailAddresses>
    <address>a@example.com</address>
    <address>b@example.com</address>
  </emailAddresses>
</emailAddressList>

Json Result Example:

{"emailAddresses":["a@example.com","b@example.com"]}

Show Domain Catch-All Address

URL:

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

Description:

Return the Catch-All Address for the domain. Returns empty string when no Catch-All Address set for the domain.

Remarks:

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

Example:

get '/customers/999999/domains/example.com/catchalladdress'

XML Result Example:

<?xml version="1.0" encoding="utf-8"?>
<emailAddress xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:xml:emailAddress">
  <address>abc@example.com</address>
</emailAddress>

Json Result Example:

{"address":"abc@example.com"}

Edit Domain Catch-All Address

URL:

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

Description:

Edit the Catch-All Address for the domain.

Remarks:

When an email is sent to a mailbox that does not exist on your domain, deliver the email to this address.

Notes:

This request may take about 1-2 minutes to be applied to the domain.

Example:

post'/customers/12345678/domains/example.com/emaileveryone',
{
  'address' => 'abc@example.com'
}