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
}