API: OpenSRS Email

The API: OpenSRS Hosted Email Developer Hub

Welcome to the API: OpenSRS Hosted Email developer hub. You'll find comprehensive guides and documentation to help you start working with API: OpenSRS Hosted Email as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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 nameObligationDefinition/Value
criteriaOptionalNarrows 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
rangeOptionalLimits 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.
sortOptionalDetermines 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 nameObligationDescription/Value
countReturned if success = trueThe number of domains returned.
domainsReturned if success = trueA 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.
errorReturned if success = falseA text string that explains the error.
error_numberReturned if success = falseA number that represents the error.
successAlways returnedIndicates whether the request was successful or not. Allowed values are true and false.
total_countReturned if success = trueThe 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

search_domains


The search_domains method retrieves a list of domains in a company.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.