Guides
Guides
Start typing to search…

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 3 months ago