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.

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
}