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 less than a minute ago