--- updatedAt: 2025-04-22T20:06:30.000Z agentTools: projectIndex: https://email.opensrs.guide/v1.0/llms.txt --- # search_domains The **search_domains** method retrieves a list of domains in a company. ## Syntax ```perl { "criteria": { "company": , "type": [, "deleted": true | false } "range": { "first": , "limit": "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** ```perl { "credentials": { "user": "company_admin@example.adm", "password": "sw0rdf1sh" } } ``` **Response** ```perl { "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** ```perl { "credentials": { "user": "company_admin@democo.adm", "password": "sw0rdf1sh" }, "criteria": { "match": "d*" }, "sort": { "by": "users" } } ``` **Response** ```perl { "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** ```perl { "credentials": { "user": "company_admin@example.adm", "password": "sw0rdf1sh" }, "criteria": { "match": "*.com", "type": [ "domain" ] } } ``` **Response** ```perl { "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 } ```