Guides
Guides
Start typing to search…

search_users

The search_users method searches for users in a specified domain. You must specify the domain to search, and you can submit other criteria to narrow your search. Each additional criteria field that you specify further narrows the search, and wildcard characters are allowed.

Syntax

Request

{
		<credentials object>, 
    "criteria": {
					"domain": <domain name>,
					"workgroup": <workgroup name>,
					"type": [<one or more of mailbox, filter, forward, or alias>]
					"match": <wildcard pattern>,
        	"deleted": TRUE | FALSE,
					"status": [<one or more of active, deleted, suspended, 
smtplimit, or quota>]
		}
		"range": {
				"first": <number>,
				"limit": <number> 
    }
		"sort": {
				by: <createtime | delete_time | id | lastlogin | status | 
target | type | user | workgroup>,
        direction: <ascending | descending>
    }
		"fields": [<one or more of createtime, forward, lastlogin , 
smtplimit, status, or workgroup>]
 }

Response

{
	"success": true, 
  "count": <number>,
	"total_count": <number>, 
  "users": [
	  {
			"user": <user name>,
			"workgroup": <workgroup name>,
			"type": mailbox |filter | forward | alias, 
      "forward_recepient_count": <number>, 
      "forward_recepient": <email address>, 
      "alias_target": <username>,
			"id":<string>,
			"status":<string>,
			"createtime":<epoch timestamp>, 
      "lastlogin":<epoch timestamp>
		}
		<...> 
  ]
}

Request fields for search_users

The following fields can be used in the search_users method:

Field name

Obligation

Definition/Value

criteria

Required

Narrows the results by restricting the search to the specified fields and their values.

  • *Note**: You must specify the domain; all other criteria are optional.

Allowed values are:

  • deleted — Specifies whether to return only deleted user accounts. Allowed values are true and false.

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

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

  • ? ― Match a single character

  • * ― Match multiple characters.

  • status — Returns only those user account with the specified status. If not specified, returns all statuses except deleted. Allowed values are:

  • active — Mailbox is currently active.

  • deleted — Mailbox has been deleted.

  • quota — Mailbox is over quota and cannot receive any more mail.

  • smtplimit — Mailbox is at the smtp limit and user cannot send any more mail.

  • suspended — Mailbox has been suspended and user cannot send or receive mail.

  • type — Returns only user accounts of the specified type. Allowed values are:

  • alias — Alias mailboxes

  • filter — Filter-only mailboxes

  • forward — Forward-only mailboxes

  • mailbox — Regular mailboxes

  • workgroup — Returns only user accounts in the specified workgroup.

The criteria fields work together to restrict the results, for example, if both workgroup and match are specified, the method returns only those users that are in that workgroup and match the pattern.

fields

Optional

Additional fields to return. Allowed values are: createtime, forward, lastlogin, status, type, and workgroup.

If not specified, defaults to workgroup and status.

range

Optional

Limits the range of user accounts to display. Allowed values are:

  • first — Specify the first user to return; the default is the first result.

  • limit — Specify the maximum number of users 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:

  • createtime — The date when the account was create, in UNIX Epoch time.

  • delete_time — The time the user account was deleted. Can be used only if criteria = deleted.

  • id — The identification number of the soft deleted account.

  • lastlogin — The last time (displayed in UNIX Epoch time) that the user successfully logged in via pop3, imap4, webmail, or smtprelay.

  • status — The status of the account.

  • target — The alias target or forward target of the user.

  • type — The type of user: alias, filter, forward, or mailbox.

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

  • workgroup — The user's workgroup.

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

Response fields for search_users

The following fields may be returned when the search_users method is submitted:

Field name

Obligation

Description/Value

count

Returned if success = true

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

users

Returned if success = true

A list of the mailboxes that meet the criteria, and, optionally, their attributes.

