This function retrieves one GSuite group or all GSuite groups in a domain.
    This function returns either PSCustomObject when there is one group, or Object[] when there is more than one group.

function Get-GSuiteGroup {
    [OutputType([Object[]], [PSCustomObject])]
    param (
        # The primary email address for the group.
        [Parameter(Mandatory=$true, ParameterSetName="Email")]

        # The domain for the groups.
        [Parameter(Mandatory=$true, ParameterSetName="Domain")]

        # Whether to retrieve all the GSuite groups.
        [Parameter(Mandatory=$true, ParameterSetName="All")]

    # Validate that the 'connection' has been established and the group access token exists
    Assert-GSuiteConnection -Scope "Group"

    # Retrieve the group with the specified email address
    if ($primaryEmailAddress) {
        $Uri = "$($primaryEmailAddress)"

    # Retrieve all the groups in the specified domain
    elseif ($domain) {
        $Uri = "$($domain)"

    # Retrieve all the groups
    else {
        $Uri = ""

    # Prepare the REST call parameters
    $invokeRestMethodParams = @{
        Uri     = $Uri
        Method  = "GET"
        Headers = @{
            Accept        = "application/json"
            Authorization = "Bearer $($Global:GSuiteAccessTokensHashTable.Group)"

    # Invoke the REST call
    $response = Invoke-RestMethod @invokeRestMethodParams

    # Return the group if $primaryEmailAddress is specified
    if ($primaryEmailAddress) {
        return $response

    # Return the groups if $domain or $all is specified
    return $response.groups