search_domains
The search_domains method retrieves a list of domains in a company.
Syntax
{
<credentials object>
"criteria": {
"company": <company>,
"type": [<domain and/or alias],
"match": <wildcard pattern>,
"deleted": true | false
}
"range": {
"first": <number>,
"limit": <number>
"sort": {
"by": delete_time | domain | id | type | users | users/filter |
users/forward | users/mailbox | users/alias | users/deleted,
"direction": ascending | descending
}
}
Request fields for search_domains
The following fields can be used in the search_domains method:
| Field name | Obligation | Definition/Value |
|---|---|---|
| criteria | Optional | Narrows the results by restricting the search to the specified fields and their values. Allowed values are: company — The company to search for domains. If not specified, the requestor's company is used. deleted — If set to true, only deleted domains are returned; if set to false or not specified, only existing domains are returned. match — Returns only those domains that match the specified pattern. You can use the following wildcards: ? ― Match a single character * * ― Match a string of characters. type — Returns only domains of the specified type. Allowed values are: domain — Regular domains * alias — Alias domains |
| range | Optional | Limits the range of domains to display. Allowed values are: first — Specify the first domain to return; the default is the first result. limit — Specify the maximum number of results to return. |
| sort | Optional | Determines the way in which to sort and display results. Allowed values are: by — Specify the attribute to use to sort results. Allowed values are: delete_time — The time the domain was deleted. Can be used only if criteria = deleted. domain — The domain name (this is the default). id — The identification number of the domain. type — The domain type: domain or alias. users — The number of users in the domain. You can refine this to specify the number of users of a certain mailbox type by using one of the following: users/alias, users/deleted, users/filter, users/forward, or users/mailbox. * direction — Specify the sort order. Allowed values are ascending (this is the default) or descending. |
Response fields for search_domains
The following fields may be returned when the search_domains method is submitted:
| Field name | Obligation | Description/Value |
|---|---|---|
| count | Returned if success = true | The number of domains returned. |
| domains | Returned if success = true | A list of the domains that meet the criteria, and, optionally, their attributes. Allowed values are: alias_target—The domain for which this name is an alias. Returned only if the domain is an alias. counts—The number of each of the different mailbox types in the domain. domain—A list of the domains that meet the search criteria. id—The identification number of the account. Returned only if deleted = true in the request. type—The type of domain. May be one of the following: alias—An alias name for another domain. * domain—Regular domain. |
| error | Returned if success = false | A text string that explains the error. |
| error_number | Returned if success = false | A number that represents the error. |
| success | Always returned | Indicates whether the request was successful or not. Allowed values are true and false. |
| total_count | Returned if success = true | The total number of domains that match the search criteria. This value may be more than the number of results returned if a range was specified in the request. |
Examples for search_domains
Example 1
Retrieves all domains in the requestor's company.
Request
{
"credentials": {
"user": "[email protected]",
"password": "sw0rdf1sh"
}
}
Response
{
"success": true,
"domains": [
{
"domain": "example.adm",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 1,
"total": 1,
"alias": 0
}
},
{
"domain": "example.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 2,
"deleted": 1,
"mailbox": 7,
"total": 10,
"alias": 1
}
},
{
"domain": "example2-restored.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 0,
"total": 0,
"alias": 0
}
},
{
"domain": "othermail.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 1,
"total": 1,
"alias": 0
}
},
{
"domain": "schmexample.com",
"alias_target": "example.com",
"type": "alias"
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 0,
"total": 0,
"alias": 0
}
}
],
"count": 5,
"total_count": 5
}
Example 2
Retrieves all domains in the requestor's company that start with 'd', sorted by number of users in the domain.
Request
{
"credentials": {
"user": "[email protected]",
"password": "sw0rdf1sh"
},
"criteria": {
"match": "d*"
},
"sort": {
"by": "users"
}
}
Response
{
"success": true,
"domains": [
{
"domain": "example2-restored.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 0,
"total": 0,
"alias": 0
}
},
{
"domain": "example.adm",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 1,
"total": 1,
"alias": 0
}
},
{
"domain": "example.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 2,
"deleted": 1,
"mailbox": 7,
"total": 10,
"alias": 1
}
}
],
"count": 3,
"total_count": 3
}
Example 3
Retrieves all regular .com domains in the requestor's company
Request
{
"credentials": {
"user": "[email protected]",
"password": "sw0rdf1sh"
},
"criteria": {
"match": "*.com",
"type": [
"domain"
]
}
}
Response
{
"success": true,
"domains": [
{
"domain": "example.adm",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 1,
"total": 1,
"alias": 0
}
}
{
"domain": "example.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 2,
"deleted": 1,
"mailbox": 7,
"total": 10,
"alias": 1
}
}
{
"domain": "example2-restored.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 0,
"total": 0,
"alias": 0
}
}
{
"domain": "othermail.com",
"type": "domain",
"counts": {
"filter": 0,
"forward": 0,
"deleted": 0,
"mailbox": 1,
"total": 1,
"alias": 0
}
}
],
"count": 4,
"total_count": 4
}
Updated less than a minute ago