Skip to main content

Queries the list of mail groups

GET/v2/groups

Queries the mail groups under the current organization. Returns up to 30 entries per request.

Filter Criteria​

Use filter expressions to filter mail groups. The supported fields are email, name, status, domain, and type. For example:

  • (name=*Engineering*): Names containing "Engineering".
  • (|(name=Jack)(email=*jack*)): Name is "Jack", or the email address contains jack.
  • (&(type=DYNAMIC)(status=FREEZE)): Type is dynamic group and status is frozen.
  • (domain=example.com): Belongs to the subdomain example.com.

Sorting​

Supports sorting by email, name, or createdTime.

Request​

Query parameters

    filter string

    Filter expression.

    cursor string
    size number

    Page size, maximum 100.

    types array

    Specifies the type. If not specified, returns all types of groups. This parameter will be deprecated in a future version. Use filter to specify the type.

    orderby string

    Sort field. If not specified, sorting is by creation time in descending order.

    order enum

    Possible values: [ASC, DES]

    • ASC:
    • DES:
    $select string

Response

    groups object[]
    id string

    id

    name stringrequired

    Group name.

    email stringrequired

    Group email address.

    status enum

    Status. Only the domain administrator or authorized applications can modify it.

    • NORMAL: Normal
    • FREEZE: Frozen

    Possible values: [NORMAL, FREEZE]

    createdTime number<int64>

    Creation time.

    itemCount number<int32>

    Number of first-level static members.

    admins string[]

    Administrator. Can only be modified by an administrator or an authorized application. (Optional field: returned when you add the $select=admins query parameter to the URL. To query multiple fields, separate them with commas.)

    needMessageDeliveryReview boolean

    Indicates whether message delivery review is required. This field is accessible only to administrators or authorized applications and can be modified. (Optional field: It is returned when the $select=needMessageDeliveryReview query parameter is added to the URL. For multiple fields, use commas to separate them.)

    messageDeliveryReviewers string[]

    Message delivery reviewer, accessible and modifiable only by administrators or authorized applications. (Optional field: returned when the query parameter $select=messageDeliveryReviewers is added to the URL. Separate multiple fields with commas.)

    allowedSenders string[]

    The persons allowed to send messages to this group. Only accessible and modifiable by administrators or authorized applications. (Optional field: returns when the $select=allowedSenders query parameter is added to the URL. Use commas to separate multiple fields.)

    allowedSenderPolicy enum

    Specifies who can send messages to this group. Accessible and modifiable only by administrators or authorized applications. (Optional field: returned by adding the $select=allowedSenderPolicy query parameter in the URL. Use commas to separate multiple fields.)

    • ANYONE:
    • SAME_ORGANIZATION:
    • GROUP_MEMBER:
    • ONLY_ALLOWED_SENDER:
    • GROUP_MEMBER_AND_ALLOWED_SENDER:

    Possible values: [ANYONE, SAME_ORGANIZATION, GROUP_MEMBER, ONLY_ALLOWED_SENDER, GROUP_MEMBER_AND_ALLOWED_SENDER]

    type enum

    Group type. Only accessible by administrators or authorized applications. (Optional field: returned by adding the $select=type query parameter in the URL. Separate multiple fields with commas.)

    • STATIC: Static group
    • DEPARTMENT: Department group
    • DYNAMIC: Dynamic group
    • USERGROUP: User group
    • DING: DingTalk group

    Possible values: [STATIC, DEPARTMENT, DYNAMIC, USERGROUP, DING]

    dynamicMatchRule string

    Dynamic group member matching rules. Only accessible and modifiable by administrators or authorized applications. (Optional field: returns when the $select=dynamicMatchRule query parameter is added to the URL. For multiple fields, use English commas to separate them.)

    itemCountLimit number<int32>

    Maximum member limit, up to 100000. Only the administrator or authorized applications can modify it (Optional field: returned after adding the $select=itemCountLimit query parameter in the URL. For multiple fields, separate them with commas).

    containOuterMember boolean

    Whether to include external members (Optional field: returned when the query parameter $select=containOuterMember is added to the URL. Use commas to separate multiple fields if needed.)

    departmentId string

    Department of the user (optional field: returned when the $select=departmentId query parameter is added to the URL; separate multiple fields with commas).

    isHidden boolean

    Whether to display this group in the address book. Only administrators or authorized applications can access it; can be modified. (Optional field: returned when the $select=isHidden query parameter is added to the URL; separate multiple fields with commas.)

    creator string

    Creator email, accessible only by administrators or authorized applications. (Optional field: Return by adding the $select=creator query parameter in the URL; separate multiple fields with commas.)

    lastRecvMessageTime string<date-time>

    Time of the last received message ( Optional field: returned when the $select=lastRecvMessageTime query parameter is added in the URL; use commas to separate multiple fields).

    ignoreAutoReplyOfMember boolean

    Ignores the auto-reply of members. Accessible and modifiable only by administrators or authorized applications. (Optional field: returned by adding the $select=ignoreAutoReplyOfMember query parameter in the URL. Use commas to separate multiple fields.)

    sendMessageToNewMember boolean

    Indicates whether to send a notification letter to newly added members. Accessible only by administrators or authorized applications, modifiable. (Optional field: Returned by adding the $select=sendMessageToNewMember query parameter in the URL. Separate multiple fields with commas.)

    requireApprovalWhenMemberLeaves boolean

    Whether administrator approval is required when a member leaves. Only accessible by domain administrators or authorized applications. Modifiable. (Optional field: returned when the $select=requireApprovalWhenMemberLeaves query parameter is added to the URL. Use English commas to separate multiple fields.)

    memberOnlyVisibleToAdmin boolean

    Whether the member is visible only to the administrator. Only the domain administrator or an authorized application can modify it (Optional field: returned after adding the $select=memberOnlyVisibleToAdmin query parameter in the URL. Use commas to separate multiple fields).

    nextCursor string
    hasMore boolean

Errors

401

Access is unauthorized. Please check whether the correct authorization token is passed.

403

No API access permission. Please complete the relevant authorization on the application management page of the domain administrator.