Allowed values are:

  • alias_target — The user for which this account is an alias. Returned only if the account is an alias.

  • createtime — The date when the account was create, in UNIX Epoch time. Only displayed if specified in the fields part of the request.

  • forward_recipient — Returned only if the mailbox forwards to one or more addresses. If the mailbox forwards to only one address, that address is displayed; otherwise, the returned value is null.

  • forward_recipient_count — Returned only if the mailbox forwards to one or more addresses. Specifies the number of addresses to which this account forwards.

  • id — The identification number of the account. Returned only if deleted = true.

  • lastlogin — The last time (displayed in UNIX Epoch time) that the user successfully logged in via pop3, imap4, webmail, or smtprelay. Not returned for aliases. Only present if specified in fields part of request.

  • *Note**: The lastlogin timestamp may be up to 48 hours out of date.

    • status — The status of the account. May be one of the following:

    • active — mailbox is currently active

    • deleted — mailbox has been deleted

    • quota — mailbox is over quota and cannot receive any more mail.

    • smtplimit — mailbox is at the smtp limit and user cannot send any more mail.

    • suspended— mailbox has been suspended and user cannot send or receive mail.

    • type — The type of account. May be one of the following:

    • alias — Alias mailbox

    • filter — Filter-only mailbox

    • forward — Forward-only mailbox

    • mailbox — Regular mailbox

    • user — The user name for the account.

    • workgroup — The workgroup to which the user account belongs. Returned only if the user is not an alias.

Examples for search_users

Example 1

Searches for all users in the domain example.com.

Request

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

Response

{
  "success": true,
  "users": [
		{
			"workgroup": "staff",
			"user": "[email protected]",
			"status": "active",
  		"type": "mailbox"
		},
		{
			"workgroup": "staff",
			"user": "[email protected]", "status": "active",
			"type": "mailbox"
    }, 
    {
    	"workgroup": "staff",
			"forward_recipient": "[email protected]", 
      "forward_recipient_count": 1,
			"user": "[email protected]",
			"status": "active",
			"type": "forward"
    }, 
    {
    	"workgroup": "interns",
			"user": "[email protected]",
			"status": "active",
			"type": "mailbox"
    }, 
    {
    	"user": "[email protected]", 
      "alias_target": "[email protected]", 
      "status": "active",
			"type": "alias"
    }, 
    {
    	"workgroup": "interns",
			"user": "[email protected]",
			"status": "active",
			"type": "mailbox"
    }, 
    {
    	"workgroup": "interns",
      "forward_recipient": null,
      "forward_recipient_count": 2,
      "user": "[email protected]",
      "status": "active",
      "type": "forward"
    }, 
    {
    	"workgroup": "staff",
			"user": "[email protected]",
			"status": "active",
			"type": "mailbox"
    }, 
    {
    	"workgroup": "staff",
			"user": "[email protected]",
			"status": "active",
			"type": "mailbox"
    }, 
    {
    	"workgroup": "sales",
			"user": "[email protected]",
			"status": "active",
			"type": "mailbox"
    } 
  ],
  "count": 10,
  "total_count": 10
}

Example 2

Retrieves all users in the domain example.com, sorted by workgroup, in reverse alphabetical order .

Request

{
  "credentials": {
    "user": "[email protected]",
    "password": "pencil75"
  },
  "criteria": {
    "domain": "example.com"
  }, 
  "sort": {
    "by": "workgroup",
    "direction": "descending"
  }
}

Response

