Guides
Guides
Start typing to search…

search_workgroups

The search_workgroups method retrieves a list of workgroups in a domain.

Syntax

{
  <credentials object>, 
  "criteria": {
    "domain": <domain name>,
    "match": <wildcard pattern> 
  }
  "range":{
     "first": <number>, 
     "limit": <number> 
     "sort": {
        "by": workgroup | users
        "direction": ascending | descending
    }
}

Request fields for search_workgroups

The following fields can be used in the search_workgroups method:

Field name

Obligation

Definition/Value

criteria

Required

Narrows the results by restricting the search.

Allowed values are:

  • domain — Specifies the domain to search. This is required.

  • match — Returns only those workgroups that match the specified pattern. You can use the following wildcards:

  • ? ― Match a single character

  • * ― Match multiple characters.

range

Optional

Limits the results to a subset of those selected by the criteria values.

Allowed values are:

  • first — Specify the first workgroup 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:

  • user — The number of users in the workgroup.

  • workgroup — The workgroup name (this is the default).

  • direction — Specify the sort order. Allowed values are ascending (this is the default) or descending.

Response fields for search_workgroups

The following fields may be returned in response to the search_workgroups method:

Field name

Obligation

Description/Value

count

Returned if success = true

The number of workgroups returned.

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 workgroups that match the search criteria. This value may be more than the number of results returned if a range was specified in the request.

workgroups

Returned if success = true

A list of the workgroups that meet the criteria and their attributes.

Includes the following:

  • counts — The number of each type of mailbox in the workgroup.

  • filter — The number of filter only mailboxes (delivery_filter attribute set to true).

  • forward — The number of forward only mailboxes (delivery_forward attribute set to true and delivery_local set to false).

  • mailbox — The number of mailboxes (delivery_local attribute set to true).

  • total — The total number of users in the workgroup.

  • workgroup — The workgroup name.

Examples for search_workgroups

Example 1

Retrieves all workgroups in the domain example.com.

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com"
  } 
}

Response

{
  "success": true,
  "count": 7,
  "total_count": 7,
  "workgroups": [
    {
      "workgroup": "contract",
      "counts": {
      	"filter": 0,
				"forward": 0,
				"mailbox": 0,
				"total": 0
      } 
    },
		{
    	"workgroup": "interns",
  		"counts": {
    		"filter": 0,
    		"forward": 1,
    		"mailbox": 2,
    		"total": 3
    }, 
    {
    	"workgroup": "sales",
				"counts": {
  			"filter": 0,
  			"forward": 0,
  			"mailbox": 1,
  			"total": 1
      } 
    },
    {
    	"workgroup": "sales_europe",
  		"counts": {
    		"filter": 0,
    		"forward": 0,
    		"mailbox": 0,
    		"total": 0
      } 
    },
    {
    	"workgroup": "staff",
  		"counts": {
      	"filter": 0,
        "forward": 1,
        "mailbox": 4,
        "total": 5
      } 
    },
    {
    	"workgroup": "stock_holders",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      } 
    },
    {
    	"workgroup": "sysadmins",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      }
    }
  ],
}

Example 2

Retrieves all workgroups that start with 's'.

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
  } 
}

Response

{
  "success": true,
  "count": 5,
  "total_count": 5,
  "workgroups": [
    {
    	"workgroup": "sales",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 1,
        "total": 1
      }
    },
    {
    	"workgroup": "sales_europe",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      }
    },
    {
    	"workgroup": "staff",
      "counts": {
        "filter": 0,
        "forward": 1,
        "mailbox": 4,
        "total": 5
      }
    },
    {
    	"workgroup": "stock_holders",
			"counts": {
  			"filter": 0,
  			"forward": 0,
  			"mailbox": 0,
  			"total": 0
      }
    },
    {
    	"workgroup": "sysadmins",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      } 
    }
	], 
}

Example 3

Retrieves the first three workgroups that start with 's' in the domain example.com.

Request

{
  "credentials": {
		"user": "[email protected]",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
  },
  "range": {
    "first": 0,
    "limit": 3
	} 
}

Response

{
  "success": true,
  "count": 3,
  "total_count": 5,
  "workgroups": [
    {
      "workgroup": "sales",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 1,
        "total": 1
      } 
    },
    {
    	"workgroup": "sales_europe",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
      } 
    },
    {
    	"workgroup": "staff",
      "counts": {
				"filter": 0,
        "forward": 1,
        "mailbox": 4,
        "total": 5
      } 
    }
  ], 
}

Example 4

Retrieves the next three workgroups that start with 's' in the domain example.com.

Request

{
  "credentials": {
		"user": "[email protected]",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
	}, 
	"range": {
		"first": 3,
		"limit": 3 
 	}
}

Response

{
  "success": true,
  "count": 2,
  "total_count": 5,
  "workgroups": [
    {
      "workgroup": "stock_holders",
      	"counts": {
      	"filter": 0,
				"forward": 0,
				"mailbox": 0,
				"total": 0
      } 
    },
    {
    	"workgroup": "sysadmins",
      "counts": {
        "filter": 0,
        "forward": 0,
        "mailbox": 0,
        "total": 0
			} 
		}
	], 
}

Example 5

Retrieves the first three workgroups that start with 's' in the domain example.com, sorting by number of users in the workgroup, in descending order.

Request

{
  "credentials": {
		"user": "[email protected]",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com",
    "match": "s*"
	}, 
	"range": {
    "first": 0,
    "limit": 3
  }, 
  "sort": {
    "by": "users",
    "direction": "descending"
  }
}

Response

{
  "success": true,
  "workgroups": [
    {
      "workgroup": "staff",
      "counts": {
        "filter": 0,
        "forward": 1,
        "deleted": 2,
        "mailbox": 4,
        "total": 5
			} 
		},
    {
      "workgroup": "sales",
      "counts": {
        "filter": 0,
        "forward": 0,
        "deleted": 0,
        "mailbox": 1,
        "total": 1
			} 
		},
		{
      "workgroup": "sales_europe",
      "counts": {
        "filter": 0,
        "forward": 0,
        "deleted": 0,
				"mailbox": 0,
				"total": 0
      } 
    }
  ],
  "count": 3,
  "total_count": 5
}

Updated 1 day ago