Difference between revisions of "Domain (Rest API)"
(→Show) |
(→Index (Reseller Only)) |
||
Line 319: | Line 319: | ||
''Description'': | ''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. The XML schema for the returned data is [http://api.emailsrvr.com | + | 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. The XML schema for the returned data is [http://api.emailsrvr.com/Schemas/DomainSplitRouting.xsd DomainAlternateList.xsd] |
Revision as of 06:17, 25 July 2013
Contents
Index
URL:
[GET] https://api.emailsrvr.com/v0/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/v0/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.
The index operation only supports the GET HTTP verb. For text/xml format, refer to the following schema document: DomainList.xsd
Example:
get '/customers/all/domains?size=100&offset=10', 'text/xml'
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> </domain> <domain> <name>apidomain66.com</name> <accountNumber>100001</accountNumber> <serviceType>both</serviceType> </domain> <domain> <name>apidomain68.com</name> <accountNumber>100002</accountNumber> <serviceType>both</serviceType> </domain> </domains> </domainList>
Json Result Example:
{"offset":0,"size":50,"total":3,"domains": [{"name":"apidomain53.com","accountNumber":"100000","serviceType":"both"}, {"name":"apidomain66.com","accountNumber":"100001","serviceType":"both"}, {"name":"apidomain68.com","accountNumber":"100002","serviceType":"both"}]}
Show
URL:
[GET] https://api.emailsrvr.com/v0/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: Domain.xsd
Notes:
- These two fields 'exchangeUsedStorage' and 'rsEmailUsedStorage' actually return the number of active mailboxes in each service respectively.
- 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' at this moment.
Example:
get '/customers/999999/domains/example.com', 'text/xml'
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/v0/customers/(customer account number)/domains/(domain name) Edit: [PUT] https://api.emailsrvr.com/v0/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.
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 |
blackBerryMobileServiceEnabled | boolean | Enable or disable domain BlackBerry Mobile service |
blackBerryLicenses | int | Maximum number of mailboxes allowed to have BlackBerry Mobile service. 0 means unlimited |
activeSyncMobileServiceEnabled | boolean | Enable or disable domain ActiveSync Mobile service |
activeSyncLicenses | int | Maximum number of mailboxes allowed to have ActiveSync Mobile service. 0 means unlimited |
goodMobileServiceEnabled (deprecated) | boolean | Enable or disable domain Good Mobile service |
goodMobileLicenses (deprecated) | int | Maximum number of mailboxes allowed to have Good Mobile service. 0 means unlimited |
archivingServiceEnabled | boolean | Enable or disable domain archiving service |
Example:
post '/customers/123455/domains/newcompany.com', 'text/xml', { 'maxNumMailboxes' => '5', 'extraStorage' => '1024' }
put '/customers/123455/domains/newcompany.com', 'text/xml', { 'maxNumMailboxes' => '25', 'extraStorage' => '2048' }
Errors:
Description | HTTP Response Code | Sample Message |
---|---|---|
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 (Reseller Only)
URL:
[PUT] https://api.emailsrvr.com/v0/customers/ (new customer account number)/domains/(domain name)
Description:
Moves the domain to another customer account.
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:
put '/customers/123456/domains/newcompany.com', 'text/xml', { 'moveDomain' => 'true' }
Delete (Reseller Only)
URL:
[DELETE] https://api.emailsrvr.com/v0/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', 'text/xml'
Alternate Domains
Index (Reseller Only)
URL:
[GET] https://api.emailsrvr.com/v0/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. The XML schema for the returned data is DomainAlternateList.xsd
Example:
get '/customers/12345678/domains/test.com/alternatedomains', 'text/xml'
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/v0/customers/(customer account number) /domains/(domain name)/alternatedomains/(alternate domain name)
Description:
Adds either a Domain Alias or Accepted Domain to the domain.
Field Name | Data Type | Description |
---|---|---|
type | string | Alternate domain type. Send "DomainAlias" for a domain alias, and "AcceptedDomain" for an accepted domain. (Required) |
createForExistingRecipients | boolean | Whether the alternate addresses should be created for existing mailboxes when adding an Accepted Domain. Sending this field in the request when the type is Domain Alias will throw an error. This defaults to false. |
Example:
post '/customers/123456/domains/example.com/alternatedomains/accepteddomain.com', 'text/xml', { 'type' => 'AcceptedDomain' 'createForExistingRecipients' => 'true' }
Errors:
Description | HTTP Response Code | Sample Message |
---|---|---|
New domain name doesn't meet the naming requirements | 400 | Invalid domain name |
Alternate domain already exists | 400 | abc.com already exists as a domain or alternate domain |
The 'createForExistingRecipients' field was sent with either data, or as a null field. It should not be included in the form data at all. | 400 | Invalid Alternate Domain Setting: createForExistingRecipients is an invalid setting for Domain Aliases |
The only valid values for 'type' are 'DomainAlias' and 'AcceptedDomain', for a Domain Alias and Accepted Domain respectively. | 400 | Invalid Alternate Domain type |
Delete (Reseller Only)
URL:
[DELETE] https://api.emailsrvr.com/v0/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/v0/customers/(customer account number)/domains/(domain)/splitdomainrouting
Description: Shows the current external email server. The XML schema document for the output of this command is DomainSplitRouting.xsd
Example:
get '/customers/12345678/domains/company.com/splitdomainrouting', 'text/xml'
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/v0/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.
Field Name | Data Type | Description |
---|---|---|
externalServer | string | The address of the external email server. To turn off split domain routing send 'none'. (Required) |
verificationAddress | string | An email address part of your domain or one of the alternate domains that the external server is already set up to handle. (Required only when turning on split domain routing, Do not send this field if turning off.) |
Example:
put '/customers/12345678/domains/company.com/splitdomainrouting', 'text/xml', { 'externalServer' => 'email.externalserver.com', 'verificationAddress' => 'externalaccount@company.com', }
Description | HTTP Response Code | Sample Message |
---|---|---|
The SMTP host could not be found. | 400 | One of the verification error messages. |
Archiving SSO Login URL
URL:
[GET] https://api.emailsrvr.com/v0/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', 'text/xml'
Errors:
Description | HTTP Response Code | Sample Message |
---|---|---|
No archiving service | 404 | Domain abc.com has no archiving service enabled |
Domain Public Folders
Show Status
URL:
[GET] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/ex/publicfolders
Description:
Retrieves the Exchange Public Folders status for the domain. The XML schema for the returned data is DomainPublicFolders.xsd
Example:
get '/customers/12345678/domains/company.com/ex/publicFolders', 'text/xml'
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/v0/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.
Field Name | Data Type | Description |
---|---|---|
enabled | string | Whether to enable public folders. Once enabled, it cannot be disabled. |
Example:
put '/customers/12345678/domains/company.com/ex/publicFolders', 'text/xml', { 'enabled' => 'true' }
Errors:
Description | HTTP Response Code | Sample Message |
---|---|---|
Public folders cannot be turned off after it's been turned on. | 400 | Public Folders cannot be disabled once enabled |
Domain Email Everyone
URL:
[POST] https://api.emailsrvr.com/v0/customers/(customer account number)/domains/(domain name)/emaileveryone [POST] https://api.emailsrvr.com/v0/domains/(domain name)/emaileveryone
Description:
Send an email to all mailboxes for the domain. This request returns a list of recipients.
Field Name | Data Type | Description |
---|---|---|
fromName | string | Sender's Name. |
fromAddress | string | Sender's Email Address. |
subject | string | Message subject. |
body | string | Message body. |
Example:
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml', { '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/v0/customers/(customer account number)/domains/(domain name)/catchalladdress [GET] https://api.emailsrvr.com/v0/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', 'text/xml'
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/v0/customers/(customer account number)/domains/(domain name)/catchalladdress [PUT] https://api.emailsrvr.com/v0/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.
Field Name | Data Type | Description |
---|---|---|
address | string | The Catch-All email address. Set address to empty string to remove Catch-All Address. |
Example:
post'/customers/12345678/domains/example.com/emaileveryone', 'text/xml', { 'address' => 'abc@example.com' }