{
  "success": true,
  "users": [
		{
			"workgroup": "staff",
			"user": "[email protected]", 
      "status": "active",
			"type": "mailbox"
		}, 
		{
    	"workgroup": "staff",
			"user": "[email protected]", 
      "status": "active",
			"type": "mailbox"
    }, 
		{
    	"workgroup": "staff",
			"forward_recipient": "[email protected]", 
      "forward_recipient_count": 1,
      "user": "[email protected]",
      "status": "active",
      "type": "forward"
    }, 
		{
    	"workgroup": "staff",
      "user": "[email protected]",
      "status": "active",
      "type": "mailbox"
    }, 
		{
    	"workgroup": "staff",
      "user": "[email protected]", 
      "status": "active",
      "type": "mailbox"
    }, 
		{
    	"workgroup": "sales",
			"user": "[email protected]",
			"status": "active",
      "type": "mailbox"
    }, 
		{
    	"workgroup": "interns",
      "user": "[email protected]",
      "status": "active",
      "type": "mailbox"
    }, 
		{
    	"workgroup": "interns",
      "user": "[email protected]",
      "status": "active",
      "type": "mailbox"
    }, 
		{
    	"workgroup": "interns",
      "forward_recipient": null,
      "forward_recipient_count": 2,
      "user": "[email protected]",
      "status": "active",
      "type": "forward"
    }, 
    {
    	"user": "[email protected]", 
      "alias_target": "[email protected]", 
      "status": "active",
			"type": "alias"
    } 
  ],
  "count": 10,
  "total_count": 10
}

Example 3

Retrieves all the forward and alias users in the domain example.com.

Request

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

Response

{
  "success": true,
  "users": [
		{
			"workgroup": "staff",
			""forward_recipient": "[email protected]", 
      ""forward_recipient_count": 1,
			""user": "[email protected]",
			"status": "active",
			""type": "forward"
    }, 
    {
    	"user": "[email protected]", 
      "alias_target": "[email protected]", 
      "status": "active",
			"type": "alias"
    }, 
    {
    	"workgroup": "interns",
    	"forward_recipient": null,
			"forward_recipient_count": 2,
			"user": "[email protected]",
			"status": "active",
			"type": "forward"
    }
  ],
  "count": 3,
  "total_count": 3
}

Example 4

Retrieves the first three users in the domain example.com.

Request

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

Response

{
  "success": true,
  "users": [
  	{
			"workgroup": "staff",
			"user": "[email protected]", 
      "status": "active",
			"type": "mailbox"
		}, 
    {
    	"workgroup": "staff",
			"user": "[email protected]", 
      "status": "active",
			"type": "mailbox"
    }, 
    {
    	"workgroup": "staff",
      "forward_recipient": "[email protected]", 
      "forward_recipient_count": 1,
			"user": "[email protected]",
			"status": "active",
      "type": "forward"
    }
	],
  "count": 3,
	"total_count": 10
}

Example 5

Retrieves the second three users in the domain example.com.

Request

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

Response

{
  "success": true,
  "users": [
    {
      "workgroup": "interns",
      "user": "[email protected]",
      "status": "active",
      "type": "mailbox"
    },
		{
			"user": "[email protected]", 
      "alias_target": "[email protected]", "status": "active",
			"type": "alias"
		}, 
		{
    	"workgroup": "interns",
			"user": "[email protected]",
			"status": "active",
			"type": "mailbox"
    } 
  ],
  "count": 3,
  "total_count": 10
}

Example 6

Retrieves all deleted users in the domain example.com.

Request

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

Response

{
  "success": true,
  "users": [
    {
      "workgroup": "staff",
      "user": "[email protected]",
      "type": "mailbox",
      "status": "deleted",
      "id": "1321905217"
} ],
"count": 1,
  "total_count": 1
}

Example 7

Request

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

Response

{
  "success": true,
  "users": [
    {
      "status": "quota",
      "user": "[email protected]",
      "lastlogin": "",
      "createtime": "1340021200"
		}, 
		{
    	"status": "smtplimit",
      "user": "[email protected]",
      "lastlogin": "",
      "createtime": "1340021200"
    }, 
		{
    	"status": "suspended",
      "user": "[email protected]",
      "lastlogin": "",
      "createtime": "1340021200"
    }, 
		{
    	"status": "active",
			"user": "[email protected]",
			"lastlogin": "1350000000",
			"createtime": "1330971427"
    } 
  ],
  		"count": 4,
      "total_count": 4,
      "audit": "pin28_514b678124"
}

Updated 1 day ago