MSGraph

1.2.9.1

MSGraph.psm1

$script:ModuleRoot = $PSScriptRoot
$script:ModuleVersion = (Import-PowerShellDataFile -Path "$($script:ModuleRoot)\MSGraph.psd1").ModuleVersion

# Detect whether at some level dotsourcing was enforced
$script:doDotSource = Get-PSFConfigValue -FullName MSGraph.Import.DoDotSource -Fallback $false
if ($MSGraph_dotsourcemodule) { $script:doDotSource = $true }

<#
Note on Resolve-Path:
All paths are sent through Resolve-Path/Resolve-PSFPath in order to convert them to the correct path separator.
This allows ignoring path separators throughout the import sequence, which could otherwise cause trouble depending on OS.
Resolve-Path can only be used for paths that already exist, Resolve-PSFPath can accept that the last leaf my not exist.
This is important when testing for paths.
#>

# Detect whether at some level loading individual module files, rather than the compiled module was enforced
$importIndividualFiles = Get-PSFConfigValue -FullName MSGraph.Import.IndividualFiles -Fallback $false
if ($MSGraph_importIndividualFiles) { $importIndividualFiles = $true }
if (Test-Path (Resolve-PSFPath -Path "$($script:ModuleRoot)\..\.git" -SingleItem -NewChild)) { $importIndividualFiles = $true }
if ("<was compiled>" -eq '<was not compiled>') { $importIndividualFiles = $true }

function Import-ModuleFile {
    <#
        .SYNOPSIS
            Loads files into the module on module import.
 
        .DESCRIPTION
            This helper function is used during module initialization.
            It should always be dotsourced itself, in order to proper function.
 
            This provides a central location to react to files being imported, if later desired
 
        .PARAMETER Path
            The path to the file to load
 
        .EXAMPLE
            PS C:\> . Import-ModuleFile -File $function.FullName
 
            Imports the file stored in $function according to import policy
    #>
    [CmdletBinding()]
    Param (
        [string]
        $Path
    )

    if ($doDotSource) { . (Resolve-Path $Path) }
    else { $ExecutionContext.InvokeCommand.InvokeScript($false, ([scriptblock]::Create([io.file]::ReadAllText((Resolve-Path $Path)))), $null, $null) }
}

#region Load individual files
if ($importIndividualFiles) {
    # Execute Preimport actions
    . Import-ModuleFile -Path "$ModuleRoot\internal\scripts\preimport.ps1"

    # Import all internal functions
    foreach ($function in (Get-ChildItem "$ModuleRoot\internal\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)) {
        . Import-ModuleFile -Path $function.FullName
    }

    # Import all public functions
    foreach ($function in (Get-ChildItem "$ModuleRoot\functions" -Filter "*.ps1" -Recurse -ErrorAction Ignore)) {
        . Import-ModuleFile -Path $function.FullName
    }

    # Execute Postimport actions
    . Import-ModuleFile -Path "$ModuleRoot\internal\scripts\postimport.ps1"

    # End it here, do not load compiled code below
    return
}
#endregion Load individual files

#region Load compiled code
Add-Type -AssemblyName System.Net.Http
Add-Type -AssemblyName System.Web
Add-Type -AssemblyName System.Windows.Forms

function Merge-HashToJson {
    <#
    .SYNOPSIS
        Merge a hashtable(s) object to a JSON data string(s)
 
    .DESCRIPTION
        Merge a hashtable(s) object to a JSON data string(s)
        Accepts [hashtable] object(s) as well as [System.Collections.Specialized.OrderedDictionary] object(s)
 
        Helper function used for internal commands.
 
    .PARAMETER Hashtable
        The hashtable to convert to json
 
    .PARAMETER OrderedHashtable
        A hash created by [ordered]@{} to convert to json
 
    .EXAMPLE
        PS C:\> Merge-HashToJson $hash
 
        Creates a json string from content in variable $hash.
        This is the recommend usage
 
        Variable $hash can be:
            $hash = @{ content = "this is a regular hashtable" }
        or
            $hash = [ordered]@{ content = "this is a ordered hashtable" }
 
    .EXAMPLE
        PS C:\> Merge-HashToJson -Hashtable $hash
 
        Creates a json string from content in variable $hash.
        Variable $hash has to be a regular hashtable:
            $hash = @{ content = "this is a regular hashtable" }
 
    .EXAMPLE
        PS C:\> Merge-HashToJson -OrderedHashtable $hash
 
        Creates a json string from content in variable $hash.
        Variable $hash has to be a ordered hashtable:
            $hash = @{ content = "this is a regular hashtable" }
 
    #>
    #[CmdletBinding(ConfirmImpact = 'Low', DefaultParameterSetName = "OrderedHash")]
    [CmdletBinding(ConfirmImpact = 'Low')]
    [OutputType([String])]
    param (
        [Parameter(ParameterSetName = "HashTable", Position = 0, Mandatory = $true)]
        [hashtable[]]
        $Hashtable,

        [Parameter(ParameterSetName = "OrderedHash", Position = 0, Mandatory = $true)]
        [System.Collections.Specialized.OrderedDictionary[]]
        $OrderedHashtable
    )

    begin {
    }

    process {
        if ($PSCmdlet.ParameterSetName -like "OrderedHash") {
            $Hashtable = [ordered]@{}
            $Hashtable = $OrderedHashtable
        }

        Write-PSFMessage -Level Debug -Message "Merge hashtable with key(s) ('$([string]::Join("', '", $Hashtable.Keys))') by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"
        foreach ($hash in $Hashtable) {
            $JsonParts = @()

            foreach ($key in $hash.Keys) {
                $JsonParts = $JsonParts + """$($key)"" : $($hash[$key])"
            }
            $json = "{`n" + ([string]::Join(",`n", $JsonParts)) + "`n}"

            $json
        }
    }

    end {
    }
}


function Convert-UriQueryFromHash {
    <#
    .SYNOPSIS
        Converts hashtables to a string for REST api calls.
 
    .DESCRIPTION
        Converts hashtables to a string for REST api calls.
 
    .PARAMETER hash
        The hashtable to convert to a string
 
    .PARAMETER NoQuestionmark
        Supress the ? as the first character in the output string
 
    .EXAMPLE
        PS C:\> Convert-UriQueryFromHash -Hash @{ username = "user"; password = "password"}
 
        Converts the specified hashtable to the following string:
        ?password=password&username=user
 
    .EXAMPLE
        PS C:\> Convert-UriQueryFromHash -Hash @{ username = "user"; password = "password"} -NoQuestionmark
 
        Converts the specified hashtable to the following string:
        password=password&username=user
        #>
    [OutputType([System.String])]
    [CmdletBinding()]
    param (
        [Parameter(ValueFromPipeline = $true, Mandatory = $true)]
        [System.Collections.Hashtable]
        $Hash,

        [switch]
        $NoQuestionmark
    )

    begin {
    }

    process {
        $elements = foreach ($key in $Hash.Keys) {
            $key + "=" + $Hash[$key]
        }
        $elementString = [string]::Join("&", $elements)

        if ($NoQuestionMark) {
            "$elementString"
        } else {
            "?$elementString"
        }
    }

    end {
    }
}

function ConvertFrom-Base64StringWithNoPadding( [string]$Data ) {
    <#
    .SYNOPSIS
        Helper function build valid Base64 strings from JWT access tokens
 
    .DESCRIPTION
        Helper function build valid Base64 strings from JWT access tokens
 
    .PARAMETER Data
        The Token to convert
 
    .EXAMPLE
        PS C:\> ConvertFrom-Base64StringWithNoPadding -Data $data
 
        build valid base64 string the content from variable $data
    #>
    $Data = $Data.Replace('-', '+').Replace('_', '/')
    switch ($Data.Length % 4) {
        0 { break }
        2 { $Data += '==' }
        3 { $Data += '=' }
        default { throw New-Object ArgumentException('data') }
    }
    [System.Convert]::FromBase64String($Data)
}

function ConvertFrom-JWTtoken {
    <#
    .SYNOPSIS
        Converts access tokens to readable objects
 
    .DESCRIPTION
        Converts access tokens to readable objects
 
    .PARAMETER Token
        The Token to convert
 
    .EXAMPLE
        PS C:\> ConvertFrom-JWTtoken -Token $Token
 
        Converts the content from variable $token to an object
    #>
    [cmdletbinding()]
    param(
        [Parameter(Mandatory = $true)]
        [string]
        $Token
    )

    # Validate as per https://tools.ietf.org/html/rfc7519 - Access and ID tokens are fine, Refresh tokens will not work
    if ((-not $Token.Contains(".")) -or (-not $Token.StartsWith("eyJ"))) {
        $msg = "Invalid data or not an access token. $($Token)"
        Stop-PSFFunction -Message $msg -Tag "JWT" -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg))
    }

    # Split the token in its parts
    $tokenParts = $Token.Split(".")

    # Work on header
    $tokenHeader = [System.Text.Encoding]::UTF8.GetString( (ConvertFrom-Base64StringWithNoPadding $tokenParts[0]) )
    $tokenHeaderJSON = $tokenHeader | ConvertFrom-Json

    # Work on payload
    $tokenPayload = [System.Text.Encoding]::UTF8.GetString( (ConvertFrom-Base64StringWithNoPadding $tokenParts[1]) )
    $tokenPayloadJSON = $tokenPayload | ConvertFrom-Json

    # Work on signature
    $tokenSignature = ConvertFrom-Base64StringWithNoPadding $tokenParts[2]

    # Output
    $resultObject = New-Object MSGraph.Core.JWTAccessTokenInfo

    $resultObject.Header = $tokenHeader
    $resultObject.Payload = $tokenPayload
    $resultObject.Signature = $tokenSignature
    $resultObject.Algorithm = $tokenHeaderJSON.alg
    $resultObject.Type = $tokenHeaderJSON.typ
    if ($tokenPayloadJSON.appid) { $resultObject.ApplicationID = $tokenPayloadJSON.appid }
    $resultObject.ApplicationName = $tokenPayloadJSON.app_displayname
    $resultObject.Audience = $tokenPayloadJSON.aud
    $resultObject.AuthenticationMethod = $tokenPayloadJSON.amr
    $resultObject.ExpirationTime = ([datetime]"1970-01-01Z00:00:00").AddSeconds($tokenPayloadJSON.exp).ToUniversalTime()
    $resultObject.GivenName = $tokenPayloadJSON.given_name
    $resultObject.IssuedAt = ([datetime]"1970-01-01Z00:00:00").AddSeconds($tokenPayloadJSON.iat).ToUniversalTime()
    $resultObject.Name = $tokenPayloadJSON.name
    $resultObject.NotBefore = ([datetime]"1970-01-01Z00:00:00").AddSeconds($tokenPayloadJSON.nbf).ToUniversalTime()
    if ($tokenPayloadJSON.oid) { $resultObject.OID = $tokenPayloadJSON.oid }
    $resultObject.Plattform = $tokenPayloadJSON.platf
    $resultObject.Scope = $tokenPayloadJSON.scp
    $resultObject.SID = $tokenPayloadJSON.onprem_sid
    $resultObject.SourceIPAddr = $tokenPayloadJSON.ipaddr
    $resultObject.SureName = $tokenPayloadJSON.family_name
    $resultObject.TenantID = $tokenPayloadJSON.tid
    $resultObject.UniqueName = $tokenPayloadJSON.unique_name
    $resultObject.UPN = $tokenPayloadJSON.upn
    $resultObject.Version = $tokenPayloadJSON.ver

    #$output
    $resultObject
}

function Invoke-TokenLifetimeValidation {
    <#
    .SYNOPSIS
        Validates the lifetime of a token object
 
    .DESCRIPTION
        Validates the lifetime of a token object and invoke update-token process, if needed.
        Helper function used for internal commands.
 
    .PARAMETER Token
        The Token to test and receive
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> Resolve-Token -User $Token
 
        Test Token for lifetime, or receives registered token from script variable
    #>
    [OutputType([MSGraph.Core.AzureAccessToken])]
    [CmdletBinding()]
    param (
        [MSGraph.Core.AzureAccessToken]
        $Token,

        [String]
        $FunctionName = $MyInvocation.MyCommand
    )

    process {
        $Token = Resolve-Token -Token $Token -FunctionName $FunctionName

        if ( (-not $Token.IsValid) -or ($Token.PercentRemaining -lt 15) ) {
            # if token is invalid or less then 15 percent of lifetime -> go and refresh the token
            Write-PSFMessage -Level Verbose -Message "Token lifetime is less then 15%. Initiate token refresh. Time remaining $($Token.TimeRemaining)" -Tag "Authentication" -FunctionName $FunctionName
            $paramsTokenRefresh = @{
                Token    = $Token
                PassThru = $true
            }
            if ($script:msgraph_Token.AccessTokenInfo.Payload -eq $Token.AccessTokenInfo.Payload) { $paramsTokenRefresh.Add("Register", $true) }
            if ($Token.Credential) { $paramsTokenRefresh.Add("Credential", $Token.Credential) }
            $Token = Update-MgaAccessToken @paramsTokenRefresh
        } else {
            Write-PSFMessage -Level Verbose -Message "Valid token for user $($Token.UserprincipalName) - Time remaining $($Token.TimeRemaining)" -Tag "Authentication" -FunctionName $FunctionName
        }

        $Token
    }
}

function Invoke-TokenScopeValidation {
    <#
    .SYNOPSIS
        Validates the scope of a token object
 
    .DESCRIPTION
        Validates the scope of a token object and invoke update-token process, if needed.
        Helper function used for internal commands.
 
    .PARAMETER Token
        The Token to test.
 
    .PARAMETER Scope
        The scope(s) the check for existence.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
        (Just used for logging reasons)
 
    .EXAMPLE
        PS C:\> $Token = Invoke-TokenScopeValidation -User $Token -Scope "Mail.Read"
 
        Test Token for scope and return the token. If necessary, the token will be renewed
    #>
    [OutputType([MSGraph.Core.AzureAccessToken])]
    [CmdletBinding()]
    param (
        [MSGraph.Core.AzureAccessToken]
        $Token,

        [Parameter(Mandatory = $true)]
        [string[]]
        $Scope,

        [String]
        $FunctionName = $MyInvocation.MyCommand
    )

    process {
        $Token = Resolve-Token -Token $Token -FunctionName $FunctionName

        if (-not (Test-TokenScope -Token $Token -Scope $requiredPermission -FunctionName $FunctionName)) {
            # required scope information are missing in token
            Write-PSFMessage -Level Warning -Message "Required scope information ($([String]::Join(", ",$Scope))) are missing in token." -Tag "Authentication" -FunctionName $FunctionName
            if ($Token.IdentityPlatformVersion -like '2.0') {
                # With Microsoft Identity Platform 2.0 it is possible to dynamically query new scope informations (incremental consent)
                Write-PSFMessage -Level Verbose -Message "Microsoft Identity Platform 2.0 is used. Dynamical permission request possible. Try to aquire new token." -Tag "Authentication" -FunctionName $FunctionName

                $Scope = $Scope + $Token.Scope
                $tenant = if ($Token.TenantID -like "9188040d-6c67-4c5b-b112-36a304b66dad") {'consumers'} else {'common'}

                # build parameters to query new token
                $paramsNewToken = @{
                    PassThru                = $true
                    ClientId                = $Token.ClientId.ToString()
                    RedirectUrl             = $Token.AppRedirectUrl.ToString()
                    ResourceUri             = $Token.Resource.ToString().TrimEnd('/')
                    IdentityPlatformVersion = $Token.IdentityPlatformVersion
                    Permission              = ($Scope | Where-Object { $_ -notin "offline_access", "openid", "profile", "email" })
                    Tenant                  = $tenant
                }
                if ($script:msgraph_Token.AccessTokenInfo.Payload -eq $Token.AccessTokenInfo.Payload) {
                    $paramsNewToken.Add("Register", $true)
                }
                if ($Token.Credential) {
                    $paramsNewToken.Add("Credential", $Token.Credential)
                }

                $Token = New-MgaAccessToken @paramsNewToken
            } else {
                Stop-PSFFunction -Message "FAILED, missing required scope information ($([String]::Join(", ",$Scope))) and Microsoft Identity Platform 1.0 is used.`nNo dynamic permission request available. Permissions has to be specified/granted in app registration process or portal." -EnableException $true -Category AuthenticationError -FunctionName $FunctionName
            }
        } else {
            Write-PSFMessage -Level VeryVerbose -Message "OK, required scope information are present. ($([String]::Join(", ",$Scope)))" -Tag "Authentication" -FunctionName $FunctionName
        }

        $Token
    }
}

function New-HttpClient {
    <#
    .SYNOPSIS
        Generates a HTTP Client.
 
    .DESCRIPTION
        Generates a HTTP Client for use with web services (REST Api).
 
    .PARAMETER UserAgentName
        The name of the UserAgent.
 
    .PARAMETER UserAgentVersion
        The Version of the UserAgent.
 
    .PARAMETER HeaderType
        Data language in the header.
 
    .EXAMPLE
        PS C:\> New-HttpClient
 
        Creates a Http Client with default values
 
    .EXAMPLE
        PS C:\> New-HttpClient -UserAgentName "PowerShellRestClient" -userAgentVersion "1.1"
 
        Creates a Http Client with UserAgent "PowerShellRestClient" as name and Version 1.1.
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding()]
    param (
        [Alias('UserAgent')]
        [String]
        $UserAgentName = (Get-PSFConfigValue -FullName MSGraph.WebClient.UserAgentName -Fallback "PowerShellRestClient"),

        [Alias('Version')]
        [String]
        $userAgentVersion = (Get-PSFConfigValue -FullName MSGraph.WebClient.UserAgentVersion -Fallback "1.1"),

        [String]
        $HeaderType = "application/json"
    )

    process {
        $header = New-Object System.Net.Http.Headers.MediaTypeWithQualityHeaderValue($HeaderType)
        $userAgent = New-Object System.Net.Http.Headers.ProductInfoHeaderValue($UserAgentName, $userAgentVersion)

        $handler = New-Object System.Net.Http.HttpClientHandler
        $handler.CookieContainer = New-Object System.Net.CookieContainer
        $handler.AllowAutoRedirect = $true

        $httpClient = New-Object System.Net.Http.HttpClient($handler)
        $httpClient.Timeout = New-Object System.TimeSpan(0, 0, 90)
        $httpClient.DefaultRequestHeaders.TransferEncodingChunked = $false
        $httpClient.DefaultRequestHeaders.Accept.Add($header)
        $httpClient.DefaultRequestHeaders.UserAgent.Add($userAgent)

        return $httpClient
    }
}

function Resolve-Token {
    <#
    .SYNOPSIS
        Test for specified Token, or receives registered token
 
    .DESCRIPTION
        Test for specified Token, or receives registered token.
        Helper function used for internal commands.
 
    .PARAMETER Token
        The Token to test and receive
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
        (Just used for logging reasons)
 
    .EXAMPLE
        PS C:\> Resolve-Token -User $Token
 
        Test Token for lifetime, or receives registered token from script variable
    #>
    [OutputType([MSGraph.Core.AzureAccessToken])]
    [CmdletBinding()]
    param (
        [MSGraph.Core.AzureAccessToken]
        $Token,

        [String]
        $FunctionName = $MyInvocation.MyCommand
    )

    process {
        if (-not $Token) {
            Write-PSFMessage -Level Debug -Message "No token on parameter in command. Getting registered token." -Tag "Authentication" -FunctionName $FunctionName
            $Token = $script:msgraph_Token
        }

        if ($Token) {
            $Token
        } else {
            Stop-PSFFunction -Message "Not connected! Use New-MgaAccessToken to create a Token and either register it or specifs it" -EnableException $true -Category AuthenticationError -FunctionName $FunctionName
        }
    }
}

function Resolve-UserString {
    <#
    .SYNOPSIS
        Converts usernames or email addresses into the user targeting segment of the Rest Api call url.
 
    .DESCRIPTION
        Converts usernames or email addresses into the user targeting segment of the Rest Api call url.
 
    .PARAMETER User
        The user to convert
 
    .PARAMETER ContextData
        Specifies, that the user string should be resolved to a @odata.context field
        Different output is needed on context URLs.
 
    .EXAMPLE
        PS C:\> Resolve-UserString -User $User
 
        Resolves $User into a legitimate user targeting string element.
 
        .EXAMPLE
        PS C:\> Resolve-UserString -User $User -ContextData
 
        Resolves $User into a legitimate user string for a @odata.context element.
    #>
    [OutputType([System.String])]
    [CmdletBinding()]
    param (
        [string]
        $User,

        [switch]
        $ContextData
    )

    if ($User -eq 'me' -or (-not $User)) {
        return 'me'
    }

    if($ContextData) {
        if ($User -like "users('*") {
            return $User
        } else {
            $userEscaped = [uri]::EscapeDataString($User)
            return "users('$($userEscaped)')"
        }
    } else {
        if ($User -like "users/*") {
            return $User
        } else {
            return "users/$($User)"
        }
    }
}

function Show-OAuthWindow {
    <#
    .SYNOPSIS
        Generates a OAuth window for interactive authentication.
 
    .DESCRIPTION
        Generates a OAuth window for interactive authentication.
 
    .PARAMETER Url
        The url to the service offering authentication.
 
    .EXAMPLE
        PS C:\> Show-OAuthWindow -Url $uri
 
        Opens an authentication window to authenticate against the service pointed at in $uri
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [System.Uri]
        $Url
    )

    process {
        $web = New-Object -TypeName System.Windows.Forms.WebBrowser -Property @{
            Width  = 420
            Height = 600
            Url    = $Url
        }
        $web.ScriptErrorsSuppressed = $true
        $web.Add_DocumentCompleted( {
                if ($web.Url.AbsoluteUri -match "error=[^&]*|code=[^&]*") { $form.Close() }
            })

        $form = New-Object -TypeName System.Windows.Forms.Form -Property @{
            Width  = 440
            Height = 640
        }
        $form.Controls.Add($web)
        $form.Add_Shown( {
                $form.BringToFront()
                $null = $form.Focus()
                $form.Activate()
                $web.Navigate($Url)
            })

        $null = $form.ShowDialog()

        $queryOutput = [System.Web.HttpUtility]::ParseQueryString($web.Url.Query)
        $output = @{}
        foreach ($key in $queryOutput.Keys) {
            $output["$key"] = $queryOutput[$key]
        }
        [pscustomobject]$output
    }
}

function Test-TokenScope {
    <#
    .SYNOPSIS
        Test for scopes existence on a Token
 
    .DESCRIPTION
        Test for existence on scopes (permissions) in a Token
        Helper function used for internal commands.
 
    .PARAMETER Token
        The Token to test.
 
    .PARAMETER Scope
        The scope(s) the check for existence.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
        (Just used for logging reasons)
 
    .EXAMPLE
        PS C:\> Test-TokenScope -User $Token -Scope "Mail.Read"
 
        Test if the specified Token contains scope "Mail.Read"
    #>
    [OutputType([bool])]
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [MSGraph.Core.AzureAccessToken]
        $Token,

        [Parameter(Mandatory = $true)]
        [string[]]
        $Scope,

        [String]
        $FunctionName = $MyInvocation.MyCommand
    )

    begin {
        $Status = $false
    }

    process {
        $Token = Resolve-Token -Token $Token -FunctionName $MyInvocation.MyCommand

        Write-PSFMessage -Level VeryVerbose -Message "Validating token scope ($([String]::Join(", ",$Token.Scope))) against specified scope(s) ($([String]::Join(", ",$Scope)))" -Tag "Authenication" -FunctionName $FunctionName
        foreach ($scopeName in $Scope) {
            foreach ($tokenScope in $Token.Scope) {
                if ($tokenScope -like "$scopeName*") {
                    Write-PSFMessage -Level Debug -Message "Token has appropriate scope ($($scopeName))" -Tag "Authenication" -FunctionName $FunctionName
                    $Status = $true
                }
            }
        }
    }

    end {
        $Status
    }
}

function Resolve-MailObjectFromString {
    <#
    .SYNOPSIS
        Resolves a name/id from a mail or folder parameter class
 
    .DESCRIPTION
        Resolves a name/id from a mail or folder parameter class to a full qualified mail or folder object and return the parameter class back.
        Helper function used for internal commands.
 
    .PARAMETER Object
        The mail or folder object
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER NoNameResolving
        If specified, there will be no checking on names. Only Id will be resolved.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> Resolve-MailObjectFromString -Object $MailFolder -User $User -Token $Token -Function $MyInvocation.MyCommand
 
        Resolves $MailFolder into a legitimate user targeting string element.
    #>
    [OutputType()]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low')]
    param (
        $Object,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $NoNameResolving,

        [String]
        $FunctionName = $MyInvocation.MyCommand
    )

    # variable definition
    $invokeParam = @{
        "User"  = $User
        "Token" = $Token
    }

    # check input object type
    if ($Object.psobject.TypeNames[0] -like "MSGraph.Exchange.Mail.FolderParameter") {
        $type = "Folder"
        $typeNamespace = "MSGraph.Exchange.Mail"
        $nounPreFix = "MgaMail"
        $parameterName = "InputObject"
    } elseif ($Object.psobject.TypeNames[0] -like "MSGraph.Exchange.Mail.MessageParameter") {
        $type = "Message"
        $typeNamespace = "MSGraph.Exchange.Mail"
        $nounPreFix = "MgaMail"
        $parameterName = "InputObject"
    } elseif ($Object.psobject.TypeNames[0] -like "MSGraph.Exchange.Category.CategoryParameter") {
        $type = "Category"
        $typeNamespace = "MSGraph.Exchange.Category"
        $nounPreFix = "MgaExch"
        if ($Object.Id) { $parameterName = "Id" } else { $parameterName = "Name" }
    } else {
        $msg = "Object '$($Object)' is not valid. Must be one of: 'MSGraph.Exchange.Mail.FolderParameter', 'MSGraph.Exchange.Mail.MessageParameter', 'MSGraph.Exchange.Category.CategoryParameter'."
        Stop-PSFFunction -Message $msg -Tag "InputValidation" -FunctionName $FunctionName -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg))
    }
    Write-PSFMessage -Level Debug -Message "Object '$($Object)' is qualified as a $($type)" -Tag "InputValidation" -FunctionName $FunctionName

    # Resolve the object
    if ($Object.Id -and (Test-MgaMailObjectId -Id $Object.Id -Type $type -FunctionName $FunctionName)) {
        Write-PSFMessage -Level Debug -Message "Going to resolve '$($Object)' with Id" -Tag "InputValidation" -FunctionName $FunctionName
        $invokeParam.Add($parameterName, $Object.Id)
        $output = .("Get-" + $nounPreFix + $type) @invokeParam
    } elseif ($Object.Name -and (-not $NoNameResolving)) {
        Write-PSFMessage -Level Debug -Message "Going to resolve '$($Object)' with name" -Tag "InputValidation" -FunctionName $FunctionName
        $invokeParam.Add($parameterName, $Object.Name)
        $invokeParam.Add("ErrorAction", "Stop")
        $output = .("Get-" + $nounPreFix + $type) @invokeParam
    } else {
        # not valid, end function without output
        Write-PSFMessage -Level Warning -Message "The specified input string seams not to be a valid Id. Skipping object '$($Object)'" -Tag "InputValidation" -FunctionName $FunctionName
        return
    }

    # output the result
    if ($output) {
        New-Object -TypeName "$($typeNamespace).$($type)Parameter" -ArgumentList $output
    }
}

function Resolve-UserInMailObject {
    <#
    .SYNOPSIS
        Resolves the user from a mail or folder parameter class
 
    .DESCRIPTION
        Resolves the user a mail or folder parameter class and compares against the specified user.
        If user in object is different, from the specified user, the user from the object is put out.
        Helper function used for internal commands.
 
    .PARAMETER Object
        The mail or folder object
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER ShowWarning
        If specified, there will be no warning output on the console.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> Resolve-UserInMailObject -Object $MailFolder -User $User -Function $MyInvocation.MyCommand
 
        Resolves the user from a mail or folder parameter class.
    #>
    [OutputType()]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low')]
    param (
        $Object,

        [string]
        $User,

        [switch]
        $ShowWarning,

        [String]
        $FunctionName = $MyInvocation.MyCommand
    )

    # check input object type
    [bool]$failed = $false
    switch ($Object.psobject.TypeNames[0]) {
        "MSGraph.Exchange.Mail.FolderParameter" {
            $namespace = "MSGraph.Exchange.Mail"
            $Type = "Folder"
        }

        "MSGraph.Exchange.Mail.MessageParameter" {
            $namespace = "MSGraph.Exchange.Mail"
            $Type = "Message"
        }

        "MSGraph.Exchange.Category.CategoryParameter" {
            $namespace = "MSGraph.Exchange.Category"
            $Type = "Category"
        }

        "MSGraph.Exchange.MailboxSetting.MailboxSettingParameter" {
            $namespace = "MSGraph.Exchange.MailboxSetting"
            $Type = "MailboxSettings"
        }

        Default { $failed = $true }
    }
    if($failed) {
        $msg = "Object '$($Object)' is not valid. Must be one of: 'MSGraph.Exchange.*.*Parameter' object types. Developers mistake!"
        Stop-PSFFunction -Message $msg -Tag "InputValidation" -FunctionName $FunctionName -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg))
    }
    Write-PSFMessage -Level Debug -Message "Object '$($Object)' is qualified as a $($Type)" -Tag "InputValidation" -FunctionName $FunctionName

    if ($ShowWarning) {
        $level = @{ Level = "Warning" }
    } else {
        $level = @{ Level = "Verbose" }
    }

    $output = ""
    # Resolve the object
    if ($User -and ($Object.TypeName -like "$($namespace).$($Type)") -and ($User -notlike $Object.InputObject.User)) {
        Write-PSFMessage @Level -Message "Individual user specified! User from $($Type)Object ($($Object.InputObject.User)) will take precedence on specified user ($($User))!" -Tag "InputValidation" -FunctionName $FunctionName
        $output = $Object.InputObject.User
    } elseif ((-not $User) -and ($Object.TypeName -like "$($namespace).$($Type)")) {
        $output = $Object.InputObject.User
    }

    # output the result
    $output
}

function Test-MgaMailObjectId {
    <#
    .SYNOPSIS
        Test for valid object ID length on folders or message objects
 
    .DESCRIPTION
        Validates the length of an Id for objects in Exchange Online
        Helper function used for internal commands.
 
    .PARAMETER Id
        The Id to test.
 
    .PARAMETER Type
        The expected type of the object
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
        (Just used for logging reasons)
 
    .EXAMPLE
        PS C:\> Test-MgaMailObjectId -Id $Id -Scope Folder
 
        Test if the specified $Id is a folder
    #>
    [OutputType([bool])]
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]
        $Id,

        [Parameter(Mandatory = $true)]
        [validateset("Folder", "Message", "Category")]
        [string]
        $Type,

        [String]
        $FunctionName = $MyInvocation.MyCommand
    )

    begin {
        $status = $false
        [guid]$guidId = [guid]::Empty
    }

    process {
        $Token = Resolve-Token -Token $Token -FunctionName $MyInvocation.MyCommand

        Write-PSFMessage -Level Debug -Message "Validating Id '$($Id)' for $($Type) length" -Tag "ValidateObjectId" -FunctionName $FunctionName
        switch ($Type) {
            "Folder" { if ($Id.Length -eq 120 -or $Id.Length -eq 104) { $status = $true } }
            "Message" { if ($Id.Length -eq 152 -or $Id.Length -eq 136) { $status = $true } }
            "Category" { if ( [guid]::TryParse($Id, [ref]$guidId) ) { $status = $true } }
        }
    }

    end {
        if ($status) { Write-PSFMessage -Level Debug -Message "Id has appropriate length ($($Id.Length)) to be a $($Type)." -Tag "ValidateObjectId" -FunctionName $FunctionName }
        $status
    }
}

function New-JsonAttachmentObject {
    <#
    .SYNOPSIS
        Creates a json attachment object for use in Microsoft Graph REST api
 
    .DESCRIPTION
        Creates a json attachment object for use in Microsoft Graph REST api
        Helper function used for internal commands.
 
    .PARAMETER Name
        The name of attachment.
 
    .PARAMETER Size
        The size in bytes of the attachment.
 
    .PARAMETER IsInline
        Set to true if this is an inline attachment.
 
    .PARAMETER LastModifiedDateTime
        The date and time when the attachment was last modified.
        The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time.
        For example, midnight UTC on Jan 1, 2014 would look like this: '2014-01-01T00:00:00Z'
 
    .PARAMETER ContentType
        The content type of the attachment.
 
    .PARAMETER contentBytes
        The base64-encoded contents of the file.
 
    .PARAMETER contentLocation
        The Uniform Resource Identifier (URI) that corresponds to the location of the content of the attachment.
 
    .PARAMETER Item
        The attached message or event. Navigation property.
 
    .PARAMETER IsFolder
        Property indicates, wether the object is a folder or not.
 
    .PARAMETER Permission
        The stated permission on the reference attachment.
 
    .PARAMETER PreviewUrl
        The url the preview the reference attachment.
 
    .PARAMETER ProviderType
        Specifies what type of reference is it.
 
    .PARAMETER SourceUrl
        The Url where the reference attachment points to.
 
    .PARAMETER ThumbnailUrl
        The Url of the thumbnail for the reference attachment.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
        (Just used for logging reasons)
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/resources/attachment?view=graph-rest-1.0
 
        https://docs.microsoft.com/en-us/graph/api/resources/fileattachment?view=graph-rest-1.0
        https://docs.microsoft.com/en-us/graph/api/resources/itemattachment?view=graph-rest-1.0
        https://docs.microsoft.com/en-us/graph/api/resources/referenceattachment?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> New-JsonAttachmentObject
 
        Creates a json attachment object for use in Microsoft Graph REST api
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low', DefaultParameterSetName = 'FileAttachment')]
    [OutputType([String])]
    param (
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $Name,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [int32]
        $Size,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [bool]
        $IsInline,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $LastModifiedDateTime,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $ContentType,

        [Parameter(ParameterSetName = 'FileAttachment')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $contentBytes,

        [Parameter(ParameterSetName = 'FileAttachment')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $contentLocation,

        [Parameter(ParameterSetName = 'ItemAttachment')]
        [psobject]
        $Item,

        [Parameter(ParameterSetName = 'ReferenceAttachment')]
        [String]
        $SourceUrl,

        [Parameter(ParameterSetName = 'ReferenceAttachment')]
        [String]
        $ProviderType,

        [Parameter(ParameterSetName = 'ReferenceAttachment')]
        [String]
        $ThumbnailUrl,

        [Parameter(ParameterSetName = 'ReferenceAttachment')]
        [String]
        $PreviewUrl,

        [Parameter(ParameterSetName = 'ReferenceAttachment')]
        [String]
        $Permission,

        [Parameter(ParameterSetName = 'ReferenceAttachment')]
        [bool]
        $IsFolder,

        [String]
        $FunctionName
    )
    begin {
    }

    process {
        Write-PSFMessage -Level Debug -Message "Create attachment JSON object" -Tag "ParameterSetHandling"

        #region variable definition
        $boundParameters = @()
        $bodyHash = [ordered]@{}
        $variableNames = @("Name", "Size", "IsInline", "LastModifiedDateTime", "ContentType")
        switch ($PSCmdlet.ParameterSetName) {
            'FileAttachment' { $variableNames = $variableNames + @("contentBytes", "contentLocation") }
            'ItemAttachment' { $variableNames = $variableNames + @("item") }
            'ReferenceAttachment' { $variableNames = $variableNames + @("SourceUrl", "ProviderType", "ThumbnailUrl", "PreviewUrl", "Permission", "IsFolder") }
        }
        #endregion variable definition

        #region Parsing string and boolean parameters to json data parts
        Write-PSFMessage -Level VeryVerbose -Message "Parsing parameters to json data parts ($([string]::Join(", ", $variableNames)))" -Tag "ParameterParsing" -FunctionName $FunctionName

        $bodyHash.Add("@odata.type", """#microsoft.graph.$($PSCmdlet.ParameterSetName)""")

        foreach ($variableName in $variableNames) {
            if (Test-PSFParameterBinding -ParameterName $variableName) {
                $boundParameters = $boundParameters + $variableName
                Write-PSFMessage -Level Debug -Message "Parsing parameter $($variableName)" -Tag "ParameterParsing"
                $bodyHash.Add($variableName, ((Get-Variable $variableName -Scope 0).Value | ConvertTo-Json))
            }
        }
        #endregion Parsing string and boolean parameters to json data parts

        # Put parameters (JSON Parts) into a valid JSON-object together and output the result
        $bodyJSON = Merge-HashToJson $bodyHash
        $bodyJSON
    }

    end {
    }
}

function New-MgaAttachmentObject {
    <#
    .SYNOPSIS
        Create new Attachment object
 
    .DESCRIPTION
        Create new Attachment object
        Helper function used for internal commands.
 
    .PARAMETER RestData
        The RestData object containing the data for the new message object.
 
    .PARAMETER ParentObject
        The ParentObject object where the attachment came from.
 
    .PARAMETER ApiVersion
        The version used for queries in Microsoft Graph connection
 
    .PARAMETER ResultSize
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER User
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Token
        The access token to use to connect.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> New-MgaAttachmentObject -RestData $output
 
        Create a MSGraph.Exchange.Attachment.* object from data in variable $output
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding()]
    param (
        $RestData,

        $ParentObject,

        $ApiVersion,

        [Int64]
        $ResultSize,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [String]
        $FunctionName
    )

    $outputHash = [ordered]@{
        Id                   = $RestData.Id
        Name                 = $RestData.Name
        AttachmentType       = [MSGraph.Exchange.Attachment.AttachmentTypes]$RestData.'@odata.type'.split(".")[($RestData.'@odata.type'.split(".").count - 1)]
        ContentType          = $RestData.ContentType
        IsInline             = $RestData.isInline
        LastModifiedDateTime = $RestData.LastModifiedDateTime
        Size                 = $RestData.Size
        User                 = $RestData.user
        ParentObject         = $ParentObject
        BaseObject           = $RestData
    }

    switch ($RestData.'@odata.type') {
        '#microsoft.graph.itemAttachment' {
            $invokeParam = @{
                "Field"        = "messages/$($ParentObject.Id)/attachments/$($RestData.id)/?`$expand=microsoft.graph.itemattachment/item"
                "Token"        = $Token
                "User"         = $User
                "ResultSize"   = $ResultSize
                "ApiVersion"   = $ApiVersion
                "FunctionName" = $FunctionName
            }
            $itemData = Invoke-MgaRestMethodGet @invokeParam

            $outputHash.BaseObject = $itemData
            $outputHash.Id = $itemData.id
            $outputHash.Add("Item", $itemData.Item)

            New-Object -TypeName MSGraph.Exchange.Attachment.ItemAttachment -Property $outputHash
        }

        '#microsoft.graph.referenceAttachment' {
            $outputHash.Add("SourceUrl", [uri]$RestData.SourceUrl)
            $outputHash.Add("ProviderType", [MSGraph.Exchange.Attachment.ReferenceAttachmentProvider]$RestData.ProviderType)
            $outputHash.Add("ThumbnailUrl", [uri]$RestData.ThumbnailUrl)
            $outputHash.Add("PreviewUrl", [uri]$RestData.PreviewUrl)
            $outputHash.Add("Permission", [MSGraph.Exchange.Attachment.referenceAttachmentPermission]$RestData.Permission)
            $outputHash.Add("IsFolder", [bool]::Parse($RestData.IsFolder))

            New-Object -TypeName MSGraph.Exchange.Attachment.ReferenceAttachment -Property $outputHash
        }

        '#microsoft.graph.fileAttachment' {
            $outputHash.Add("ContentId", $RestData.ContentId)
            $outputHash.Add("ContentLocation", $RestData.ContentLocation)
            $outputHash.Add("ContentBytes", [system.convert]::FromBase64String($RestData.contentBytes))

            New-Object -TypeName MSGraph.Exchange.Attachment.FileAttachment -Property $outputHash
        }

        Default {
            New-Object -TypeName MSGraph.Exchange.Attachment.Attachment -Property $outputHash
        }
    }

}

function New-JsonMailObject {
    <#
    .SYNOPSIS
        Creates a json message object for use in Microsoft Graph REST api
 
    .DESCRIPTION
        Creates a json message object for use in Microsoft Graph REST api
        Helper function used for internal commands.
 
    .PARAMETER Subject
        The subject of the new message.
 
    .PARAMETER Sender
        The account that is actually used to generate the message.
        (Updatable only when sending a message from a shared mailbox or sending a message as a delegate.
        In any case, the value must correspond to the actual mailbox used.)
 
    .PARAMETER From
        The mailbox owner and sender of the message.
        Must correspond to the actual mailbox used.
 
    .PARAMETER ToRecipients
        The To recipients for the message.
 
    .PARAMETER CCRecipients
        The Cc recipients for the message.
 
    .PARAMETER BCCRecipients
        The Bcc recipients for the message.
 
    .PARAMETER ReplyTo
        The email addresses to use when replying.
 
    .PARAMETER Body
        The body of the message.
 
    .PARAMETER Categories
        The categories associated with the message.
 
    .PARAMETER Importance
        The importance of the message.
        The possible values are: Low, Normal, High.
 
    .PARAMETER InferenceClassification
        The classification of the message for the user, based on inferred relevance or importance, or on an explicit override.
        The possible values are: focused or other.
 
    .PARAMETER InternetMessageId
        The message ID in the format specified by RFC2822.
 
    .PARAMETER IsDeliveryReceiptRequested
        Indicates whether a delivery receipt is requested for the message.
 
    .PARAMETER IsReadReceiptRequested
        Indicates whether a read receipt is requested for the message.
 
    .PARAMETER IsRead
        Indicates whether the message has been read.
 
    .PARAMETER Comment
        The comment in a body of a forwarded message.
        Only used when forwarding messages.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
        (Just used for logging reasons)
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/resources/message?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> New-JsonMailObject
 
        Creates a json message object for use in Microsoft Graph REST api
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low')]
    [OutputType([String])]
    param (
        [bool]
        $IsRead,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $Subject,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $Sender,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $From,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $ToRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $CCRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $BCCRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $ReplyTo,

        [String]
        $Body,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [String[]]
        $Categories,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateSet($null, "", "Low", "Normal", "High")]
        [String]
        $Importance,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [ValidateSet($null, "", "focused", "other")]
        [String]
        $InferenceClassification,

        [String]
        $InternetMessageId,

        [bool]
        $IsDeliveryReceiptRequested,

        [bool]
        $IsReadReceiptRequested,

        [String]
        $Comment,

        [String]
        $FunctionName
    )
    begin {
        #region variable definition
        $boundParameters = @()
        $mailAddressNames = @("sender", "from", "toRecipients", "ccRecipients", "bccRecipients", "replyTo")
        #endregion variable definition

        # parsing mailAddress parameter strings to mailaddress objects (if not empty)
        foreach ($Name in $mailAddressNames) {
            if (Test-PSFParameterBinding -ParameterName $name) {
                New-Variable -Name "$($name)Addresses" -Force -Scope 0
                if ((Get-Variable -Name $Name -Scope 0).Value) {
                    try {
                        $mailAddress = (Get-Variable -Name $Name -Scope 0).Value | ForEach-Object { [mailaddress]$_ } -ErrorAction Stop -ErrorVariable parseError
                        Set-Variable -Name "$($name)Addresses" -Value $mailAddress
                        Remove-Variable mailaddress -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false -ErrorAction Ignore
                    } catch {
                        Stop-PSFFunction -Message "Unable to parse $($name) to a mailaddress. String should be 'name@domain.topleveldomain' or 'displayname name@domain.topleveldomain'. Error: $($parseError[0].Exception.Message)" -Tag "ParameterParsing" -Category InvalidData -EnableException $true -Exception $parseError[0].Exception -FunctionName $FunctionName
                    }
                }
            }
        }

    }

    process {
        $bodyHash = @{}
        Write-PSFMessage -Level Debug -Message "Create message JSON object" -Tag "ParameterSetHandling"

        #region Parsing string and boolean parameters to json data parts
        $names = @("Comment", "IsRead", "Subject", "Categories", "Importance", "InferenceClassification", "InternetMessageId", "IsDeliveryReceiptRequested", "IsReadReceiptRequested")
        Write-PSFMessage -Level VeryVerbose -Message "Parsing string and boolean parameters to json data parts ($([string]::Join(", ", $names)))" -Tag "ParameterParsing"
        foreach ($name in $names) {
            if (Test-PSFParameterBinding -ParameterName $name) {
                $boundParameters = $boundParameters + $name
                Write-PSFMessage -Level Debug -Message "Parsing text parameter $($name)" -Tag "ParameterParsing"
                $bodyHash.Add($name, ((Get-Variable $name -Scope 0).Value | ConvertTo-Json))
            }
        }

        if ($Body) {
            $bodyHash.Add("Body", ([MSGraph.Exchange.Mail.MessageBody]$Body | ConvertTo-Json))
        }
        #endregion Parsing string and boolean parameters to json data parts

        #region Parsing mailaddress parameters to json data parts
        Write-PSFMessage -Level VeryVerbose -Message "Parsing mailaddress parameters to json data parts ($([string]::Join(", ", $mailAddressNames)))" -Tag "ParameterParsing"
        foreach ($name in $mailAddressNames) {
            if (Test-PSFParameterBinding -ParameterName $name) {
                $boundParameters = $boundParameters + $name
                Write-PSFMessage -Level Debug -Message "Parsing mailaddress parameter $($name)" -Tag "ParameterParsing"
                $addresses = (Get-Variable -Name "$($name)Addresses" -Scope 0).Value
                if ($addresses) {
                    # build valid mail address object, if address is specified
                    [array]$addresses = foreach ($item in $addresses) {
                        [PSCustomObject]@{
                            emailAddress = [PSCustomObject]@{
                                address = $item.Address
                                name    = $item.DisplayName
                            }
                        }
                    }
                } else {
                    # place an empty mail address object in, if no address is specified (this will clear the field in the message)
                    [array]$addresses = [PSCustomObject]@{
                        emailAddress = [PSCustomObject]@{
                            address = ""
                            name    = ""
                        }
                    }
                }

                if ($name -in @("toRecipients", "ccRecipients", "bccRecipients", "replyTo")) {
                    # these kind of objects need to be an JSON array
                    if ($addresses.Count -eq 1) {
                        # hardly format JSON object as an array, because ConvertTo-JSON will output a single object-json-string on an array with count 1 (PSVersion 5.1.17134.407 | PSVersion 6.1.1)
                        $bodyHash.Add($name, ("[" + ($addresses | ConvertTo-Json) + "]") )
                    } else {
                        $bodyHash.Add($name, ($addresses | ConvertTo-Json) )
                    }
                } else {
                    $bodyHash.Add($name, ($addresses | ConvertTo-Json) )
                }
            }
        }
        #endregion Parsing mailaddress parameters to json data parts

        # Put parameters (JSON Parts) into a valid JSON-object together and output the result
        $bodyJSON = Merge-HashToJson $bodyHash
        $bodyJSON
    }

    end {
    }
}

function New-MgaMailFolderObject {
    <#
    .SYNOPSIS
        Create new FolderObject
 
    .DESCRIPTION
        Create new FolderObject
        Helper function used for internal commands.
 
    .PARAMETER RestData
        The RestData object containing the data for the new message object.
 
    .PARAMETER Level
        The hierarchy level of the folder.
        1 means the folder is a root folder.
 
    .PARAMETER ParentFolder
        If known/ existing, the parent folder object of the folder object to create.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> New-MgaMailFolderObject -RestData $output -Level $Level -ParentFolder $ParentFolder -FunctionName $MyInvocation.MyCommand
 
        Create a MSGraph.Exchange.Mail.Folder object from data in variable $output
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [OutputType([MSGraph.Exchange.Mail.Folder])]
    [CmdletBinding()]
    param (
        $RestData,

        [MSGraph.Exchange.Mail.FolderParameter]
        $ParentFolder,

        [int]
        $Level,

        [String]
        $FunctionName
    )

    if ((-not $Level) -and $ParentFolder) {
        $Level = $ParentFolder.InputObject.HierarchyLevel + 1
    } elseif ((-not $Level) -and (-not $ParentFolder)) {
        $Level = 1
    }

    $hash = @{
        Id               = $RestData.Id
        DisplayName      = $RestData.DisplayName
        ParentFolderId   = $RestData.ParentFolderId
        ChildFolderCount = $RestData.ChildFolderCount
        UnreadItemCount  = $RestData.UnreadItemCount
        TotalItemCount   = $RestData.TotalItemCount
        User             = $RestData.User
        HierarchyLevel   = $Level
    }

    if ($ParentFolder) { $hash.Add("ParentFolder", $ParentFolder.InputObject) }

    $OutputObject = New-Object -TypeName MSGraph.Exchange.Mail.Folder -Property $hash

    $OutputObject
}

function New-MgaMailMessageObject {
    <#
    .SYNOPSIS
        Create new MessageObject
 
    .DESCRIPTION
        Create new MessageObject
        Helper function used for internal commands.
 
    .PARAMETER RestData
        The RestData object containing the data for the new message object.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> New-MgaMailMessageObject -RestData $output
 
        Create a MSGraph.Exchange.Mail.Message object from data in variable $output
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    [CmdletBinding()]
    param (
        $RestData,

        [String]
        $FunctionName
    )

    $hash = [ordered]@{
        BaseObject                 = $RestData
        Subject                    = $RestData.subject
        Body                       = $RestData.body
        BodyPreview                = $RestData.bodyPreview
        Categories                 = $RestData.categories
        ChangeKey                  = $RestData.changeKey
        ConversationId             = $RestData.conversationId
        CreatedDateTime            = [datetime]::Parse($RestData.createdDateTime)
        Flag                       = $RestData.flag.flagStatus
        HasAttachments             = $RestData.hasAttachments
        Id                         = $RestData.id
        Importance                 = $RestData.importance
        InferenceClassification    = $RestData.inferenceClassification
        InternetMessageId          = $RestData.internetMessageId
        IsDeliveryReceiptRequested = $RestData.isDeliveryReceiptRequested
        IsDraft                    = $RestData.isDraft
        IsRead                     = $RestData.isRead
        isReadReceiptRequested     = $RestData.isReadReceiptRequested
        lastModifiedDateTime       = [datetime]::Parse($RestData.lastModifiedDateTime)
        MeetingMessageType         = $RestData.meetingMessageType
        ParentFolderId             = $RestData.parentFolderId
        WebLink                    = $RestData.webLink
        User                       = $RestData.User
    }
    if ($RestData.receivedDateTime) { $hash.Add("ReceivedDateTime", [datetime]::Parse($RestData.receivedDateTime)) }
    if ($RestData.sentDateTime) { $hash.Add("SentDateTime", [datetime]::Parse($RestData.sentDateTime)) }
    if ($RestData.from.emailAddress) {
        if ($RestData.from.emailAddress.name -like $RestData.from.emailAddress.address) {
            # if emailaddress is same in address and in name field, only use address field
            $from = $RestData.from.emailAddress | ForEach-Object { [mailaddress]$_.address } -ErrorAction Continue
        } else {
            $from = $RestData.from.emailAddress | ForEach-Object { [mailaddress]"$($_.name) $($_.address)"} -ErrorAction Continue
        }
        $hash.Add("from", $from)
    }
    if ($RestData.Sender.emailAddress) {
        if ($RestData.Sender.emailAddress.name -like $RestData.Sender.emailAddress.address) {
            # if emailaddress is same in address and in name field, only use address field
            $senderaddress = $RestData.Sender.emailAddress | ForEach-Object { [mailaddress]$_.address } -ErrorAction Continue
        } else {
            $senderaddress = $RestData.Sender.emailAddress | ForEach-Object { [mailaddress]"$($_.name) $($_.address)"} -ErrorAction Continue
        }
        $hash.Add("Sender", $senderaddress)
    }
    if ($RestData.bccRecipients.emailAddress) {
        if ($RestData.bccRecipients.emailAddress.name -like $RestData.bccRecipients.emailAddress.address) {
            # if emailaddress is same in address and in name field, only use address field
            [array]$bccRecipients = $RestData.bccRecipients.emailAddress | ForEach-Object { [mailaddress]$_.address } -ErrorAction Continue
        } else {
            [array]$bccRecipients = $RestData.bccRecipients.emailAddress | ForEach-Object { [mailaddress]"$($_.name) $($_.address)"} -ErrorAction Continue
        }
        $hash.Add("bccRecipients", [array]$bccRecipients)
    }
    if ($RestData.ccRecipients.emailAddress) {
        if ($RestData.ccRecipients.emailAddress.name -like $RestData.ccRecipients.emailAddress.address) {
            # if emailaddress is same in address and in name field, only use address field
            [array]$ccRecipients = $RestData.ccRecipients.emailAddress | ForEach-Object { [mailaddress]$_.address } -ErrorAction Continue
        } else {
            [array]$ccRecipients = $RestData.ccRecipients.emailAddress | ForEach-Object { [mailaddress]"$($_.name) $($_.address)"} -ErrorAction Continue
        }
        $hash.Add("ccRecipients", [array]$ccRecipients)
    }
    if ($RestData.replyTo.emailAddress) {
        if ($RestData.replyTo.emailAddress.name -like $RestData.replyTo.emailAddress.address) {
            # if emailaddress is same in address and in name field, only use address field
            [array]$replyTo = $RestData.replyTo.emailAddress | ForEach-Object { [mailaddress]$_.address } -ErrorAction Continue
        } else {
            [array]$replyTo = $RestData.replyTo.emailAddress | ForEach-Object { [mailaddress]"$($_.name) $($_.address)"} -ErrorAction Continue
        }
        $hash.Add("replyTo", [array]$replyTo)
    }
    if ($RestData.toRecipients.emailAddress) {
        if ($RestData.toRecipients.emailAddress.name -like $RestData.toRecipients.emailAddress.address) {
            # if emailaddress is same in address and in name field, only use address field
            [array]$toRecipients = $RestData.toRecipients.emailAddress | ForEach-Object { [mailaddress]$_.address } -ErrorAction Continue
        } else {
            [array]$toRecipients = $RestData.toRecipients.emailAddress | ForEach-Object { [mailaddress]"$($_.name) $($_.address)"} -ErrorAction Continue
        }
        $hash.Add("toRecipients", [array]$toRecipients)
    }

    $messageOutputObject = New-Object -TypeName MSGraph.Exchange.Mail.Message -Property $hash
    $messageOutputObject
}

function New-JsonAutomaticRepliesSettingFraction {
    <#
    .SYNOPSIS
        Creates a json object from AutomaticRepliesSetting object
 
    .DESCRIPTION
        Creates a json object from AutomaticRepliesSetting object used for Microsoft Graph REST api
        Helper function used for internal commands.
 
    .PARAMETER AutomaticRepliesSetting
        The object to convert to json
 
    .EXAMPLE
        PS C:\> New-JsonAutomaticRepliesSettingFraction -AutomaticRepliesSetting $automaticRepliesSetting
 
        Creates a json object from AutomaticRepliesSetting object used for Microsoft Graph REST api
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low')]
    [OutputType([String])]
    param (
        [MSGraph.Exchange.MailboxSetting.AutomaticRepliesSetting]
        $AutomaticRepliesSetting
    )

    $automaticRepliesSettingHash = [ordered]@{
        "status"                 = $AutomaticRepliesSetting.Status.ToString()
        "externalAudience"       = $AutomaticRepliesSetting.ExternalAudience.ToString()
        "internalReplyMessage"   = $AutomaticRepliesSetting.InternalReplyMessage
        "externalReplyMessage"   = $AutomaticRepliesSetting.ExternalReplyMessage
        "scheduledStartDateTime" = [ordered]@{
            #"dateTime" = ($AutomaticRepliesSetting.ScheduledStartDateTimeUTC.DateTime | Get-Date -Format s)
            "dateTime" = $AutomaticRepliesSetting.ScheduledStartDateTimeUTC.DateTime.ToString("s") # "s" means sortable date: 2000-01-01T01:01:01(.010001)
            "timeZone" = $AutomaticRepliesSetting.ScheduledStartDateTimeUTC.TimeZone
        }
        "scheduledEndDateTime"   = [ordered]@{
            #"dateTime" = ($AutomaticRepliesSetting.ScheduledEndDateTimeUTC.DateTime | Get-Date -Format s)
            "dateTime" = $AutomaticRepliesSetting.ScheduledEndDateTimeUTC.DateTime.ToString("s") # "s" means sortable date: 2000-01-01T01:01:01(.010001)
            "timeZone" = $AutomaticRepliesSetting.ScheduledEndDateTimeUTC.TimeZone
        }
    }
    $automaticRepliesSettingObject = New-Object psobject -Property $automaticRepliesSettingHash
    $automaticRepliesSettingJSON = ConvertTo-Json -InputObject $automaticRepliesSettingObject
    $automaticRepliesSettingJSON
}


function New-JsonLanguageSettingFraction {
    <#
    .SYNOPSIS
        Creates a json object from LocaleInfoSetting (LanguageSetting) object
 
    .DESCRIPTION
        Creates a json object from LocaleInfoSetting (LanguageSetting) object used for Microsoft Graph REST api
        Helper function used for internal commands.
 
    .PARAMETER LanguageSetting
        The object to convert to json
 
    .EXAMPLE
        PS C:\> New-JsonLanguageSettingFraction -LanguageSetting $languageSetting
 
        Creates a json object from LanguageSetting object used for Microsoft Graph REST api
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low')]
    [OutputType([String])]
    param (
        [MSGraph.Exchange.MailboxSetting.LocaleInfoSetting]
        $LanguageSetting
    )

    $languageSettingHash = [ordered]@{
        "locale"      = $LanguageSetting.Locale.ToString()
        #"displayName" = $LanguageSetting.DisplayName # causes errors on rest patch call
    }
    $languageSettingObject = New-Object psobject -Property $languageSettingHash
    $languageSettingJSON = ConvertTo-Json -InputObject $languageSettingObject
    $languageSettingJSON
}


function New-JsonMailboxSettingObject {
    <#
    .SYNOPSIS
        Creates a json mailsettings object for use in Microsoft Graph REST api
 
    .DESCRIPTION
        Creates a json mailsettings object for use in Microsoft Graph REST api
        Helper function used for internal commands.
 
    .PARAMETER SettingObject
        The object to be converted into JSON format containing the data for the new message object.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
        (Just used for logging reasons)
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/user-update-mailboxsettings?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> New-JsonMailboxSettingObject -SettingObject $settingObject -User $user -FunctionName $MyInvocation.MyCommand
 
        Creates a json MailboxSetting object for use in Microsoft Graph REST api
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low')]
    [OutputType([String])]
    param (
        [MSGraph.Exchange.MailboxSetting.MailboxSettingParameter]
        $SettingObject,

        [string]
        $User,

        [String]
        $FunctionName
    )
    begin {
    }

    process {
        Write-PSFMessage -Level Debug -Message "Working on '$($SettingObject)' to create mailboxSetting JSON object" -Tag "ParameterSetHandling"
        #region variable definition
        $bodyHash = [ordered]@{}

        #endregion variable definition

        #region Parsing input to json data parts
        # set field @odata.context - required
        if ($SettingObject.InputObject.BaseObject.'@odata.context') {
            $context = $SettingObject.InputObject.BaseObject.'@odata.context'
            if ($context -match '\/mailboxSettings\/\w*$') { $context = $context.Replace($Matches.Values, "/mailboxsettings") }
            Remove-Variable -Name Matches -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false -WarningAction Ignore -ErrorAction Ignore
        } else {
            $apiConnection = Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiConnection' -Fallback 'https://graph.microsoft.com'
            $apiVersion = Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiVersion' -Fallback 'v1.0'
            $resolvedUser = Resolve-UserString -User $User -ContextData
            $context = "$($apiConnection)/$($apiVersion)/`$metadata#$($resolvedUser)/mailboxsettings"
            Remove-Variable -Name apiConnection, apiVersion -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false -WarningAction Ignore -ErrorAction Ignore
        }
        $bodyHash.Add('@odata.context', """$context""")

        # depending on type of object
        switch ($SettingObject.TypeName) {
            'MSGraph.Exchange.MailboxSetting.MailboxSettings' {
                # set archive folder
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting archive folder to '$($SettingObject.InputObject.ArchiveFolder)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $bodyHash.Add('archiveFolder', ($SettingObject.InputObject.ArchiveFolder.Id | ConvertTo-Json))

                # set time zone
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting timezone to '$($SettingObject.InputObject.TimeZone.Id)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $bodyHash.Add('timeZone', ($SettingObject.InputObject.TimeZone.Id | ConvertTo-Json))
                #$bodyHash.Add('timeZone', ('"' + "W. Europe Standard Time" + '"'))

                # set auto reply
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting autoreply to '$($SettingObject.InputObject.automaticRepliesSetting.Status)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $automaticRepliesSettingJSON = New-JsonAutomaticRepliesSettingFraction -AutomaticRepliesSetting $SettingObject.InputObject.automaticRepliesSetting
                $bodyHash.Add('automaticRepliesSetting', $automaticRepliesSettingJSON)

                # set language
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting language to '$($SettingObject.InputObject.Language)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $languageSettingJSON = New-JsonLanguageSettingFraction -LanguageSetting $SettingObject.InputObject.Language
                $bodyHash.Add('language', $languageSettingJSON)

                # set working hours
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting workingHours to '$($SettingObject.InputObject.WorkingHours)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $workingHoursSettingJSON = New-JsonWorkingHoursSettingFraction -WorkingHoursSetting $SettingObject.InputObject.WorkingHours
                $bodyHash.Add('workingHours', $workingHoursSettingJSON)
            }

            'MSGraph.Exchange.Mail.Folder' {
                # set archive folder
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting archive folder to '$($SettingObject.InputObject)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $bodyHash.Add('archiveFolder', ($SettingObject.InputObject.Id | ConvertTo-Json))
            }

            'System.TimeZoneInfo' {
                # set time zone
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting timezone to '$($SettingObject.InputObject.Id)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $bodyHash.Add('timeZone', ($SettingObject.InputObject.Id | ConvertTo-Json))
            }

            'MSGraph.Exchange.MailboxSetting.AutomaticRepliesSetting' {
                # set auto reply
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting autoreply to '$($SettingObject.InputObject.Status)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $automaticRepliesSettingJSON = New-JsonAutomaticRepliesSettingFraction -AutomaticRepliesSetting $SettingObject.InputObject
                $bodyHash.Add('automaticRepliesSetting', $automaticRepliesSettingJSON)
            }

            'MSGraph.Exchange.MailboxSetting.LocaleInfoSetting' {
                # set language
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting language to '$($SettingObject.InputObject)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $languageSettingJSON = New-JsonLanguageSettingFraction -LanguageSetting $SettingObject.InputObject
                $bodyHash.Add('language', $languageSettingJSON)
            }

            'MSGraph.Exchange.MailboxSetting.WorkingHoursSetting' {
                # set working hours
                Write-PSFMessage -Level VeryVerbose -Message "Prepare setting workingHours to '$($SettingObject.InputObject)'" -Tag "CreateJSON" -FunctionName $FunctionName
                $workingHoursSettingJSON = New-JsonWorkingHoursSettingFraction -WorkingHoursSetting $SettingObject.InputObject
                $bodyHash.Add('workingHours', $workingHoursSettingJSON)
            }

            Default { Stop-PSFFunction -Message "Unhandled type ($($SettingObject.TypeName)) of SettingObject. Developer mistake!" -EnableException $true -Category InvalidType -FunctionName $MyInvocation.MyCommand }
        }
        #endregion Parsing input to json data parts

        # Put parameters (JSON Parts) into a valid JSON-object and output the result
        $bodyJSON = Merge-HashToJSON $bodyHash
        $bodyJSON
    }

    end {
    }
}

function New-JsonWorkingHoursSettingFraction {
    <#
    .SYNOPSIS
        Creates a json object from WorkingHoursSetting object
 
    .DESCRIPTION
        Creates a json object from WorkingHoursSetting object used for Microsoft Graph REST api
        Helper function used for internal commands.
 
    .PARAMETER WorkingHoursSetting
        The object to convert to json
 
    .EXAMPLE
        PS C:\> New-JsonWorkingHoursSettingFraction -WorkingHoursSetting $workingHoursSetting
 
        Creates a json object from WorkingHoursSetting object used for Microsoft Graph REST api
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(SupportsShouldProcess = $false, ConfirmImpact = 'Low')]
    [OutputType([String])]
    param (
        [MSGraph.Exchange.MailboxSetting.WorkingHoursSetting]
        $WorkingHoursSetting
    )

    $workingHoursSettingHash = [ordered]@{
        "daysOfWeek" = [array]$WorkingHoursSetting.DaysOfWeek.ForEach( {$_.ToString()} )
        "startTime"  = $WorkingHoursSetting.StartTime.ToString("HH:mm:ss.fffffff")
        "endTime"    = $WorkingHoursSetting.EndTime.ToString("HH:mm:ss.fffffff")
        "timeZone"   = @{
            "name" = $WorkingHoursSetting.TimeZone.ToString()
        }
    }
    $workingHoursSettingObject = New-Object psobject -Property $workingHoursSettingHash
    $workingHoursSettingJSON = ConvertTo-Json -InputObject $workingHoursSettingObject
    $workingHoursSettingJSON
}


function New-MgaMailboxSettingObject {
    <#
    .SYNOPSIS
        Create new mailboxSettings object
 
    .DESCRIPTION
        Create new mailboxSettings object
        Helper function used for internal commands.
 
    .PARAMETER RestData
        The RestData object containing the data for the new message object.
 
    .PARAMETER Type
        The type of the settings object to be created.
 
    .PARAMETER User
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Token
        The access token to use to connect.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> New-MgaMailboxSettingObject -RestData $output -Type MailboxSettings
 
        Create a MSGraph.Exchange.MailboxSetting.MailboxSettings object from data in variable $output
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseOutputTypeCorrectly", "")]
    [CmdletBinding()]
    param (
        $RestData,

        [String]
        $Type,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [String]
        $FunctionName
    )
    Write-PSFMessage -Level Debug -Message "Create $($Type) mailbox Setting object" -Tag "CreateObject"

    if ($Type -notlike "TimeZoneSetting" -and $Type -notlike "ArchiveFolderSetting") {
        $name = [System.Web.HttpUtility]::UrlDecode(([uri]$RestData.'@odata.context').Fragment).TrimStart("#")
        $outputHash = [ordered]@{
            Name       = $name
            User       = $RestData.user
            BaseObject = $RestData
        }
    }

    switch ($Type) {
        {$_ -like 'AllSettings' -or $_ -like 'ArchiveFolderSetting'} {
            # create the full set of mailbox settings
            if ($RestData.archiveFolder) {
                try {
                    $archivFolder = Get-MgaMailFolder -Name $RestData.archiveFolder -User $User -Token $Token -ErrorAction Stop
                } catch {
                    Stop-PSFFunction -Message "Failed to get information about archiv folder on $($outputHash.Name)" -EnableException $true -Exception $_.Exception -Category ReadError -ErrorRecord $_ -Tag "QueryData" -FunctionName $FunctionName
                }

                if ($Type -like 'ArchiveFolderSetting') {
                    return $archivFolder
                } else {
                    $outputHash.Add("ArchiveFolder", $archivFolder)
                }
            } else {
                $archivFolder = ""
            }

            $timeZone = [System.TimeZoneInfo]::FindSystemTimeZoneById($RestData.timeZone)
            $outputHash.Add("TimeZone", $timeZone)

            $autoReplySetting = [MSGraph.Exchange.MailboxSetting.AutomaticRepliesSetting]::new(
                [MSGraph.Exchange.MailboxSetting.AutomaticRepliesStatus]$RestData.automaticRepliesSetting.Status,
                [MSGraph.Exchange.MailboxSetting.ExternalAudienceScope]$RestData.automaticRepliesSetting.ExternalAudience,
                $RestData.automaticRepliesSetting.ExternalReplyMessage.Trim([char]65279),
                $RestData.automaticRepliesSetting.internalReplyMessage.Trim([char]65279),
                [MSGraph.Exchange.DateTimeTimeZone]$RestData.automaticRepliesSetting.ScheduledStartDateTime,
                [MSGraph.Exchange.DateTimeTimeZone]$RestData.automaticRepliesSetting.ScheduledEndDateTime,
                "$($name)/automaticRepliesSetting"
            )
            $outputHash.Add("AutomaticRepliesSetting", $autoReplySetting)

            $language = [MSGraph.Exchange.MailboxSetting.LocaleInfoSetting]::new(
                [cultureinfo]$RestData.language.locale,
                $RestData.language.displayName,
                "$($name)/language"
            )
            $outputHash.Add("Language", $language)

            $workingHours = [MSGraph.Exchange.MailboxSetting.WorkingHoursSetting]::new(
                $RestData.WorkingHours.daysOfWeek.ForEach( {[dayOfWeek]$_}),
                [datetime]$RestData.WorkingHours.startTime,
                [datetime]$RestData.WorkingHours.endTime,
                [MSGraph.Exchange.TimeZoneBase]::new($RestData.WorkingHours.timeZone.name),
                "$($name)/workingHours"
            )
            $outputHash.Add("WorkingHours", $workingHours)

            New-Object -TypeName MSGraph.Exchange.MailboxSetting.MailboxSettings -Property $outputHash
        }

        'AutomaticReplySetting' {
            # create auto reply settings object
            if ($RestData.automaticRepliesSetting) { $autoReplySetting = $RestData.automaticRepliesSetting } else { $autoReplySetting = $RestData }
            $outputHash.Add("Status", [MSGraph.Exchange.MailboxSetting.AutomaticRepliesStatus]$autoReplySetting.Status)
            $outputHash.Add("ExternalAudience", [MSGraph.Exchange.MailboxSetting.ExternalAudienceScope]$autoReplySetting.ExternalAudience)
            $outputHash.Add("ExternalReplyMessage", $autoReplySetting.ExternalReplyMessage.Trim([char]65279))
            $outputHash.Add("InternalReplyMessage", $autoReplySetting.internalReplyMessage.Trim([char]65279))
            $outputHash.Add("ScheduledStartDateTimeUTC", [MSGraph.Exchange.DateTimeTimeZone]$autoReplySetting.ScheduledStartDateTime)
            $outputHash.Add("ScheduledEndDateTimeUTC", [MSGraph.Exchange.DateTimeTimeZone]$autoReplySetting.ScheduledEndDateTime)

            $output = New-Object -TypeName MSGraph.Exchange.MailboxSetting.AutomaticRepliesSetting -Property $outputHash
            $output
            Remove-Variable -Name autoReplySetting -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false -WarningAction Ignore -ErrorAction Ignore
        }

        'LanguageSetting' {
            # create language setting object
            if($RestData.language) { $languageSetting = $RestData.language } else { $languageSetting = $RestData }
            $outputHash.Add("Locale", [cultureinfo]$languageSetting.locale)
            $outputHash.Add("DisplayName", $languageSetting.displayName)

            $output = New-Object -TypeName MSGraph.Exchange.MailboxSetting.LocaleInfoSetting -Property $outputHash
            $output
            Remove-Variable -Name languageSetting -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false -WarningAction Ignore -ErrorAction Ignore
        }

        'TimeZoneSetting' {
            # create timeZone object
            if($RestData.timeZone) { $timeZoneSetting = $RestData.timeZone } else { $timeZoneSetting = $RestData }
            $output = [System.TimeZoneInfo]::FindSystemTimeZoneById($timeZoneSetting)
            $output
            Remove-Variable -Name timeZoneSetting -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false -WarningAction Ignore -ErrorAction Ignore
        }

        'WorkingHoursSetting' {
            # create workingHours object
            if($RestData.workingHours) { $workingHourSetting = $RestData.workingHours } else { $workingHourSetting = $RestData }
            $outputHash.Add("DaysOfWeek", $workingHourSetting.daysOfWeek.ForEach( {[dayOfWeek]$_}))
            $outputHash.Add("StartTime", [datetime]$workingHourSetting.startTime)
            $outputHash.Add("EndTime", [datetime]$workingHourSetting.endTime)
            $outputHash.Add("TimeZone", [MSGraph.Exchange.TimeZoneBase]::new($workingHourSetting.timeZone.name))

            $output = New-Object -TypeName MSGraph.Exchange.MailboxSetting.WorkingHoursSetting -Property $outputHash
            $output
            Remove-Variable -Name workingHourSetting -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false -WarningAction Ignore -ErrorAction Ignore
        }

        Default {
            Stop-PSFFunction -Message "Unable to output a valid MailboxSetting object, because of unhandled type '$($Type)'. Developer mistake." -EnableException $true -Category InvalidData -FunctionName $MyInvocation.MyCommand
        }
    }
}

function Get-MgaAccessTokenRegistered {
    <#
    .SYNOPSIS
        Output the registered access token
 
    .DESCRIPTION
        Output the registered access token
 
    .EXAMPLE
        PS C:\> Get-MgaRegisteredAccessToken
 
        Output the registered access token
    #>
    [CmdletBinding()]
    [Alias('Get-MgaRegisteredAccessToken')]
    param ()

    if ($script:msgraph_Token) {
        $script:msgraph_Token
    } else {
        Write-PSFMessage -Level Host -Message "No access token registered."
    }
}

function Invoke-MgaRestMethodDelete {
    <#
    .SYNOPSIS
        Performs a REST DELETE against the graph API
 
    .DESCRIPTION
        Performs a REST DELETE against the graph API.
        Primarily used for internal commands.
 
    .PARAMETER Field
        The api child item under the username in the url of the api call.
        If this didn't make sense to you, you probably shouldn't be using this command ;)
 
    .PARAMETER User
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Body
        JSON date as string to send as body on the REST call
 
    .PARAMETER ContentType
        Nature of the data in the body of an entity. Required.
 
    .PARAMETER ApiConnection
        The URI for the Microsoft Graph connection
 
    .PARAMETER ApiVersion
        The version used for queries in Microsoft Graph connection
 
    .PARAMETER Token
        The access token to use to connect.
 
    .PARAMETER Force
        If specified the user will not prompted on confirmation.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
 
    .EXAMPLE
        PS C:\> Invoke-MgaRestMethodDelete -Field "mailFolders/$($id)"
 
        Delete a mailfolder with the id stored in variable $id.
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    [Alias('Invoke-MgaDeleteMethod')]
    param (
        [Parameter(Mandatory = $true)]
        [string]
        $Field,

        [string]
        $User,

        [String]
        $Body,

        [ValidateSet("application/json")]
        [String]
        $ContentType = "application/json",

        [String]
        $ApiConnection = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiConnection' -Fallback 'https://graph.microsoft.com'),

        [string]
        $ApiVersion = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiVersion' -Fallback 'v1.0'),

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $Force,

        [string]
        $FunctionName = $MyInvocation.MyCommand
    )

    # tokek check
    $Token = Invoke-TokenLifetimeValidation -Token $Token -FunctionName $FunctionName

    if (-not $User) { $User = $Token.UserprincipalName }
    $restUri = "$($ApiConnection)/$($ApiVersion)/$(Resolve-UserString -User $User)/$($Field)"

    Write-PSFMessage -Tag "RestData" -Level VeryVerbose -Message "Invoking REST DELETE to uri: $($restUri)"
    Write-PSFMessage -Tag "RestData" -Level Debug -Message "REST body data: $($Body)"

    Clear-Variable -Name data -Force -WhatIf:$false -Confirm:$false -Verbose:$false -ErrorAction Ignore
    $invokeParam = @{
        Method  = "DELETE"
        Uri     = $restUri
        Body    = $Body
        Headers = @{
            "Authorization" = "Bearer $( [System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($token.AccessToken)) )"
            "Content-Type"  = "application/json"
        }
    }

    if ($Force) { $doAction = $true } else { $doAction = $pscmdlet.ShouldProcess($restUri, "Invoke DELETE") }
    if ($doAction) {
        try {
            $data = Invoke-RestMethod @invokeParam -ErrorVariable "restError" -ErrorAction Stop -Verbose:$false -UseBasicParsing
        } catch {
            Stop-PSFFunction -Tag "RestDataError" -Message $_.Exception.Message -Exception $_.Exception -ErrorRecord $_ -EnableException $true -Category ConnectionError -FunctionName $FunctionName
        }
    }

    if ($data) {
        $data | Add-Member -MemberType NoteProperty -Name 'User' -Value $User -Force
        $data
    }
}

function Invoke-MgaRestMethodGet {
    <#
    .SYNOPSIS
        Performs a rest GET against the graph API
 
    .DESCRIPTION
        Performs a rest GET against the graph API.
        Primarily used for internal commands.
 
    .PARAMETER Field
        The api child item under the username in the url of the api call.
        If this didn't make sense to you, you probably shouldn't be using this command ;)
 
    .PARAMETER User
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Delta
        Indicates that the query is intend to be a delta query, so a delta-link property is added to the output-object ('@odata.deltaLink').
 
    .PARAMETER DeltaLink
        Specifies the uri to query for delta objects on a query.
 
    .PARAMETER ResultSize
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER ApiConnection
        The URI for the Microsoft Graph connection
 
    .PARAMETER ApiVersion
        The version used for queries in Microsoft Graph connection
 
    .PARAMETER Token
        The access token to use to connect.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> Invoke-MgaRestMethodGet -Field 'mailFolders' -Token $Token -User $User
 
        Retrieves a list of email folders for the user $User, using the token stored in $Token
    #>
    [CmdletBinding(DefaultParameterSetName = 'Default')]
    [Alias('Invoke-MgaGetMethod')]
    param (
        [ValidateNotNullOrEmpty()]
        [string]
        $Field,

        [string]
        $User,

        [Parameter(ParameterSetName = 'Default')]
        [switch]
        $Delta,

        [Parameter(ParameterSetName = 'DeltaLink')]
        [string]
        $DeltaLink,

        [Int64]
        $ResultSize = (Get-PSFConfigValue -FullName 'MSGraph.Query.ResultSize' -Fallback 100),

        [String]
        $ApiConnection = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiConnection' -Fallback 'https://graph.microsoft.com'),

        [string]
        $ApiVersion = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiVersion' -Fallback 'v1.0'),

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [string]
        $FunctionName = $MyInvocation.MyCommand
    )

    # tokek check
    $Token = Invoke-TokenLifetimeValidation -Token $Token -FunctionName $FunctionName

    #region variable definition
    if ($PSCmdlet.ParameterSetName -like "DeltaLink") {
        Write-PSFMessage -Level VeryVerbose -Message "ParameterSet $($PSCmdlet.ParameterSetName) - constructing delta query" -Tag "ParameterSetHandling"
        $restUri = $DeltaLink
        $Delta = $true
        $User = ([uri]$restUri).AbsolutePath.split('/')[2]
    } else {
        if (-not $User) { $User = $Token.UserprincipalName }
        $restUri = "$($ApiConnection)/$($ApiVersion)/$(Resolve-UserString -User $User)/$($Field)"
        if ($Delta) { $restUri = $restUri + "/delta" }
    }
    if ($ResultSize -eq 0) { $ResultSize = [Int64]::MaxValue }
    #if ($ResultSize -le 10 -and $restUri -notmatch '\$top=') { $restUri = $restUri + "?`$top=$($ResultSize)" }
    [Int64]$i = 0
    [Int64]$overResult = 0
    $tooManyItems = $false
    $output = @()
    #endregion variable definition

    #region query data
    do {
        Write-PSFMessage -Tag "RestData" -Level VeryVerbose -Message "Get REST data: $($restUri)"

        Clear-Variable -Name data -Force -WhatIf:$false -Confirm:$false -Verbose:$false -ErrorAction Ignore
        $invokeParam = @{
            Method  = "Get"
            Uri     = $restUri
            Headers = @{
                "Authorization" = "Bearer $( [System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($token.AccessToken)) )"
                "Content-Type"  = "application/json"
            }
        }

        try {
            $data = Invoke-RestMethod @invokeParam -ErrorVariable "restError" -ErrorAction Stop -Verbose:$false -UseBasicParsing
        } catch {
            Stop-PSFFunction -Tag "RestDataError" -Message $_.Exception.Message -Exception $_.Exception -ErrorRecord $_ -EnableException $true -Category ConnectionError -FunctionName $FunctionName
        }

        if ("Value" -in $data.psobject.Properties.Name) {
            # Multi object with value property returned by api call
            [array]$value = $data.Value
            Write-PSFMessage -Tag "RestData" -Level VeryVerbose -Message "Retrieving $($value.Count) records from query"
            $i = $i + $value.Count
            if ($i -lt $ResultSize) {
                $restUri = $data.'@odata.nextLink'
            } else {
                $restUri = ""
                $tooManyItems = $true
                $overResult = $ResultSize - ($i - $value.Count)
                Write-PSFMessage -Tag "ResultSize" -Level Verbose -Message "Resultsize ($ResultSize) exeeded. Output $($overResult) object(s) in record set."
            }
        } else {
            # Multi object with value property returned by api call
            Write-PSFMessage -Tag "RestData" -Level VeryVerbose -Message "Single item retrived. Outputting data."
            [array]$value = $data
            $restUri = ""
        }

        if ((-not $tooManyItems) -or ($overResult -gt 0)) {
            # check if resultsize is reached
            if ($overResult -gt 0) {
                $output = $output + $Value[0..($overResult - 1)]
            } else {
                $output = $output + $Value
            }
        }
    }
    while ($restUri)
    #endregion query data

    #region output data
    $output | Add-Member -MemberType NoteProperty -Name 'User' -Value $User -Force
    if ($Delta) {
        if ('@odata.deltaLink' -in $data.psobject.Properties.Name) {
            $output | Add-Member -MemberType NoteProperty -Name '@odata.deltaLink' -Value $data.'@odata.deltaLink' -PassThru
        } else {
            $output | Add-Member -MemberType NoteProperty -Name '@odata.deltaLink' -Value $data.'@odata.nextLink' -PassThru
        }
    } else {
        $output
    }

    if ($tooManyItems) {
        # write information to console if resultsize exceeds
        if ($Delta) {
            Write-PSFMessage -Tag "GetData" -Level Host -Message "Reaching maximum ResultSize before finishing delta query. Next delta query will continue on pending objects. Current ResultSize: $($ResultSize)" -FunctionName $FunctionName
        } else {
            Write-PSFMessage -Tag "GetData" -Level Warning -Message "Too many items. Reaching maximum ResultSize before finishing query. You may want to increase the ResultSize. Current ResultSize: $($ResultSize)" -FunctionName $FunctionName
        }
    }
    #endregion output data
}

function Invoke-MgaRestMethodPatch {
    <#
    .SYNOPSIS
        Performs a REST PATCH against the graph API
 
    .DESCRIPTION
        Performs a REST PATCH against the graph API.
        Primarily used for internal commands.
 
    .PARAMETER Field
        The api child item under the username in the url of the api call.
        If this didn't make sense to you, you probably shouldn't be using this command ;)
 
    .PARAMETER User
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Body
        JSON date as string to send as body on the REST call
 
    .PARAMETER ContentType
        Nature of the data in the body of an entity. Required.
 
    .PARAMETER ApiConnection
        The URI for the Microsoft Graph connection
 
    .PARAMETER ApiVersion
        The version used for queries in Microsoft Graph connection
 
    .PARAMETER Token
        The access token to use to connect.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> Invoke-MgaRestMethodPatch -Field "messages/$($id)" -Body '{ "isRead": true }' -Token $Token
 
        Set a message as readed.
        The token stored in $Token is used for the api call.
    #>
    [CmdletBinding(DefaultParameterSetName = 'Default')]
    [Alias('Invoke-MgaPatchMethod')]
    param (
        [Parameter(Mandatory = $true)]
        [string]
        $Field,

        [string]
        $User,

        [String]
        $Body,

        [ValidateSet("application/json")]
        [String]
        $ContentType = "application/json",

        [String]
        $ApiConnection = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiConnection' -Fallback 'https://graph.microsoft.com'),

        [string]
        $ApiVersion = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiVersion' -Fallback 'v1.0'),

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [string]
        $FunctionName = $MyInvocation.MyCommand
    )

    # tokek check
    $Token = Invoke-TokenLifetimeValidation -Token $Token -FunctionName $FunctionName

    if (-not $User) { $User = $Token.UserprincipalName }
    $restUri = "$($ApiConnection)/$($ApiVersion)/$(Resolve-UserString -User $User)/$($Field)"

    Write-PSFMessage -Tag "RestData" -Level VeryVerbose -Message "Invoking REST PATCH to uri: $($restUri)"
    Write-PSFMessage -Tag "RestData" -Level Debug -Message "REST body data: $($Body)"

    Clear-Variable -Name data -Force -WhatIf:$false -Confirm:$false -Verbose:$false -ErrorAction Ignore
    $invokeParam = @{
        Method  = "Patch"
        Uri     = $restUri
        Body    = $Body
        Headers = @{
            "Authorization" = "Bearer $( [System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($token.AccessToken)) )"
            "Content-Type"  = "application/json"
        }
    }
    try {
        $data = Invoke-RestMethod @invokeParam -ErrorVariable "restError" -ErrorAction Stop -Verbose:$false -UseBasicParsing
    } catch {
        Stop-PSFFunction -Tag "RestDataError" -Message $_.Exception.Message -Exception $_.Exception -ErrorRecord $_ -EnableException $true -Category ConnectionError -FunctionName $FunctionName
    }

    if ($data) {
        $data | Add-Member -MemberType NoteProperty -Name 'User' -Value $User -Force
        $data
    }
}

function Invoke-MgaRestMethodPost {
    <#
    .SYNOPSIS
        Performs a REST POST against the graph API
 
    .DESCRIPTION
        Performs a REST POST against the graph API.
        Primarily used for internal commands.
 
    .PARAMETER Field
        The api child item under the username in the url of the api call.
        If this didn't make sense to you, you probably shouldn't be using this command ;)
 
    .PARAMETER User
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Body
        JSON date as string to send as body on the REST call
 
    .PARAMETER ContentType
        Nature of the data in the body of an entity. Required.
 
    .PARAMETER ApiConnection
        The URI for the Microsoft Graph connection
 
    .PARAMETER ApiVersion
        The version used for queries in Microsoft Graph connection
 
    .PARAMETER Token
        The access token to use to connect.
 
    .PARAMETER FunctionName
        Name of the higher function which is calling this function.
 
    .EXAMPLE
        PS C:\> Invoke-MgaRestMethodPost -Field "messages/$($id)/reply" -Body '{"comment": "comment-value"}' -Token $Token
 
        Reply to the sender of a message with the id, stored in variable $id. The message is then saved in the Sent Items folder.
        The token stored in $Token is used for the api call.
    #>
    [CmdletBinding(DefaultParameterSetName = 'Default')]
    [Alias('Invoke-MgaPostMethod')]
    param (
        [Parameter(Mandatory = $true)]
        [string]
        $Field,

        [string]
        $User,

        [String]
        $Body,

        [ValidateSet("application/json")]
        [String]
        $ContentType = "application/json",

        [String]
        $ApiConnection = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiConnection' -Fallback 'https://graph.microsoft.com'),

        [string]
        $ApiVersion = (Get-PSFConfigValue -FullName 'MSGraph.Tenant.ApiVersion' -Fallback 'v1.0'),

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [string]
        $FunctionName = $MyInvocation.MyCommand
    )

    # tokek check
    $Token = Invoke-TokenLifetimeValidation -Token $Token -FunctionName $FunctionName

    if (-not $User) { $User = $Token.UserprincipalName }
    $restUri = "$($ApiConnection)/$($ApiVersion)/$(Resolve-UserString -User $User)/$($Field)"

    Write-PSFMessage -Tag "RestData" -Level VeryVerbose -Message "Invoking REST POST to uri: $($restUri)"
    Write-PSFMessage -Tag "RestData" -Level Debug -Message "REST body data: $($Body)"

    Clear-Variable -Name data -Force -WhatIf:$false -Confirm:$false -Verbose:$false -ErrorAction Ignore
    $invokeParam = @{
        Method  = "Post"
        Uri     = $restUri
        Body    = $Body
        Headers = @{
            "Authorization" = "Bearer $( [System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($token.AccessToken)) )"
            "Content-Type"  = "application/json"
        }
    }

    try {
        $data = Invoke-RestMethod @invokeParam -ErrorVariable "restError" -ErrorAction Stop -Verbose:$false -UseBasicParsing
    } catch {
        Stop-PSFFunction -Tag "RestDataError" -Message $_.Exception.Message -Exception $_.Exception -ErrorRecord $_ -EnableException $true -Category ConnectionError -FunctionName $FunctionName
    }

    if ($restError) {
        Stop-PSFFunction -Tag "RestData" -Message $parseError[0].Exception -Exception $parseError[0].Exception -EnableException $false -Category ConnectionError -FunctionName $FunctionName
        return
    }

    if ($data) {
        $data | Add-Member -MemberType NoteProperty -Name 'User' -Value $User -Force
        $data
    }
}

function New-MgaAccessToken {
    <#
    .SYNOPSIS
        Creates an access token for contacting the specified application endpoint
 
    .DESCRIPTION
        Creates an access token for contacting the specified application endpoint
 
    .PARAMETER MailboxName
        The email address of the mailbox to access
 
    .PARAMETER Credential
        The credentials to use to authenticate the request.
        Using this avoids the need to visually interact with the logon screen.
        Only works for accounts that have once logged in visually, but can be used from any machine.
 
    .PARAMETER ClientId
        The ID of the client to connect with.
        This is the ID of the registered application.
 
    .PARAMETER RedirectUrl
        Some weird vodoo. Leave it as it is, unless you know better
 
    .PARAMETER ShowLoginWindow
        Force to show login window with account selection again.
 
    .PARAMETER Register
        Registers the token, so all subsequent calls to Exchange Online reuse it by default.
 
    .PARAMETER PassThru
        Outputs the token to the console, even when the register switch is set
 
    .PARAMETER IdentityPlatformVersion
        Specifies the endpoint version of the logon platform (Microsoft identity platform) where to connect for logon.
        Use 2.0 if you want to login with a Microsoft Account.
 
        For more information goto https://docs.microsoft.com/en-us/azure/active-directory/develop/about-microsoft-identity-platform
 
    .PARAMETER Tenant
        The entry point to sign into.
        The allowed values are common, organizations, consumers.
 
    .PARAMETER Permission
        Only applies if IdentityPlatformVersion version 2.0 is used.
        Specify the requested permission in the token.
 
    .PARAMETER ResourceUri
        The App ID URI of the target web API (secured resource).
        It may be https://graph.microsoft.com
 
    .EXAMPLE
        PS C:\> New-MgaAccessToken -Register
 
        For best usage and convinience, mostly, this is what you want to use.
 
        Requires an interactive session with a user handling the web UI.
        For addition the aquired token will be registered in the module as default value to use with all the commands.
 
    .EXAMPLE
        PS C:\> $token = New-MgaAccessToken
 
        Requires an interactive session with a user handling the web UI.
 
    .EXAMPLE
        PS C:\> $token = New-MgaAccessToken -Credential $cred
 
        Generates a token with the credentials specified in $cred.
        This is not supported for personal accounts (Micrsoft Accounts).
 
    .EXAMPLE
        PS C:\> New-MgaAccessToken -Register -ShowLoginWindow -ClientId '4a6acbac-d325-47a3-b59b-d2e9e05a37c1' -RedirectUrl 'urn:ietf:wg:oauth:2.0:oob' -IdentityPlatformVersion '2.0'
 
        Requires an interactive session with a user handling the web UI.
        Always prompt for account selection windows.
        Connecting against Azure Application with ID '4a6acbac-d325-47a3-b59b-d2e9e05a37c1'.
        Specifies RedirectUrl 'urn:ietf:wg:oauth:2.0:oob' (default value for interactive apps).
        Use Authentication Plattform 1.0, which only allows AzureAD business accounts to logon.
 
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingConvertToSecureStringWithPlainText", "")]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(DefaultParameterSetName = "LoginWithWebForm")]
    param (
        [Parameter(ParameterSetName = 'LoginWithCredentialObject')]
        [PSCredential]
        $Credential,

        [System.Guid]
        $ClientId = (Get-PSFConfigValue -FullName MSGraph.Tenant.Application.ClientID -NotNull),

        [string]
        $RedirectUrl = (Get-PSFConfigValue -FullName MSGraph.Tenant.Application.RedirectUrl -Fallback "urn:ietf:wg:oauth:2.0:oob"),

        [Parameter(ParameterSetName = 'LoginWithWebForm')]
        [Alias('Force')]
        [switch]
        $ShowLoginWindow,

        [ValidateSet('1.0', '2.0')]
        [string]
        $IdentityPlatformVersion = (Get-PSFConfigValue -FullName MSGraph.Tenant.Authentiation.IdentityPlatformVersion -Fallback '2.0'),

        [String[]]
        $Permission,

        [String]
        $ResourceUri = (Get-PSFConfigValue -FullName MSGraph.Tenant.ApiConnection -Fallback 'https://graph.microsoft.com'),

        [ValidateSet('common', 'organizations', 'consumers')]
        [String]
        $Tenant = 'common',

        [switch]
        $Register,

        [switch]
        $PassThru
    )
    begin {
        $baselineTimestamp = [datetime]"1970-01-01Z00:00:00"
        $endpointBaseUri = (Get-PSFConfigValue -FullName MSGraph.Tenant.Authentiation.Endpoint -Fallback 'https://login.microsoftonline.com')

        if ($IdentityPlatformVersion -like '1.0' -and $Permission) {
            Write-PSFMessage -Level Warning -Message "Individual pemissions are not supported in combination with IdentityPlatformVersion 1.0. Specified Permission ($([String]::Join(", ", $Permission))) in parameter will be ignored" -Tag "ParameterSetHandling"
            $Permission = ""
        } elseif ($IdentityPlatformVersion -like '2.0' -and (-not $Permission)) {
            $Permission = @("Mail.ReadWrite.Shared")
        }
    }

    process {
        # variable definitions
        switch ($IdentityPlatformVersion) {
            '1.0' { $endpointUri = "$($endpointBaseUri)/$($Tenant)/oauth2" }
            '2.0' {
                if ($Credential -and $Tenant -notlike "organizations") {
                    $endpointUri = "$($endpointBaseUri)/organizations/oauth2/V2.0"
                } else {
                    $endpointUri = "$($endpointBaseUri)/$($Tenant)/oauth2/V2.0"
                }
            }
        }

        $endpointUriAuthorize = "$($endpointUri)/authorize"
        $endpointUriToken = "$($endpointUri)/token"
        Write-PSFMessage -Level Verbose -Message "Start authentication against endpoint $($endpointUri). (Identity platform version $($IdentityPlatformVersion))" -Tag "Authorization"
        Write-PSFMessage -Level VeryVerbose -Message "Try to get token for usage of application ClientID: $($ClientId) to interact with ResourceAPI: $($ResourceUri)" -Tag "Authorization"

        if ($IdentityPlatformVersion -like '2.0') {
            [array]$scopes = "offline_access", "openid" # offline_access to get refreshtoken
            foreach ($permissionItem in $Permission) {
                $scopes = $scopes + "$($resourceUri)/$($permissionItem)"
            }
            $scope = [string]::Join(" ", $scopes)
            Remove-Variable -Name scopes -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false
            Write-PSFMessage -Level VeryVerbose -Message "Using scope: $($scope)" -Tag "Authorization"
        }

        #region Request an authorization code (login procedure)
        if (-not $Credential) {
            # build authorization string with web form
            # Info https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code#request-an-authorization-code
            Write-PSFMessage -Level Verbose -Message "Authentication is done by code. Query authentication from login form." -Tag "Authorization"

            $queryHash = [ordered]@{
                client_id     = "$($ClientId)"
                response_type = "code"
                redirect_uri  = [System.Web.HttpUtility]::UrlEncode($redirectUrl)
            }
            switch ($IdentityPlatformVersion) {
                '1.0' {
                    $queryHash.Add("resource", [System.Web.HttpUtility]::UrlEncode($resourceUri)) # optional, but recommended
                    if ($ShowLoginWindow) { $queryHash.Add("prompt", "select_account") }
                }

                '2.0' {
                    $queryHash.Add("scope", [uri]::EscapeDataString($scope))
                    if ($ShowLoginWindow) { $queryHash.Add("prompt", "login") }
                }
            }

            # Show login windows (web form)
            $phase1auth = Show-OAuthWindow -Url ($endpointUriAuthorize + (Convert-UriQueryFromHash $queryHash))
            if (-not $phase1auth.code) {
                $msg = "Authentication failed. Unable to obtain AccessToken.`n$($phase1auth.error_description)"
                if ($phase1auth.error) { $msg = $phase1auth.error.ToUpperInvariant() + " - " + $msg }
                Stop-PSFFunction -Message $msg -Tag "Authorization" -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg))
            }

            # build authorization string with authentication code from web form auth
            $tokenQueryHash = [ordered]@{
                client_id    = "$($ClientId)"
                grant_type   = "authorization_code"
                code         = "$($phase1auth.code)"
                redirect_uri = "$($redirectUrl)"
            }
            switch ($IdentityPlatformVersion) {
                '1.0' { $tokenQueryHash.Add("resource", [System.Web.HttpUtility]::UrlEncode($resourceUri)) }
                '2.0' { $tokenQueryHash.Add("scope", [uri]::EscapeDataString($scope)) }
            }
            $authorizationPostRequest = Convert-UriQueryFromHash $tokenQueryHash -NoQuestionmark
        } else {
            # build authorization string with plain text credentials
            # Info https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow#request-an-access-token
            Write-PSFMessage -Level Verbose -Message "Authentication is done by specified credentials. (No TwoFactor-Authentication supported!)" -Tag "Authorization"

            $tokenQueryHash = [ordered]@{
                grant_type = "password"
                username   = $Credential.UserName
                password   = $Credential.GetNetworkCredential().password
                client_id  = $ClientId
            }
            switch ($IdentityPlatformVersion) {
                '1.0' { $tokenQueryHash.Add("resource", [System.Web.HttpUtility]::UrlEncode($resourceUri)) }
                '2.0' { $tokenQueryHash.Add("scope", [uri]::EscapeDataString($scope)) }
            }

            $authorizationPostRequest = Convert-UriQueryFromHash $tokenQueryHash -NoQuestionmark
        }
        #endregion Request an authorization code (login procedure)

        # Request an access token
        $content = New-Object System.Net.Http.StringContent($authorizationPostRequest, [System.Text.Encoding]::UTF8, "application/x-www-form-urlencoded")
        $httpClient = New-HttpClient
        $clientResult = $httpClient.PostAsync([Uri]($endpointUriToken), $content)
        $jsonResponse = ConvertFrom-Json -InputObject $clientResult.Result.Content.ReadAsStringAsync().Result -ErrorAction Ignore
        if ($clientResult.Result.StatusCode -eq [System.Net.HttpStatusCode]"OK") {
            Write-PSFMessage -Level Verbose -Message "AccessToken granted. $($clientResult.Result.StatusCode.value__) ($($clientResult.Result.StatusCode)) $($clientResult.Result.ReasonPhrase)" -Tag "Authorization"
        } else {
            $httpClient.CancelPendingRequests()
            $msg = "Request for AccessToken failed. $($clientResult.Result.StatusCode.value__) ($($clientResult.Result.StatusCode)) $($clientResult.Result.ReasonPhrase) `n$($jsonResponse.error_description)"
            Stop-PSFFunction -Message $msg -Tag "Authorization" -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg))
        }

        # Build output object
        $resultObject = New-Object -TypeName MSGraph.Core.AzureAccessToken -Property @{
            IdentityPlatformVersion = $IdentityPlatformVersion
            TokenType               = $jsonResponse.token_type
            AccessToken             = $null
            RefreshToken            = $null
            IDToken                 = $null
            Credential              = $Credential
            ClientId                = $ClientId
            Resource                = $resourceUri
            AppRedirectUrl          = $RedirectUrl
        }
        switch ($IdentityPlatformVersion) {
            '1.0' {
                $resultObject.Scope = $jsonResponse.scope -split " "
                $resultObject.ValidUntilUtc = $baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToUniversalTime()
                $resultObject.ValidFromUtc = $baselineTimestamp.AddSeconds($jsonResponse.not_before).ToUniversalTime()
                $resultObject.ValidUntil = $baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToLocalTime().AddHours( [int]$baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToLocalTime().IsDaylightSavingTime() )
                $resultObject.ValidFrom = $baselineTimestamp.AddSeconds($jsonResponse.not_before).ToLocalTime().AddHours( [int]$baselineTimestamp.AddSeconds($jsonResponse.not_before).ToLocalTime().IsDaylightSavingTime() )
            }
            '2.0' {
                $resultObject.Scope = $jsonResponse.scope.Replace("$ResourceUri/", '') -split " "
                $resultObject.ValidUntilUtc = (Get-Date).AddSeconds($jsonResponse.expires_in).ToUniversalTime()
                $resultObject.ValidFromUtc = (Get-Date).ToUniversalTime()
                $resultObject.ValidUntil = (Get-Date).AddSeconds($jsonResponse.expires_in).ToLocalTime()
                $resultObject.ValidFrom = (Get-Date).ToLocalTime()
            }
        }

        # Insert token data into output object. done as secure string to prevent text output of tokens
        if ($jsonResponse.psobject.Properties.name -contains "refresh_token") { $resultObject.RefreshToken = ($jsonResponse.refresh_token | ConvertTo-SecureString -AsPlainText -Force) }
        if ($jsonResponse.psobject.Properties.name -contains "id_token") {
            $resultObject.IDToken = ($jsonResponse.id_token | ConvertTo-SecureString -AsPlainText -Force)
            $resultObject.AccessTokenInfo = ConvertFrom-JWTtoken -Token $jsonResponse.id_token
        }
        if ($jsonResponse.psobject.Properties.name -contains "access_token") {
            $resultObject.AccessToken = ($jsonResponse.access_token | ConvertTo-SecureString -AsPlainText -Force)
            if ($jsonResponse.access_token.Contains(".") -and $jsonResponse.access_token.StartsWith("eyJ")) {
                $resultObject.AccessTokenInfo = ConvertFrom-JWTtoken -Token $jsonResponse.access_token
            }
        }

        # Getting validity period out of AccessToken information
        if ($resultObject.AccessTokenInfo -and $resultObject.AccessTokenInfo.TenantID.ToString() -notlike "9188040d-6c67-4c5b-b112-36a304b66dad") {
            $resultObject.ValidUntilUtc = $resultObject.AccessTokenInfo.ExpirationTime.ToUniversalTime()
            $resultObject.ValidFromUtc = $resultObject.AccessTokenInfo.NotBefore.ToUniversalTime()
            $resultObject.ValidUntil = $resultObject.AccessTokenInfo.ExpirationTime.ToLocalTime().AddHours( [int]$resultObject.AccessTokenInfo.ExpirationTime.ToLocalTime().IsDaylightSavingTime() )
            $resultObject.ValidFrom = $resultObject.AccessTokenInfo.NotBefore.ToLocalTime().AddHours( [int]$resultObject.AccessTokenInfo.NotBefore.ToLocalTime().IsDaylightSavingTime() )
        }

        # Checking if token is valid
        # ToDo implement "validating token information" -> https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens#validating-tokens
        if ($resultObject.IsValid) {
            if ($Register) {
                $script:msgraph_Token = $resultObject
                if ($PassThru) { $resultObject }
            } else {
                $resultObject
            }
        } else {
            Stop-PSFFunction -Message "Token failure. Acquired token is not valid" -EnableException $true -Tag "Authorization"
        }
    }
}


function Register-MgaAccessToken {
    <#
    .SYNOPSIS
        Registers an access token
 
    .DESCRIPTION
        Registers an access token, so all subsequent calls to Exchange Online reuse it by default.
 
    .PARAMETER Token
        The Token to register as default token for subsequent calls.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .EXAMPLE
        PS C:\> Get-MgaRegisteredAccessToken
 
        Output the registered access token
    #>
    [CmdletBinding (SupportsShouldProcess = $false, ConfirmImpact = 'Medium')]
    [OutputType([MSGraph.Core.AzureAccessToken])]
    param (
        [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ValueFromRemainingArguments = $false)]
        [ValidateNotNullOrEmpty()]
        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru

    )

    $script:msgraph_Token = $Token
    if ($PassThru) {
        $script:msgraph_Token
    }
}

function Update-MgaAccessToken {
    <#
    .SYNOPSIS
        Updates an existing access token
 
    .DESCRIPTION
        Updates an existing access token for contacting the specified application endpoint as long
        as the token is still valid. Otherwise, a new access is called through New-MgaAccessToken.
 
    .PARAMETER Token
        The token object to renew.
 
    .PARAMETER Register
        Registers the renewed token, so all subsequent calls to Exchange Online reuse it by default.
 
    .PARAMETER PassThru
        Outputs the token to the console, even when the register switch is set
 
    .EXAMPLE
        PS C:\> Update-MgaAccessToken -Register
 
        Updates the default (registered) Accesstoken and register it again as the default token
 
    .EXAMPLE
        PS C:\> $token = Update-MgaAccessToken -Token $token
 
        Updates the AccessToken in $token and output a new AccessToken object.
    #>
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingConvertToSecureStringWithPlainText", "")]
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")]
    [CmdletBinding(DefaultParameterSetName = "Default")]
    param (
        [Parameter(ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [MSGraph.Core.AzureAccessToken]
        $Token,

        [Parameter(ParameterSetName = 'Register')]
        [switch]
        $Register,

        [Parameter(ParameterSetName = 'Register')]
        [switch]
        $PassThru
    )

    begin {
        $endpointBaseUri = (Get-PSFConfigValue -FullName MSGraph.Tenant.Authentiation.Endpoint -Fallback 'https://login.microsoftonline.com')
        $baselineTimestamp = [datetime]"1970-01-01Z00:00:00"
    }

    process {
        $Token = Resolve-Token -Token $Token -FunctionName $MyInvocation.MyCommand

        $Credential = $Token.Credential
        $ClientId = $Token.ClientId
        $RedirectUrl = $Token.AppRedirectUrl.ToString()
        $ResourceUri = $Token.Resource.ToString().TrimEnd('/')
        $Permission = ($Token.Scope | Where-Object { $_ -notin "offline_access", "openid", "profile", "email" })
        $IdentityPlatformVersion = $Token.IdentityPlatformVersion

        if (-not $Token.IsValid) {
            Write-PSFMessage -Level Warning -Message "Token lifetime already expired and can't be newed. New authentication is required. Calling New-MgaAccessToken..." -Tag "Authorization"

            $paramsNewToken = @{
                PassThru                = $True
                ClientId                = $ClientId
                RedirectUrl             = $RedirectUrl
                ResourceUri             = $ResourceUri
                Permission              = $Permission
                IdentityPlatformVersion = $IdentityPlatformVersion
            }
            if ($Credential) { $paramsNewToken.Add("Credential", $Credential ) }
            if ($Register -or ($script:msgraph_Token.AccessTokenInfo.Payload -eq $Token.AccessTokenInfo.Payload) ) { $paramsNewToken.Add("Register", $true) }
            if (Test-PSFParameterBinding -ParameterName Verbose) { $paramsNewToken.Add("Verbose", $true) }

            $resultObject = New-MgaAccessToken @paramsNewToken
            if ($PassThru) { return $resultObject } else { return }
        }

        Write-PSFMessage -Level Verbose -Message "Start token refresh for application $( if($Token.AppName){$Token.AppName}else{$ClientId} ). (Identity platform version $($IdentityPlatformVersion))" -Tag "Authorization"

        switch ($IdentityPlatformVersion) {
            '1.0' { $endpointUriToken = "$($endpointBaseUri)/common/oauth2/token" }
            '2.0' {
                if ($token.Credential) {
                    $endpointUriToken = "$($endpointBaseUri)/organizations/oauth2/V2.0/token"
                } else {
                    $endpointUriToken = "$($endpointBaseUri)/common/oauth2/V2.0/token"
                }

                [array]$scopes = "offline_access", "openid"
                foreach ($permissionItem in $Permission) {
                    $scopes = $scopes + "$($resourceUri)/$($permissionItem)"
                }
                $scope = [string]::Join(" ", $scopes)
                Remove-Variable -Name scopes -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false
                Write-PSFMessage -Level VeryVerbose -Message "Using scope: $($scope)" -Tag "Authorization"
            }
        }

        $queryHash = [ordered]@{
            grant_type    = "refresh_token"
            client_id     = $ClientId
            refresh_token = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto([System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($Token.RefreshToken))
        }
        switch ($IdentityPlatformVersion) {
            '1.0' { $queryHash.Add("resource", [System.Web.HttpUtility]::UrlEncode($resourceUri)) }
            '2.0' {
                $queryHash.Add("scope", [uri]::EscapeDataString($scope))
                $queryHash.Add("redirect_uri", [System.Web.HttpUtility]::UrlEncode($redirectUrl))
            }
        }
        $authorizationPostRequest = Convert-UriQueryFromHash $queryHash -NoQuestionmark

        $content = New-Object System.Net.Http.StringContent($authorizationPostRequest, [System.Text.Encoding]::UTF8, "application/x-www-form-urlencoded")
        $httpClient = New-HttpClient
        $clientResult = $httpClient.PostAsync([Uri]$endpointUriToken, $content)
        $jsonResponse = ConvertFrom-Json -InputObject $clientResult.Result.Content.ReadAsStringAsync().Result -ErrorAction Ignore
        if ($clientResult.Result.StatusCode -eq [System.Net.HttpStatusCode]"OK") {
            Write-PSFMessage -Level Verbose -Message "AccessToken renewal successful. $($clientResult.Result.StatusCode.value__) ($($clientResult.Result.StatusCode)) $($clientResult.Result.ReasonPhrase)" -Tag "Authorization"
        } else {
            $httpClient.CancelPendingRequests()
            $msg = "Request for AccessToken failed. $($clientResult.Result.StatusCode.value__) ($($clientResult.Result.StatusCode)) $($clientResult.Result.ReasonPhrase) `n$($jsonResponse.error_description)"
            Stop-PSFFunction -Message $msg -Tag "Authorization" -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg))
        }

        # Build output object
        $resultObject = New-Object -TypeName MSGraph.Core.AzureAccessToken -Property @{
            IdentityPlatformVersion = $IdentityPlatformVersion
            TokenType               = $jsonResponse.token_type
            AccessToken             = $null
            RefreshToken            = $null
            IDToken                 = $null
            Credential              = $Credential
            ClientId                = $ClientId
            Resource                = $resourceUri
            AppRedirectUrl          = $RedirectUrl
        }
        switch ($IdentityPlatformVersion) {
            '1.0' {
                $resultObject.Scope = $jsonResponse.scope -split " "
                $resultObject.ValidUntilUtc = $baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToUniversalTime()
                $resultObject.ValidFromUtc = $baselineTimestamp.AddSeconds($jsonResponse.not_before).ToUniversalTime()
                $resultObject.ValidUntil = $baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToLocalTime().AddHours( [int]$baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToLocalTime().IsDaylightSavingTime() )
                $resultObject.ValidFrom = $baselineTimestamp.AddSeconds($jsonResponse.not_before).ToLocalTime().AddHours( [int]$baselineTimestamp.AddSeconds($jsonResponse.not_before).ToLocalTime().IsDaylightSavingTime() )
            }
            '2.0' {
                $resultObject.Scope = $jsonResponse.scope.Replace("$ResourceUri/", '') -split " "
                $resultObject.ValidUntilUtc = (Get-Date).AddSeconds($jsonResponse.expires_in).ToUniversalTime()
                $resultObject.ValidFromUtc = (Get-Date).ToUniversalTime()
                $resultObject.ValidUntil = (Get-Date).AddSeconds($jsonResponse.expires_in).ToLocalTime()
                $resultObject.ValidFrom = (Get-Date).ToLocalTime()
            }
        }

        # Insert token data into output object. done as secure string to prevent text output of tokens
        if ($jsonResponse.psobject.Properties.name -contains "refresh_token") { $resultObject.RefreshToken = ($jsonResponse.refresh_token | ConvertTo-SecureString -AsPlainText -Force) }
        if ($jsonResponse.psobject.Properties.name -contains "id_token") {
            $resultObject.IDToken = ($jsonResponse.id_token | ConvertTo-SecureString -AsPlainText -Force)
            $resultObject.AccessTokenInfo = ConvertFrom-JWTtoken -Token $jsonResponse.id_token
        }
        if ($jsonResponse.psobject.Properties.name -contains "access_token") {
            $resultObject.AccessToken = ($jsonResponse.access_token | ConvertTo-SecureString -AsPlainText -Force)
            if ($jsonResponse.access_token.Contains(".") -and $jsonResponse.access_token.StartsWith("eyJ")) {
                $resultObject.AccessTokenInfo = ConvertFrom-JWTtoken -Token $jsonResponse.access_token
            }
        }

        # Getting validity period out of AccessToken information
        if ($resultObject.AccessTokenInfo -and $resultObject.AccessTokenInfo.TenantID.ToString() -notlike "9188040d-6c67-4c5b-b112-36a304b66dad") {
            $resultObject.ValidUntilUtc = $resultObject.AccessTokenInfo.ExpirationTime.ToUniversalTime()
            $resultObject.ValidFromUtc = $resultObject.AccessTokenInfo.NotBefore.ToUniversalTime()
            $resultObject.ValidUntil = $resultObject.AccessTokenInfo.ExpirationTime.ToLocalTime().AddHours( [int]$resultObject.AccessTokenInfo.ExpirationTime.ToLocalTime().IsDaylightSavingTime() )
            $resultObject.ValidFrom = $resultObject.AccessTokenInfo.NotBefore.ToLocalTime().AddHours( [int]$resultObject.AccessTokenInfo.NotBefore.ToLocalTime().IsDaylightSavingTime() )
        }

        # Checking if token is valid
        # ToDo implement "validating token information" -> https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens#validating-tokens
        if ($resultObject.IsValid) {
            if ($Register) {
                $script:msgraph_Token = $resultObject
                if ($PassThru) { $resultObject }
            } else {
                $resultObject
            }
        } else {
            Stop-PSFFunction -Message "Token failure. Acquired token is not valid" -EnableException $true -Tag "Authorization"
        }
    }

    end {
    }
}

function Add-MgaMailAttachment {
    <#
    .SYNOPSIS
        Add attachment(s) to a draft message in Exchange Online using the graph api.
 
    .DESCRIPTION
        Add attachment(s) to a draft message in Exchange Online using the graph api.
 
        Currently, only file attachments are supportet.
 
    .PARAMETER Message
        Carrier object for Pipeline input.
        This can be the id of the message or a message object passed in.
 
    .PARAMETER File
        The path to the file to add as attachment.
 
    .PARAMETER Link
        The ReferenceAttachment (aka "modern attachment", aka OneDriveLink) to add to the message..
 
    .PARAMETER Item
        The Outlook item to add as attachment.
 
    .PARAMETER Force
        Enforce adding attachment, even when the message is not in draft mode.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/message-post-attachments?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> $mail | Add-MgaMailAttachment -Path "logfile.txt"
 
        Add "logfile.txt" as attachment to message(s) in the variable $mail,
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Drafts -ResultSize 1
 
    .EXAMPLE
        PS C:\> $mail | Add-MgaMailAttachment -Link $ReferenceAttachment
 
        Add a modern attachment as attachment (reference link) to message(s) in the variable $mail,
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Drafts -ResultSize 1
 
        The variable $ReferenceAttachment has to be a object [MSGraph.Exchange.Attachment.ReferenceAttachment]
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'FileAttachment')]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0)]
        [Alias('InputObject', 'Id', 'Mail', 'MailMessage', 'MessageId', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(Mandatory = $true, ParameterSetName = 'FileAttachment')]
        [Alias('Path', 'FileName', 'FilePath')]
        [string[]]
        $File,

        [Parameter(Mandatory = $true, ParameterSetName = 'ReferenceAttachment')]
        [Alias('ReferenceAttachment', 'LinkPath', 'Uri', 'Url')]
        [MSGraph.Exchange.Attachment.ReferenceAttachment[]]
        $Link,

        [Parameter(Mandatory = $true, ParameterSetName = 'ItemAttachment')]
        [Alias('Event', 'OutlookItem')]
        [psobject[]]
        $Item,

        [switch]
        $Force,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        switch ($PSCmdlet.ParameterSetName) {
            'FileAttachment' {
                $filesToAttach = @()
                foreach ($filePath in $File) {
                    try {
                        $fileItem = Get-ChildItem -Path $filePath -File -ErrorAction Stop
                        $fileItem | Add-Member -MemberType NoteProperty -Name contentBytes -Value ( [System.Convert]::ToBase64String( [System.IO.File]::ReadAllBytes($fileItem.FullName) ) )
                        $filesToAttach = $filesToAttach + $fileItem
                    } catch {
                        Stop-PSFFunction -Message "Specified path '$($filePath)' is invalid or not a file. Please specify a valid file." -EnableException $true -Exception $errorvariable.Exception -Category InvalidData -Tag "Attachment"
                    }
                }
                $namesFileToAttach = "'$([string]::Join("', '",$filesToAttach.Name))'"
            }

            'ReferenceAttachment' {
                # ToDo implemented convinient parsing for referenceAttachments
                $namesFileToAttach = "'$([string]::Join("', '",$Link.Name))'"
            }

            'ItemAttachment' {
                # ToDo implemented adding item attachment
                Stop-PSFFunction -Message "adding item attachment is not implemented, yet."
                foreach ($itemObject in $Item) {
                }
            }

            Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
        }
    }

    process {
        foreach ($messageItem in $Message) {
            Write-PSFMessage -Level Debug -Message "Adding attachment(s) $($namesFileToAttach) to message '$($messageItem)' by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            if (-not $messageItem.InputObject.IsDraft -and (-not $Force)) {
                if ($PSCmdlet.ShouldContinue("The mesaage is not a draft message! Would you really like to add attachment(s) $($namesFileToAttach) to message '$($messageItem)'?", "$($messageItem) is not a draft message") ) {
                    Write-PSFMessage -Level Verbose -Message "Confirmation specified to add attachment(s) to non draft message '$($messageItem)'" -Tag "AddAttachmentEnforce"
                } else {
                    Write-PSFMessage -Level Important -Message "Abort adding attachment(s) to non draft message '$($messageItem)'" -Tag "AddAttachmentEnforce"
                    return
                }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            # prepare parameters for rest call
            $invokeParam = @{
                "Field"        = "messages/$($messageItem.Id)/attachments"
                "Token"        = $Token
                "User"         = $User
                "ApiVersion"   = "beta"
                "FunctionName" = $MyInvocation.MyCommand
            }

            $data = @()
            switch ($PSCmdlet.ParameterSetName) {
                'FileAttachment' {
                    foreach ($fileToAttach in $filesToAttach) {
                        # prepare REST Body
                        $bodyJSON = New-JsonAttachmentObject -Name $fileToAttach.Name -Size $fileToAttach.Length -IsInline $false -contentBytes $fileToAttach.contentBytes -FunctionName $MyInvocation.MyCommand
                        $invokeParam.Add("Body", $bodyJSON)

                        # add attachment
                        if ($pscmdlet.ShouldProcess("Message '$($messageItem)'", "Add FileAttachment '$($fileToAttach.FullName)'")) {
                            Write-PSFMessage -Level Verbose -Message "Add '$($fileToAttach.FullName)' to message '$($messageItem)'" -Tag "AddData"
                            $data = $data + (Invoke-MgaRestMethodPost @invokeParam)
                        }
                        $invokeParam.Remove("Body")
                    }
                }

                'ReferenceAttachment' {
                    foreach ($linkItem in $Link) {
                        # prepare REST Body
                        $bodyJSON = New-JsonAttachmentObject -SourceUrl $linkItem.SourceUrl -Name $linkItem.Name -ProviderType $linkItem.ProviderType -IsFolder $linkItem.IsFolder -Permission $linkItem.Permission -FunctionName $MyInvocation.MyCommand
                        $invokeParam.Add("Body", $bodyJSON)

                        # add attachment
                        if ($pscmdlet.ShouldProcess("Message '$($messageItem)'", "Add ReferenceAttachment '$($linkItem.Name)'")) {
                            Write-PSFMessage -Level Verbose -Message "Getting '$($linkItem.ToString())' as ReferenceAttachment to message '$($messageItem)'" -Tag "AddData"
                            $data = $data + (Invoke-MgaRestMethodPost @invokeParam)
                        }
                        $invokeParam.Remove("Body")
                    }
                }

                'ItemAttachment' {
                    # ToDo implemented adding item attachment
                    foreach ($itemObject in $Item) {
                    }
                }

                Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
            }

            #region output data
            foreach ($output in $data) {
                if ($PassThru) {
                    $AttachmentObject = New-MgaAttachmentObject -RestData $output -ParentObject $messageItem.InputObject -ApiVersion "beta" -ResultSize $ResultSize -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                    $AttachmentObject
                }
            }
            #endregion output data
        }
    }

    end {
    }
}

function Export-MgaMailAttachment {
    <#
    .SYNOPSIS
        Export a mail attachment to a file
 
    .DESCRIPTION
        Export/saves a mail attachment to a file
 
    .PARAMETER Attachment
        The attachment object to export
 
    .PARAMETER Path
        The directory where to export the attachment
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> Export-MgaMailAttachment -Attachment $attachment -Path "$HOME"
 
        Export the attement to the users profile base directory
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
    [Alias('Save-MgaMailAttachment')]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ValueFromRemainingArguments = $false)]
        [Alias('InputObject', 'AttachmentId', 'Id')]
        [MSGraph.Exchange.Attachment.AttachmentParameter[]]
        $Attachment,

        [String]
        $Path = (Get-Location).Path,

        [switch]
        $PassThru
    )
    begin {
        if (Test-Path -Path $Path -IsValid) {
            if (-not (Test-Path -Path $Path -PathType Container)) {
                Stop-PSFFunction -Message "Specified path is a file and not a path. Please specify a directory." -EnableException $true -Category "InvalidPath" -Tag "Attachment"
            }
        } else {
            Stop-PSFFunction -Message "Specified path is not valid. Please specify a valid directory." -EnableException $true -Category "InvalidPath" -Tag "Attachment"
        }
        $Path = Resolve-Path -Path $Path
    }

    process {
        foreach ($attachmentItem in $Attachment) {
            #switching between different types to export
            switch ($attachmentItem.TypeName) {
                "MSGraph.Exchange.Attachment.FileAttachment" {
                    if ($pscmdlet.ShouldProcess($attachmentItem, "Export to $($Path.Path)")) {
                        Write-PSFMessage -Level Verbose -Message "Exporting attachment '$($attachmentItem)' to '$($Path.ToString())'" -Tag "ExportData"
                        $attachmentItem.InputObject.ContentBytes | Set-Content -Path (Join-Path -Path $Path -ChildPath $attachmentItem.Name) -Encoding Byte
                    }
                }

                "MSGraph.Exchange.Attachment.ItemAttachment" {
                    if ($pscmdlet.ShouldProcess($attachmentItem, "Export to $($Path.Path)")) {
                        Write-PSFMessage -Level Important -Message "Export of $($attachmentItem.TypeName) is not implemented, yet. Could not export '$($attachmentItem.InputObject)'" -Tag "ExportData"
                    }
                }

                "MSGraph.Exchange.Attachment.ReferenceAttachment" {
                    if ($pscmdlet.ShouldProcess($attachmentItem, "Export to $($Path.Path)")) {
                        $shell = New-Object -ComObject ("WScript.Shell")
                        $shortCut = $shell.CreateShortcut("$($Path.Path)\$($attachmentItem.InputObject.Name).lnk")
                        $shortCut.TargetPath = $attachmentItem.InputObject.SourceUrl
                        $shortCut.Save()
                    }
                }

                "MSGraph.Exchange.Attachment.Attachment" {
                    Write-PSFMessage -Level Warning -Message "$($attachmentItem) is not a exportable attachment." -Tag "ParameterSetHandling"
                }

                Default {
                    Write-PSFMessage -Level Warning -Message "$($attachmentItem) is not a exportable attachment." -Tag "ParameterSetHandling"
                    continue
                }
            }

            if ($PassThru) { $attachmentItem }
        }
    }

    end {
    }
}

function Get-MgaMailAttachment {
    <#
    .SYNOPSIS
        Retrieves the attachment object from a email message in Exchange Online using the graph api.
 
    .DESCRIPTION
        Retrieves the attachment object from a email message in Exchange Online using the graph api.
 
    .PARAMETER Message
        Carrier object for Pipeline input.
        This can be the id of the message or a message object passed in.
 
    .PARAMETER Name
        The name to filter by.
        (Client Side filtering)
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER IncludeInlineAttachment
        This will retrieve also attachments like pictures in the html body of the mail.
 
    .PARAMETER ResultSize
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage | Get-MgaMailAttachment
 
        Return all emails attachments from all mails in the inbox of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage | Get-MgaMailAttachment -Name "MyName*"
 
        Return all emails attachments with name MyName* from all mails in the inbox of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage | Get-MgaMailAttachment -IncludeInlineAttachment
 
        Return also "inline" attachments, like pictures in html mails from all emails in the inbox of the user connected to through a token.
    #>
    [CmdletBinding(ConfirmImpact = 'Low', DefaultParameterSetName = 'Default')]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0)]
        [Alias('InputObject', 'Id', 'Mail', 'MailMessage', 'MessageId', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(Position = 1)]
        [Alias('Filter', 'NameFilter')]
        [string]
        $Name = "*",

        [switch]
        $IncludeInlineAttachment,

        [string]
        $User,

        [Int64]
        $ResultSize = (Get-PSFConfigValue -FullName 'MSGraph.Query.ResultSize' -Fallback 100),

        [MSGraph.Core.AzureAccessToken]
        $Token
    )
    begin {
        $requiredPermission = "Mail.Read"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        foreach ($messageItem in $Message) {
            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            #region query data
            $invokeParam = @{
                "Field"        = "messages/$($messageItem.Id)/attachments"
                "Token"        = $Token
                "User"         = $User
                "ResultSize"   = $ResultSize
                "ApiVersion"   = "beta"
                "FunctionName" = $MyInvocation.MyCommand
            }

            Write-PSFMessage -Level Verbose -Message "Getting attachment from message '$($messageItem)'" -Tag "QueryData"
            $data = Invoke-MgaRestMethodGet @invokeParam | Where-Object { $_.name -like $Name }
            if (-not $IncludeInlineAttachment) { $data = $data | Where-Object isInline -eq $false }
            #endregion query data

            #region output data
            foreach ($output in $data) {
                $AttachmentObject = New-MgaAttachmentObject -RestData $output -ParentObject $messageItem.InputObject -ApiVersion "beta" -ResultSize $ResultSize -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                $AttachmentObject
            }
            #endregion output data
        }
    }

    end {
    }
}

function Remove-MgaMailAttachment {
    <#
    .SYNOPSIS
        Remove attachment(s) from a email message(s) in Exchange Online using the graph api.
 
    .DESCRIPTION
        Remove attachment(s) from a email message(s) in Exchange Online using the graph api.
 
    .PARAMETER Message
        Carrier object for Pipeline input.
        This can be the id of the message or a message object passed in.
 
    .PARAMETER Attachment
        Carrier object for Pipeline input.
        This can be the id of the attachment or a attachment object passed in.
 
    .PARAMETER Name
        The name of the attachment to delete.
 
    .PARAMETER IncludeInlineAttachment
        Also search and remove InlineAttachment.
        Per default, only attachments outside a html body are recognized.
 
    .PARAMETER Force
        Suppress any confirmation request and enforce removing attachment on any kind of message.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the object to the console.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/attachment-delete?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage -Folder Drafts | Remove-MgaMailAttachment
 
        Delete attachment(s) from all mails in drafts folder of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage -Folder Drafts | Remove-MgaMailAttachment -Name "MyName*"
 
        Delete attachment(s) with name MyName* from all mails in drafts folder of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage -Folder Drafts | Remove-MgaMailAttachment -IncludeInlineAttachment
 
        Delete also "inline" attachments, like pictures in html mails from all emails in drafts folder of the user connected to through a token.
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High', DefaultParameterSetName = 'MessageInputObject')]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'MessageInput', Position = 0)]
        [Alias('Mail', 'MailMessage', 'MessageId', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'AttachmentInput', Position = 0)]
        [Alias('Attachments', 'AttachmentId', 'AttachmentObject')]
        [MSGraph.Exchange.Attachment.AttachmentParameter[]]
        $Attachment,

        [Parameter(ParameterSetName = 'MessageInput', Position = 1)]
        [Alias('Filter', 'NameFilter')]
        [string]
        $Name = "*",

        [switch]
        $IncludeInlineAttachment,

        [switch]
        $Force,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        if ($PSCmdlet.ParameterSetName -like 'MessageInput') {
            $Attachment = @()
            foreach ($messageItem in $Message) {
                #region checking input object type and query message if required
                if ($messageItem.TypeName -like "System.String") {
                    $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                    if (-not $messageItem) { continue }
                }

                if (-not $messageItem.InputObject.IsDraft -and (-not $Force)) {
                    if ($PSCmdlet.ShouldContinue("The mesaage is not a draft message! Would you really like to add attachment(s) $($namesFileToAttach) to message '$($messageItem)'?", "$($messageItem) is not a draft message") ) {
                        Write-PSFMessage -Level Verbose -Message "Confirmation specified to add attachment(s) to non draft message '$($messageItem)'" -Tag "AddAttachmentEnforce"
                    } else {
                        Write-PSFMessage -Level Important -Message "Abort adding attachment(s) to non draft message '$($messageItem)'" -Tag "AddAttachmentEnforce"
                        return
                    }
                }

                $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
                #endregion checking input object type and query message if required

                $getAttachmentParam = @{
                    "Message" = $messageItem
                    "Name"    = $Name
                    "User"    = $User
                    "Token"   = $Token
                }
                if ($IncludeInlineAttachment) { $getAttachmentParam.Add("IncludeInlineAttachment", $true) }
                $output = (Get-MgaMailAttachment @getAttachmentParam | Where-Object { $_.name -like $Name })
                if ($output) {
                    foreach ($outputItem in $output) {
                        $Attachment = $Attachment + [MSGraph.Exchange.Attachment.AttachmentParameter]$outputItem
                    }
                }
            }
            if (-not $Attachment) {
                Write-PSFMessage -Level Important -Message "Nothing found to delete." -Tag "QueryData"
            }
        }

        foreach ($attachmentItem in $Attachment) {
            Write-PSFMessage -Level Debug -Message "Deleting attachment '$($attachmentItem)' from message '$($attachmentItem.InputObject.ParentObject.Name)' by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

            # prepare parameters for rest call
            $invokeParam = @{
                "Field"        = "messages/$($attachmentItem.InputObject.ParentObject.Id)/attachments/$($attachmentItem.id)"
                "Token"        = $Token
                "User"         = $User
                "Confirm"      = $false
                "FunctionName" = $MyInvocation.MyCommand
            }

            # remove attachment
            if ($Force) {
                $proceed = $true
            } else {
                $proceed = $pscmdlet.ShouldProcess("Message '$($attachmentItem.InputObject.ParentObject.Name)'", "Delete attachment '$($attachmentItem)'")
            }
            if ($proceed) {
                Write-PSFMessage -Level Verbose -Message "Delete attachment '$($attachmentItem)' from message '$($attachmentItem.InputObject.ParentObject.Name)'" -Tag "RemoveData"
                Invoke-MgaRestMethodDelete @invokeParam
            }

            #region passthru data
            if ($PassThru) { $attachmentItem.InputObject }
            #endregion passthru data
        }
    }

    end {
    }
}

function Get-MgaExchCategory {
    <#
    .SYNOPSIS
        Retrieves categories in Exchange Online using the graph api.
 
    .DESCRIPTION
        Retrieves categories in Exchange Online using the graph api.
 
    .PARAMETER InputObject
        Carrier object for Pipeline input.Accepts CategoryObjects and strings.
 
    .PARAMETER Id
        The Id to filter by.
        (Client Side filtering)
 
    .PARAMETER Name
        The name to filter by.
        (Client Side filtering)
 
    .PARAMETER Color
        The color to filter by.
        (Client Side filtering)
 
        Tab completion is available on this parameter for the list of the 25 predefined colors.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER ResultSize
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .EXAMPLE
        PS C:\> Get-MgaExchCategory
 
        Return all categories of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaExchCategory -Id "89101089-690d-4263-9470-b674e709a996"
 
        Return the category with the specified Id of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaExchCategory -Name "*category"
 
        Return all categories with names like "*category" of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaExchCategory -Color "Blue"
 
        Return all categories with names like "*category" of the user connected to through a token.
 
    #>
    [CmdletBinding(ConfirmImpact = 'Low', DefaultParameterSetName = 'Default')]
    [OutputType([MSGraph.Exchange.Category.OutlookCategory])]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0, ParameterSetName = 'ByInputOBject')]
        [Alias('Category')]
        [MSGraph.Exchange.Category.CategoryParameter[]]
        $InputObject,

        [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'ById')]
        [Alias('IdFilter', 'FilterId')]
        [guid[]]
        $Id,

        [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'ByName')]
        [Alias('NameFilter', 'FilterName')]
        [string[]]
        $Name,

        [Parameter(Mandatory = $true, Position = 0, ParameterSetName = 'ByColor')]
        [Alias('ColorFilter', 'FilterColor')]
        [MSGraph.Exchange.Category.ColorName[]]
        $Color,

        [string]
        $User,

        [Int64]
        $ResultSize = (Get-PSFConfigValue -FullName 'MSGraph.Query.ResultSize' -Fallback 100),

        [MSGraph.Core.AzureAccessToken]
        $Token
    )
    begin {
        $requiredPermission = "MailboxSettings.Read"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        #region query data
        $invokeParam = @{
            "Token"        = $Token
            "User"         = $User
            "ResultSize"   = $ResultSize
            "FunctionName" = $MyInvocation.MyCommand
        }

        $data = @()
        if ($PSCmdlet.ParameterSetName -like 'ByInputOBject') {
            foreach ($categoryItem in $InputObject) {
                #region checking input object type and query message if required
                if ($categoryItem.TypeName -like "System.String") {
                    $categoryItem = Resolve-MailObjectFromString -Object $categoryItem -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                    if (-not $categoryItem) { continue }
                }

                $User = Resolve-UserInMailObject -Object $categoryItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
                #endregion checking input object type and query message if required

                $invokeParam.Add("Field", "outlook/masterCategories/$($categoryItem.Id)")
                Write-PSFMessage -Level Verbose -Message "Get refresh on category '$($categoryItem)'" -Tag "QueryData"
                $data = $data + (Invoke-MgaRestMethodGet @invokeParam)
                $invokeParam.Remove("Field")
            }
        } else {
            $invokeParam.Add("Field", "outlook/masterCategories")
            Write-PSFMessage -Level Verbose -Message "Getting available categories" -Tag "QueryData"
            $data = $data + (Invoke-MgaRestMethodGet @invokeParam)
        }
        #endregion query data

        #region filter data
        switch ($PSCmdlet.ParameterSetName) {
            'ById' {
                $data = foreach ($filter in $Id) {
                    Write-PSFMessage -Level VeryVerbose -Message "Filtering on id '$($filter)'." -Tag "FilterData"
                    $data | Where-Object Id -like $filter.Guid
                }
            }
            'ByName' {
                $data = foreach ($filter in $Name) {
                    Write-PSFMessage -Level VeryVerbose -Message "Filtering on name '$($filter)'." -Tag "FilterData"
                    $data | Where-Object displayname -like $filter
                }
            }
            'ByColor' {
                $data = foreach ($filter in $Color) {
                    Write-PSFMessage -Level VeryVerbose -Message "Filtering on color '$($filter)'." -Tag "FilterData"
                    $data | Where-Object Color -like ([MSGraph.Exchange.Category.OutlookCategory]::Parse($filter))
                }
            }
            Default {}
        }
        #endregion filter data

        #region output data
        Write-PSFMessage -Level VeryVerbose -Message "Output $( ($data | Measure-Object).Count ) objects." -Tag "OutputData"
        foreach ($output in $data) {
            if ($output.User) { $User = $output.User }
            $categoryObject = [MSGraph.Exchange.Category.OutlookCategory]::new( $output.id, $output.displayName, $output.color, $User, $output)
            Write-PSFMessage -Level Debug -Message "Output new object '$($categoryObject)'." -Tag "OutputData"
            $categoryObject
        }
        #endregion output data
    }

    end {
    }
}

function New-MgaExchCategory {
    <#
    .SYNOPSIS
        Creates a new category in Exchange Online using the graph api.
 
    .DESCRIPTION
        Creates a new category in Exchange Online using the graph api.
 
    .PARAMETER Name
        The category name.
 
    .PARAMETER Color
        The color for the category.
 
        Tab completion is available on this parameter for the list of the 25 predefined colors.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/outlookuser-post-mastercategories?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> New-MgaExchCategory -Name "Important stuff"
 
        Creates a category "Important stuff" in the mailbox of the user connected to through a token.
        The new category will creates without color mapping.
 
    .EXAMPLE
        PS C:\> Get-MgaExchCategory -Name "Important stuff" -Color "Blue"
 
        Creates a blue colored category "Important stuff" in the mailbox of the user connected to through a token.
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
    [OutputType([MSGraph.Exchange.Category.OutlookCategory])]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0)]
        [Alias('DisplayName', 'Category', 'InputObject')]
        [string[]]
        $Name,

        [Parameter(Mandatory = $false, Position = 1)]
        [Alias('ColorName')]
        [MSGraph.Exchange.Category.ColorName]
        $Color,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token
    )
    begin {
        $requiredPermission = "MailboxSettings.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        if ($Color) {
            [String]$colorValue = [MSGraph.Exchange.Category.OutlookCategory]::Parse($Color)
        } else {
            [String]$colorValue = [MSGraph.Exchange.Category.ColorKey]::None
        }
    }

    process {
        foreach ($categoryName in $Name) {
            Write-PSFMessage -Level Verbose -Message "Create new category '$($categoryName)'" -Tag "CreateData"

            #region prepare rest call to create data
            $bodyJSON = @{
                displayName = $categoryName
                color       = $colorValue
            } | ConvertTo-Json

            $invokeParam = @{
                "Field"        = "outlook/masterCategories"
                "Body"         = $bodyJSON
                "Token"        = $Token
                "User"         = $User
                "FunctionName" = $MyInvocation.MyCommand
            }
            #endregion prepare rest call to create data

            # create data
            if ($pscmdlet.ShouldProcess($categoryName, "Create")) {
                $data = Invoke-MgaRestMethodPost @invokeParam
            }

            #region output data
            foreach ($output in $data) {
                if ($output.User) { $User = $output.User }
                $categoryObject = [MSGraph.Exchange.Category.OutlookCategory]::new( $output.id, $output.displayName, $output.color, $User, $output)
                $categoryObject
            }
            #endregion output data
        }
    }

    end {
    }
}

function Remove-MgaExchCategory {
    <#
    .SYNOPSIS
        Remove a category in Exchange Online using the graph api.
 
    .DESCRIPTION
        Remove a category in Exchange Online using the graph api.
 
    .PARAMETER InputObject
        Carrier object for Pipeline input.Accepts CategoryObjects and strings.
 
    .PARAMETER Force
        Suppress any confirmation request and enforce removing.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the modified category to the console.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/outlookcategory-delete?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> Remove-MgaExchCategory -Name "Important stuff"
 
        Remove existing category "Important stuff" in the mailbox of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaExchCategory -Name "Important stuff" | Remove-MgaExchCategory -Force
 
        Remove existing category "Important stuff" WITHOUT CONFIRMATION in the mailbox of the user connected to through a token.
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    [OutputType([MSGraph.Exchange.Category.OutlookCategory])]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0)]
        [Alias('Name', 'DisplayName', 'Category')]
        [MSGraph.Exchange.Category.CategoryParameter[]]
        $InputObject,

        [switch]
        $Force,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "MailboxSettings.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        foreach ($categoryItem in $InputObject) {
            Write-PSFMessage -Level Verbose -Message "Working on removal of category '$($categoryItem)'" -Tag "QueryData"

            #region checking input object type and query message if required
            if ($categoryItem.TypeName -like "System.String") {
                $categoryItem = Resolve-MailObjectFromString -Object $categoryItem -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                if (-not $categoryItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $categoryItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            #region prepare rest call to create data

            $invokeParam = @{
                "Field"        = "outlook/masterCategories/$($categoryItem.Id)"
                "Token"        = $Token
                "User"         = $User
                "Confirm"      = $false
                "FunctionName" = $MyInvocation.MyCommand
            }
            #endregion prepare rest call to create data

            # set data
            if ($Force) {
                $proceed = $true
            } else {
                $proceed = $pscmdlet.ShouldProcess($categoryItem.Name, "Delete")
            }
            if ($proceed) {
                Write-PSFMessage -Level Verbose -Message "Delete category '$($categoryItem)'." -Tag "RemoveData"
                Invoke-MgaRestMethodDelete @invokeParam
            }

            #region output data
            if ($PassThru) { $categoryItem.InputObject }
            #endregion output data
        }
    }

    end {
    }
}

function Set-MgaExchCategory {
    <#
    .SYNOPSIS
        Set a category in Exchange Online using the graph api.
 
    .DESCRIPTION
        Set a category in Exchange Online using the graph api.
 
    .PARAMETER InputObject
        Carrier object for Pipeline input.Accepts CategoryObjects and strings.
 
    .PARAMETER Color
        The color for the category.
 
        Tab completion is available on this parameter for the list of the 25 predefined colors.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the modified category to the console.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/outlookcategory-update?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> Set-MgaExchCategory -Name "Important stuff" -Color Black
 
        Set color "black" on existing category "Important stuff" in the mailbox of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> Get-MgaExchCategory -Name "Important stuff" | Set-MgaExchCategory -Color "Blue"
 
        Set color "blue" on existing category "Important stuff" in the mailbox of the user connected to through a token.
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium')]
    [OutputType([MSGraph.Exchange.Category.OutlookCategory])]
    param (
        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Position = 0)]
        [Alias('Name', 'DisplayName', 'Category')]
        [MSGraph.Exchange.Category.CategoryParameter[]]
        $InputObject,

        <# Currently not available as writeable property on microsoft graph version 1.0 and beta
        [Parameter(Mandatory = $false)]
        [string]
        $NewName,
#>
        [Parameter(Mandatory = $false)]
        [Alias('ColorName')]
        [MSGraph.Exchange.Category.ColorName]
        $Color,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "MailboxSettings.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        foreach ($categoryItem in $InputObject) {
            #region checking input object type and query message if required
            if ($categoryItem.TypeName -like "System.String") {
                $categoryItem = Resolve-MailObjectFromString -Object $categoryItem -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                if (-not $categoryItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $categoryItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            #region prepare rest call to create data
            $bodyJSON = @{}
            $boundParameters = @()
            if ($NewName) {
                $boundParameters = $boundParameters + "NewName"
                $bodyJSON.Add("displayName", $NewName)
            }
            if ($Color) {
                $boundParameters = $boundParameters + "Color"
                [String]$colorValue = [MSGraph.Exchange.Category.OutlookCategory]::Parse($Color)
                $bodyJSON.Add("color", $colorValue.ToLower())
            }
            $bodyJSON = $bodyJSON | ConvertTo-Json

            $invokeParam = @{
                "Field"        = "outlook/masterCategories/$($categoryItem.Id)"
                "Body"         = $bodyJSON
                "Token"        = $Token
                "User"         = $User
                "FunctionName" = $MyInvocation.MyCommand
            }
            #endregion prepare rest call to create data
            Write-PSFMessage -Level Verbose -Message "Set property '$([string]::Join("', '", $boundParameters))' on category '$($categoryItem)'" -Tag "SetData"

            # set data
            if ($pscmdlet.ShouldProcess($categoryItem, "Set property '$([string]::Join("', '", $boundParameters))'")) {
                $data = Invoke-MgaRestMethodPatch @invokeParam
            }

            #region output data
            if ($PassThru) {
                foreach ($output in $data) {
                    if ($output.User) { $User = $output.User }
                    $categoryObject = [MSGraph.Exchange.Category.OutlookCategory]::new( $output.id, $output.displayName, $output.color, $User, $output)
                    $categoryObject
                }
            }
            #endregion output data
        }
    }

    end {
    }
}

function Get-MgaMailFolder {
    <#
    .SYNOPSIS
        Get mail folder(s) in Exchange Online
 
    .DESCRIPTION
        Get mail folder(s) with metadata from Exchange Online via Microsoft Graph API
 
    .PARAMETER Name
        The name of the folder(S) to query.
 
    .PARAMETER IncludeChildFolders
        Output all subfolders on queried folder(s).
 
    .PARAMETER Recurse
        Iterates through the whole folder structure and query all subfolders.
 
    .PARAMETER Filter
        The name to filter by.
        (Client Side filtering)
 
        Try to avoid, when filtering on single name, use parameter -Name instead of -Filter.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER ResultSize
        The user to execute this under.
        Defaults to the user the token belongs to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .EXAMPLE
        PS C:\> Get-MgaMailFolder
 
        Returns all folders in the mailbox of the connected user.
 
    .EXAMPLE
        PS C:\> Get-MgaMailFolder -Name Inbox
 
        Returns the "wellknown" inbox folder in the mailbox of the connected user.
        The wellknown folders can be specified by tab completion.
 
    .EXAMPLE
        PS C:\> Get-MgaMailFolder -Name Inbox -IncludeChildFolders
 
        Returns inbox and the next level of subfolders in the inbox of the connected user.
 
    .EXAMPLE
        PS C:\> Get-MgaMailFolder -Name Inbox -Recurse
 
        Returns inbox and the all subfolders underneath the inbox of the connected user.
        This one is like the "-Recurse" switch on the dir/Get-ChildItem command.
 
    .EXAMPLE
        PS C:\> Get-MgaMailFolder -Filter "My*" -User "max.master@contoso.onmicrosoft.com" -Token $Token
 
        Retrieves all folders where name starts with My in the mailbox of "max.master@contoso.onmicrosoft.com", using the connection token stored in $Token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailFolder -ResultSize 5
 
        Retrieves only the first 5 folders in the mailbox of the connected user.
    #>
    [CmdletBinding(DefaultParameterSetName = 'Default')]
    [OutputType([MSGraph.Exchange.Mail.Folder])]
    param (
        [Parameter(ParameterSetName = 'ByFolderName', ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, Mandatory = $true, Position = 0)]
        [Alias('FolderName', 'InputObject', 'DisplayName', 'Id')]
        [MSGraph.Exchange.Mail.FolderParameter[]]
        $Name,

        [switch]
        $IncludeChildFolders,

        [switch]
        $Recurse,

        [string]
        $Filter = "*",

        [string]
        $User,

        [Int64]
        $ResultSize = (Get-PSFConfigValue -FullName 'MSGraph.Query.ResultSize' -Fallback 100),

        [MSGraph.Core.AzureAccessToken]
        $Token
    )

    begin {
        $requiredPermission = "Mail.Read"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        if ($Recurse) { $IncludeChildFolders = $true }

        #region helper subfunctions
        function invoke-internalMgaGetMethod ($invokeParam, [int]$level, [MSGraph.Exchange.Mail.Folder]$parentFolder, [String]$FunctionName) {
            # Subfunction for query objects and creating valid new objects from the query result
            $folderData = Invoke-MgaRestMethodGet @invokeParam
            foreach ($folderOutput in $folderData) {
                New-MgaMailFolderObject -RestData $folderOutput -ParentFolder $parentFolder -Level $level #-FunctionName $FunctionName
            }
        }

        function get-childfolder ($output, [int]$level, $invokeParam) {
            $FoldersWithChilds = $output | Where-Object ChildFolderCount -gt 0
            $childFolders = @()

            do {
                $level = $level + 1
                foreach ($folderItem in $FoldersWithChilds) {
                    if ($folderItem.ChildFolderCount -gt 0) {
                        Write-PSFMessage -Level VeryVerbose -Message "Getting childfolders for folder '$($folderItem.Name)'" -Tag "QueryData"
                        $invokeParam.Field = "mailFolders/$($folderItem.Id)/childFolders"
                        $childFolderOutput = invoke-internalMgaGetMethod -invokeParam $invokeParam -level $level -parentFolder $folderItem -FunctionName $MyInvocation.MyCommand

                        $FoldersWithChilds = $childFolderOutput | Where-Object ChildFolderCount -gt 0
                        $childFolders = $childFolders + $childFolderOutput
                    }
                }
            } while ($Recurse -and $FoldersWithChilds)

            $childFolders
        }
        #endregion helper subfunctions
    }

    process {
        Write-PSFMessage -Level VeryVerbose -Message "Gettings folder(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"
        switch ($PSCmdlet.ParameterSetName) {
            "Default" {
                $baseLevel = 1
                $invokeParam = @{
                    "Field"        = 'mailFolders'
                    "Token"        = $Token
                    "User"         = Resolve-UserString -User $User
                    "ResultSize"   = $ResultSize
                    "FunctionName" = $MyInvocation.MyCommand
                }

                $output = invoke-internalMgaGetMethod -invokeParam $invokeParam -level $baseLevel -FunctionName $MyInvocation.MyCommand  | Where-Object displayName -Like $Filter

                if ($output -and $IncludeChildFolders) {
                    $childFolders = $output | Where-Object ChildFolderCount -gt 0 | ForEach-Object {
                        get-childfolder -output $_ -level $baseLevel -invokeParam $invokeParam
                    }
                    if ($childFolders) {
                        [array]$output = [array]$output + $childFolders
                    }
                }

                if (-not $output) {
                    Stop-PSFFunction -Message "Unexpected error. Could not query root folders from user '$($User)'." -Tag "QueryData" -EnableException $true
                }
            }

            "ByFolderName" {
                foreach ($folder in $Name) {
                    $baseLevel = 1
                    Write-PSFMessage -Level VeryVerbose -Message "Getting folder '$( if($folder.Name){$folder.Name}else{$folder.Id} )'" -Tag "ParameterSetHandling"
                    $invokeParam = @{
                        "Token"        = $Token
                        "User"         = Resolve-UserString -User $User
                        "ResultSize"   = $ResultSize
                        "FunctionName" = $MyInvocation.MyCommand
                    }
                    if ($folder.id) {
                        $invokeParam.add("Field", "mailFolders/$($folder.Id)")
                    } else {
                        $invokeParam.add("Field", "mailFolders?`$filter=DisplayName eq '$($folder.Name)'")
                    }

                    $output = invoke-internalMgaGetMethod -invokeParam $invokeParam -level $baseLevel -FunctionName $MyInvocation.MyCommand | Where-Object displayName -Like $Filter

                    if ($output -and $IncludeChildFolders) {
                        $childFolders = get-childfolder -output $output -level $baseLevel -invokeParam $invokeParam
                        if ($childFolders) {
                            [array]$output = [array]$output + $childFolders
                        }
                    }

                    if (-not $output) {
                        Write-PSFMessage -Level Warning -Message "Folder '$($folder)' not found." -Tag "QueryData"
                    }
                }
            }

            Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
        }

        $output
    }

    end {
    }
}

function Move-MgaMailFolder {
    <#
    .SYNOPSIS
        Move folder(s) to another folder
 
    .DESCRIPTION
        Move folder(s) to another folder in Exchange Online using the graph api.
 
    .PARAMETER Folder
        Carrier object for Pipeline input. Accepts folders and strings.
 
    .PARAMETER DestinationFolder
        The destination folder where to move the folder to.
 
        Tab completion is available on this parameter for a list of well known folders.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational folders will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> Move-MgaMailFolder -Folder $folder -DestinationFolder $destinationFolder
 
        Moves the folder(s) in variable $folder to the folder in the variable $destinationFolder.
        also possible:
        PS C:\> $folder | Move-MgaMailFolder -DestinationFolder $destinationFolder
 
        The variable $folder can be represent:
        PS C:\> $folder = Get-MgaMailFolder -Name "MyFolder"
 
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    .EXAMPLE
        PS C:\> Move-MgaMailFolder -Id $folder.id -DestinationFolder $destinationFolder.id
 
        Moves folders into the folder $destinationFolder.
 
        The variable $folder can be represent:
        PS C:\> $folder = Get-MgaMailFolder -Name "MyFolder"
 
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [Alias()]
    [OutputType([MSGraph.Exchange.Mail.Folder])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('InputObject', 'FolderId', 'Id')]
        [MSGraph.Exchange.Mail.FolderParameter[]]
        $Folder,

        [Parameter(Mandatory = $true, Position = 1)]
        [Alias('DestinationObject', 'DestinationFolderId')]
        [MSGraph.Exchange.Mail.FolderParameter]
        $DestinationFolder,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        #region checking DestinationFolder and query folder if required
        if ($DestinationFolder.TypeName -like "System.String") {
            $DestinationFolder = Resolve-MailObjectFromString -Object $DestinationFolder -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
            if (-not $DestinationFolder) { throw }
        }

        $User = Resolve-UserInMailObject -Object $DestinationFolder -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
        #endregion checking DestinationFolder and query folder if required

        $bodyJSON = @{
            destinationId = $DestinationFolder.Id
        } | ConvertTo-Json
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings folder(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        foreach ($folderItem in $Folder) {
            #region checking input object type and query folder if required
            if ($folderItem.TypeName -like "System.String") {
                $folderItem = Resolve-MailObjectFromString -Object $folderItem -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                if (-not $folderItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $folderItem -User $User -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            if ($pscmdlet.ShouldProcess("Folder '$($folderItem)'", "Move to '$($DestinationFolder)'")) {
                Write-PSFMessage -Tag "FolderUpdate" -Level Verbose -Message "Move folder '$($folderItem)' into folder '$($DestinationFolder)'"
                $invokeParam = @{
                    "Field"        = "mailFolders/$($folderItem.Id)/move"
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                $output = Invoke-MgaRestMethodPost @invokeParam
                if ($PassThru) {
                    New-MgaMailFolderObject -RestData $output -ParentFolder $DestinationFolder.InputObject -FunctionName $MyInvocation.MyCommand
                }
            }
        }
    }

}

function New-MgaMailFolder {
    <#
    .SYNOPSIS
        Creates a folder in Exchange Online using the graph api.
 
    .DESCRIPTION
        Creates a new folder in Exchange Online using the graph api.
 
    .PARAMETER Name
        The name to be set as new name.
 
    .PARAMETER ParentFolder
        The folder where the new folder should be created in. Do not specify to create
        a folder on the root level.
 
        Possible values are a valid folder Id or a Mga folder object passed in.
        Tab completion is available on this parameter for a list of well known folders.
 
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> New-MgaMailFolder -Name 'MyFolder'
 
        Creates a new folder named "MyFolder" on the root level of the mailbox
 
    .EXAMPLE
        PS C:\> New-MgaMailFolder -Name 'MyFolder' -ParentFolder $folder
 
        Creates a new folder named "MyFolder" inside the folder passed in with the variable $folder
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [OutputType([MSGraph.Exchange.Mail.Folder])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('FolderName', 'DisplayName')]
        [string[]]
        $Name,

        [Parameter(Mandatory = $false, Position = 1)]
        [Alias('Parent', 'ParentFolderId')]
        [MSGraph.Exchange.Mail.FolderParameter[]]
        $ParentFolder,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        #region checking input object type and query folder if required
        if ($ParentFolder.TypeName -like "System.String") {
            $ParentFolder = Resolve-MailObjectFromString -Object $ParentFolder -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
            if (-not $ParentFolder) { throw }
        }

        if ($ParentFolder) {
            $User = Resolve-UserInMailObject -Object $ParentFolder -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
        }
        #endregion checking input object type and query message if required
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings folder(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        foreach ($NameItem in $Name) {
            if ($pscmdlet.ShouldProcess($NameItem, "New")) {
                $msg = "Creating subfolder '$($NameItem)'"
                if ($ParentFolder) { $msg = $msg + " in '$($ParentFolder)'"}
                Write-PSFMessage -Tag "FolderCreation" -Level Verbose -Message $msg

                $bodyJSON = @{
                    displayName = $NameItem
                } | ConvertTo-Json

                $invokeParam = @{
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                if ($ParentFolder.Id) {
                    $invokeParam.Add("Field", "mailFolders/$($ParentFolder.Id)/childFolders")
                } else {
                    $invokeParam.Add("Field", "mailFolders")
                }

                $output = Invoke-MgaRestMethodPost @invokeParam
                New-MgaMailFolderObject -RestData $output -ParentFolder $ParentFolder.InputObject -FunctionName $MyInvocation.MyCommand
            }
        }
    }

    end {
    }
}

function Remove-MgaMailFolder {
    <#
    .SYNOPSIS
        Remove folder(s) in Exchange Online using the graph api.
 
    .DESCRIPTION
        Remove folder(s) in Exchange Online using the graph api.
 
        ATTENTION! The command does what it is name to!
        The folder will not be moved to 'deletedObjects', it will be deleted.
 
    .PARAMETER Folder
        The folder to be removed.
        This can be a name of the folder, it can be the Id of the folder or it can be a folder object passed in.
 
        Tab completion is available on this parameter for a list of well known folders.
 
    .PARAMETER Force
        If specified the user will not prompted on confirmation.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> Remove-MgaMailFolder -Name 'MyFolder'
 
        Removes folder named "MyFolder".
        The folder has to be on the root level of the mailbox to be specified by individual name.
 
    .EXAMPLE
        PS C:\> Remove-MgaMailFolder -Name $folder
 
        Removes folder represented by the variable $folder.
        You will be prompted for confirmation.
 
        The variable $folder can be represent:
        PS C:\> $folder = Get-MgaMailFolder -Folder "MyFolder"
 
    .EXAMPLE
        PS C:\> $folder | Remove-MgaMailFolder -Force
 
        Removes folder represented by the variable $folder.
        ATTENTION, There will be NO prompt for confirmation!
 
        The variable $folder can be represent:
        PS C:\> $folder = Get-MgaMailFolder -Folder "MyFolder"
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    [OutputType([MSGraph.Exchange.Mail.Folder])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('FolderName', 'FolderId', 'InputObject', 'DisplayName', 'Name', 'Id')]
        [MSGraph.Exchange.Mail.FolderParameter[]]
        $Folder,

        [switch]
        $Force,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings folder(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        foreach ($folderItem in $Folder) {
            #region checking input object type and query folder if required
            if ($folderItem.TypeName -like "System.String") {
                if (($folderItem.IsWellKnownName -and $folderItem.Id -like "recoverableitemsdeletions") -or $folderItem.name -like "recoverableitemsdeletions") {
                    Write-PSFMessage -Level Important -Message "Can not delete well known folder 'recoverableitemsdeletions'. Continue without action on folder."
                    continue
                }
                $folderItem = Resolve-MailObjectFromString -Object $folderItem -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                if (-not $folderItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $folderItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            if ($Force) { $doAction = $true } else { $doAction = $pscmdlet.ShouldProcess($folderItem, "Remove (ATTENTION! Folder will not be moved to 'deletedObjects')") }
            if ($doAction) {
                Write-PSFMessage -Tag "FolderRemove" -Level Verbose -Message "Remove folder '$($folderItem)'"
                $invokeParam = @{
                    "Field"        = "mailFolders/$($folderItem.Id)"
                    "User"         = $User
                    "Body"         = ""
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "Force"        = $true
                    "FunctionName" = $MyInvocation.MyCommand
                }
                $null = Invoke-MgaRestMethodDelete @invokeParam
                if ($PassThru) {
                    $folderItem.InputObject
                }
            }
        }
    }

    end {
    }
}

function Rename-MgaMailFolder {
    <#
    .SYNOPSIS
        Rename folder(s) in Exchange Online using the graph api.
 
    .DESCRIPTION
        Change the displayname of folder(s) in Exchange Online using the graph api.
 
    .PARAMETER Folder
        The folder to be renamed. This can be a name of the folder, it can be the
        Id of the folder or it can be a folder object passed in.
 
    .PARAMETER NewName
        The name to be set as new name.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> Rename-MgaMailFolder -Folder 'Inbox' -NewName 'MyPersonalInbox'
 
        Rename the "wellknown" folder inbox (regardless of it's current name), to 'MyPersonalInbox'.
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [OutputType([MSGraph.Exchange.Mail.Folder])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'ByInputObject')]
        [Alias('FolderName', 'FolderId', 'InputObject', 'DisplayName', 'Name', 'Id')]
        [MSGraph.Exchange.Mail.FolderParameter[]]
        $Folder,

        [Parameter(Mandatory = $true, Position = 1)]
        [string]
        $NewName,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        $bodyJSON = @{
            displayName = $NewName
        } | ConvertTo-Json
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings folder(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        foreach ($folderItem in $Folder) {
            #region checking input object type and query folder if required
            if ($folderItem.TypeName -like "System.String") {
                $folderItem = Resolve-MailObjectFromString -Object $folderItem -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                if (-not $folderItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $folderItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            if ($pscmdlet.ShouldProcess("Folder '$($folderItem)'", "Rename to '$($NewName)'")) {
                Write-PSFMessage -Tag "FolderUpdate" -Level Verbose -Message "Rename folder '$($folderItem)' to name '$($NewName)'"
                $invokeParam = @{
                    "Field"        = "mailFolders/$($folderItem.Id)"
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                $output = Invoke-MgaRestMethodPatch @invokeParam
                if ($PassThru) {
                    New-MgaMailFolderObject -RestData $output -ParentFolder $folderItem.InputObject.ParentFolder -FunctionName $MyInvocation.MyCommand
                }
            }
        }
    }

    end {
    }
}

function Add-MgaMailMessageForward {
    <#
    .SYNOPSIS
        Forward message(s) in Exchange Online using the graph api.
 
    .DESCRIPTION
        Creates forward message(s) and save it as draft message(s).
 
        Alternatively, the command can directly forward a message by specifing recipient(s) and text
        The message is then saved in the Sent Items folder.
 
    .PARAMETER Message
        Carrier object for Pipeline input.
        This can be the id of the message or a message object passed in.
 
    .PARAMETER Comment
        The body of the message.
 
    .PARAMETER ToRecipients
        The To recipients for the message.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/message-createforward?view=graph-rest-1.0
        https://docs.microsoft.com/en-us/graph/api/message-forward?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> $mail | Add-MgaMailMessageForward
 
        Create forward message(s) and save it in the drafts folder for messages from variable $mail.
        also possible:
        PS C:\> Add-MgaMailMessageForward -Message $mail
 
        The variable $mail can be represent:
        PS C:\> $mail = Get-MgaMailMessage -Subject "Important mail"
 
    .EXAMPLE
        PS C:\> $mail | Add-MgaMailMessageForward -ToRecipients 'someone@something.org' -Comment 'For your information.'
 
        This one directly forwards message(s) from variable $mail. The message(s) is saved in the sendItems folder
 
        The variable $mail can be represent:
        PS C:\> $mail = Get-MgaMailMessage -Subject "Important mail"
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [Alias('Add-MgaMailForwardMessage')]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)] #, ParameterSetName = 'ByInputObject'
        [Alias('InputObject', 'MessageId', 'Id', 'Mail', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(Mandatory = $true, ParameterSetName = 'DirectReply')]
        [Alias('To', 'Recipients')]
        [string[]]
        $ToRecipients,

        [Parameter(Mandatory = $true, ParameterSetName = 'DirectReply')]
        [Alias('Body', 'Text', 'ReplyText')]
        [String]
        $Comment,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [Parameter(ParameterSetName = 'DirectReply')]
        [switch]
        $PassThru
    )
    begin {
        if ($PSCmdlet.ParameterSetName -like 'DirectReply') {
            $requiredPermission = "Mail.Send"
        } else {
            $requiredPermission = "Mail.ReadWrite"
        }
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        Write-PSFMessage -Level Debug -Message "Working on parameter set $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        foreach ($messageItem in $Message) {
            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand

            if ($PSCmdlet.ParameterSetName -like 'DirectReply') {
                $bodyJSON = New-JsonMailObject -ToRecipients $ToRecipients -Comment $Comment -FunctionName $MyInvocation.MyCommand
                $msgAction = "Send"
            } else {
                $bodyJSON = ""
                $msgAction = "create"
            }
            #endregion checking input object type and query message if required

            #region send message
            $msg = $msgAction + " reply$(if($ReplyAll){" all"})"
            if ($pscmdlet.ShouldProcess($messageItem, $msg)) {
                Write-PSFMessage -Tag "MessageReply$msgAction" -Level Verbose -Message "$($msg) message for '$($messageItem)'"
                $invokeParam = @{
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                switch ($PSCmdlet.ParameterSetName) {
                    'Default' { $invokeParam.Add("Field", "messages/$($messageItem.Id)/createForward") }
                    'DirectReply' { $invokeParam.Add("Field", "messages/$($messageItem.Id)/forward") }
                    Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
                }

                $output = Invoke-MgaRestMethodPost @invokeParam
                if ($PSCmdlet.ParameterSetName -like 'Default' -and $output) {
                    New-MgaMailMessageObject -RestData $output -FunctionName $MyInvocation.MyCommand
                } elseif ($PSCmdlet.ParameterSetName -like 'DirectReply' -and $PassThru) {
                    Write-PSFMessage -Tag "MessageQuery" -Level Verbose -Message "PassThru specified, query forward message from sentItems folder."
                    Get-MgaMailMessage -FolderName Sentitems -Subject "FW: $($messageItem.Name)" -ResultSize 5
                }
            }
            #endregion send message
        }
    }

    end {
    }
}

function Add-MgaMailMessageReply {
    <#
    .SYNOPSIS
        Create reply (all) message(s) in Exchange Online using the graph api.
 
    .DESCRIPTION
        Create reply (all) message(s) and save it as draft message(s).
 
        Alternatively, the command can directly send the reply (all) by specifing a text
        The message is then saved in the Sent Items folder.
 
    .PARAMETER Message
        Carrier object for Pipeline input.
        This can be the id of the message or a message object passed in.
 
    .PARAMETER Comment
        The body of the message.
 
    .PARAMETER ReplyAll
        Creates a reply all message.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/message-createreply?view=graph-rest-1.0
        https://docs.microsoft.com/en-us/graph/api/message-reply?view=graph-rest-1.0
        https://docs.microsoft.com/en-us/graph/api/message-createreplyall?view=graph-rest-1.0
        https://docs.microsoft.com/en-us/graph/api/message-replyall?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> $mail | Add-MgaMailMessageReply
 
        Create reply message(s) for messages in variable $mail.
        also possible:
        PS C:\> Add-MgaMailMessageReply -Message $mail
 
        The variable $mail can be represent:
        PS C:\> $mail = Get-MgaMailMessage -Subject "Important mail"
 
    .EXAMPLE
        PS C:\> $mail | Add-MgaMailMessageReply -Comment 'Reply for confirmation to your message.'
 
        This one directly send reply message(s) for messages from variable $mail.
        The message(s) is saved in the sendItems folder
 
        The variable $mail can be represent:
        PS C:\> $mail = Get-MgaMailMessage -Subject "Important mail"
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [Alias('Add-MgaMailReplyMessage')]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)] #, ParameterSetName = 'ByInputObject'
        [Alias('InputObject', 'MessageId', 'Id', 'Mail', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(Mandatory = $true, ParameterSetName = 'DirectReply')]
        [Alias('Body', 'Text', 'ReplyText')]
        [String]
        $Comment,

        [Alias('All')]
        [switch]
        $ReplyAll,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [Parameter(ParameterSetName = 'DirectReply')]
        [switch]
        $PassThru
    )
    begin {
        if ($PSCmdlet.ParameterSetName -like 'DirectReply') {
            $requiredPermission = "Mail.Send"
        } else {
            $requiredPermission = "Mail.ReadWrite"
        }
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        Write-PSFMessage -Level Debug -Message "Working on parameter set $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        foreach ($messageItem in $Message) {
            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand

            if ($PSCmdlet.ParameterSetName -like 'DirectReply') {
                $bodyJSON = @{
                    comment = $Comment
                } | ConvertTo-Json
                $msgAction = "Send"
            } else {
                $bodyJSON = ""
                $msgAction = "create"
            }
            #endregion checking input object type and query message if required

            #region send message
            $msg = $msgAction + " reply$(if($ReplyAll){" all"})"
            if ($pscmdlet.ShouldProcess($messageItem, $msg)) {
                Write-PSFMessage -Tag "MessageReply$msgAction" -Level Verbose -Message "$($msg) message for '$($messageItem)'"
                $invokeParam = @{
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                switch ($PSCmdlet.ParameterSetName) {
                    'Default' { $invokeParam.Add("Field", "messages/$($messageItem.Id)/createReply$(if($ReplyAll){"All"})") }
                    'DirectReply' { $invokeParam.Add("Field", "messages/$($messageItem.Id)/reply$(if($ReplyAll){"All"})") }
                    Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
                }

                $output = Invoke-MgaRestMethodPost @invokeParam
                if ($PSCmdlet.ParameterSetName -like 'Default' -and $output) {
                    New-MgaMailMessageObject -RestData $output -FunctionName $MyInvocation.MyCommand
                } elseif ($PSCmdlet.ParameterSetName -like 'DirectReply' -and $PassThru) {
                    Write-PSFMessage -Tag "MessageQuery" -Level Verbose -Message "PassThru specified, query reply message from sentItems folder."
                    Get-MgaMailMessage -FolderName Sentitems -Subject "RE: $($messageItem.Name)" -ResultSize 5
                }
            }
            #endregion send message
        }
    }

    end {
    }
}

function Copy-MgaMailMessage {
    <#
    .SYNOPSIS
        Copy message(s) to a folder
 
    .DESCRIPTION
        Copy message(s) to a folder in Exchange Online using the graph api.
 
    .PARAMETER Message
        Carrier object for Pipeline input. Accepts messages and strings.
 
    .PARAMETER DestinationFolder
        The destination folder where to copy the message to
 
        .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> $mails | Copy-MgaMailMessage -DestinationFolder $destinationFolder
 
        Copys messages in variable $mails to the folder in the variable $destinationFolder.
        also possible:
        PS C:\> Copy-MgaMailMessage -Message $mails -DestinationFolder $destinationFolder
 
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Inbox -ResultSize 1
 
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    .EXAMPLE
        PS C:\> Copy-MgaMailMessage -Id $mails.id -DestinationFolder $destinationFolder
 
        Copys messages into the folder $destinationFolder.
 
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Inbox -ResultSize 1
 
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage -Folder Inbox | Copy-MgaMailMessage -DestinationFolder $destinationFolder
 
        Copys ALL messages from your inbox into the folder $destinationFolder.
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [Alias()]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('InputObject', 'MessageId', 'Id', 'Mail', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(Mandatory = $true, Position = 1)]
        [MSGraph.Exchange.Mail.FolderParameter]
        $DestinationFolder,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        #region checking DestinationFolder and query folder if required
        if ($DestinationFolder.TypeName -like "System.String") {
            $DestinationFolder = Resolve-MailObjectFromString -Object $DestinationFolder -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
            if (-not $DestinationFolder) { throw }
        }
        #endregion checking DestinationFolder and query folder if required

        $bodyHash = @{
            destinationId = ($DestinationFolder.Id | ConvertTo-Json)
        }
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings messages by parameter set $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        # Put parameters (JSON Parts) into a valid JSON-object together
        $bodyJSON = Merge-HashToJSON $bodyHash

        #region copy messages
        foreach ($messageItem in $Message) {
            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            if ($pscmdlet.ShouldProcess("message '$($messageItem)'", "Copy to folder '$($DestinationFolder.Name)'")) {
                Write-PSFMessage -Tag "MessageUpdate" -Level Verbose -Message "Copy message '$($messageItem)' to folder '$($DestinationFolder)'"
                $invokeParam = @{
                    "Field"        = "messages/$($messageItem.Id)/copy"
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                $output = Invoke-MgaRestMethodPost @invokeParam
                if ($PassThru) { New-MgaMailMessageObject -RestData $output }
            }
        }
        #endregion Update messages
    }

}

function Get-MgaMailMessage {
    <#
    .SYNOPSIS
        Retrieves messages from a email folder from Exchange Online using the graph api.
 
    .DESCRIPTION
        Retrieves messages from a email folder from Exchange Online using the graph api.
 
    .PARAMETER InputObject
        Carrier object for Pipeline input
        Accepts messages or folders from other Mga-functions
 
    .PARAMETER FolderName
        The display name of the folder to search.
        Defaults to the inbox.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Subject
        The subject to filter by (Client Side filtering)
 
    .PARAMETER Delta
        Indicates a "delta-query" for incremental changes on mails.
        The switch allows you to query mutliple times against the same user and folder while only getting additional,
        updated or deleted messages.
 
        Please notice, that delta queries needs to be handeled right. See the examples for correct usage.
 
    .PARAMETER ResultSize
        The user to execute this under. Defaults to the user the token belongs to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage
 
        Return emails in the inbox of the user connected to through a token.
 
    .EXAMPLE
        PS C:\> $mails = Get-MgaMailMessage -Delta
 
        Return emails in the inbox of the user connected to through a token and write the output in the variable $mails.
        IMPORTANT, the -Delta switch needs to be specified on the first call, because the outputobject will has to be piped
        into the next delta query.
 
        The content of $mails can be used and processed:
        PS C:\> $mails
 
        So the second Get-MgaMailMessage call has to be:
        PS C:\> $deltaMails = Get-MgaMailMessage -InputObject $mails -Delta
 
        This return only unqueried, updated, or new messages from the previous call and writes the result in the
        variable $deltaMails.
 
        The content of the $deltaMails variable can be used as output and should only overwrites the $mail variable if there is content in $deltaMails:
        PS C:\> if($deltaMails) {
            $mails = $deltaMails
            $deltaMails
        }
 
        From the second call, the procedure can be continued as needed, only updates will be outputted by Get-MgaMailMessage.
 
        .EXAMPLE
        PS C:\> Get-MgaMailFolder -Name "Junkemail" | Get-MgaMailMessage
 
        Return emails from the Junkemail folder of the user connected to through a token.
 
        .EXAMPLE
        PS C:\> Get-MgaMailMessage -FolderName "MyFolder" -Subject "Important*"
 
        Return emails where the subject starts with "Important" from the folder "MyFolder" of the user connected to through a token.
#>
    [CmdletBinding(DefaultParameterSetName = 'ByInputObject')]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(ParameterSetName = 'ByInputObject', Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('Input', 'Id')]
        [MSGraph.Exchange.Mail.MessageOrFolderParameter[]]
        $InputObject,

        [Parameter(ParameterSetName = 'ByFolderName', Position = 0)]
        [Alias('FolderId', 'Folder')]
        [string[]]
        $FolderName,

        [string]
        $User,

        [string]
        $Subject = "*",

        [switch]
        $Delta,

        [Int64]
        $ResultSize = (Get-PSFConfigValue -FullName 'MSGraph.Query.ResultSize' -Fallback 100),

        [MSGraph.Core.AzureAccessToken]
        $Token
    )
    begin {
        $requiredPermission = "Mail.Read"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        $InvokeParams = @()
    }

    process {
        Write-PSFMessage -Level VeryVerbose -Message "Gettings mails by parameter set $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"
        if ($PSCmdlet.ParameterSetName -like "ByInputObject" -and -not $InputObject) {
            Write-PSFMessage -Level Verbose -Message "No InputObject specified. Gettings mail from default folder (inbox)." -Tag "ParameterSetHandling"
            [MSGraph.Exchange.Mail.MessageOrFolderParameter]$InputObject = [MSGraph.Exchange.Mail.WellKnownFolder]::Inbox.ToString()
        }
        if ($PSCmdlet.ParameterSetName -like "ByFolderName") {
            foreach ($folderItem in $FolderName) {
                $folderItem = [MSGraph.Exchange.Mail.MessageOrFolderParameter]$folderItem
                if ($folderItem.Name -and (-not $folderItem.IsWellKnownName)) {
                    [MSGraph.Exchange.Mail.MessageOrFolderParameter]$folderItem = Get-MgaMailFolder -Name $folderItem.Name -User $User -Token $Token
                }
                $InputObject = $InputObject + $folderItem
            }
        }

        foreach ($InputObjectItem in $InputObject) {
            Write-PSFMessage -Level VeryVerbose -Message "Parsing input $($InputObjectItem.TypeName) object '$($InputObjectItem)'"
            switch ($InputObjectItem.TypeName) {
                "MSGraph.Exchange.Mail.Message" {
                    if ($Delta -and ('@odata.deltaLink' -in $InputObjectItem.InputObject.BaseObject.psobject.Properties.Name)) {
                        # if delta message, construct a delta query from mail
                        Write-PSFMessage -Level VeryVerbose -Message "Delta parameter specified and delta message found. Checking on message '$($InputObjectItem)' from the pipeline"
                        $invokeParam = @{
                            "deltaLink"    = $InputObjectItem.InputObject.BaseObject.'@odata.deltaLink'
                            "Token"        = $Token
                            "ResultSize"   = $ResultSize
                            "FunctionName" = $MyInvocation.MyCommand
                        }
                    } else {
                        # if non delta message is parsed in, the message will be queried again (refreshed)
                        # Not really necessary, but works as intend from pipeline usage
                        Write-PSFMessage -Level VeryVerbose -Message "Refresh message '$($InputObjectItem)' from the pipeline"
                        $invokeParam = @{
                            "Field"        = "messages/$($InputObjectItem.Id)"
                            "User"         = $InputObjectItem.InputObject.BaseObject.User
                            "Token"        = $Token
                            "ResultSize"   = $ResultSize
                            "FunctionName" = $MyInvocation.MyCommand
                        }
                        if ($Delta) { $invokeParam.Add("Delta", $true) }
                    }
                    $invokeParams = $invokeParams + $invokeParam
                }

                "MSGraph.Exchange.Mail.Folder" {
                    Write-PSFMessage -Level VeryVerbose -Message "Gettings messages in folder '$($InputObjectItem)' from the pipeline"
                    $invokeParam = @{
                        "Field"        = "mailFolders/$($InputObjectItem.Id)/messages"
                        "User"         = $InputObjectItem.InputObject.User
                        "Token"        = $Token
                        "ResultSize"   = $ResultSize
                        "FunctionName" = $MyInvocation.MyCommand
                    }
                    if ($Delta) { $invokeParam.Add("Delta", $true) }
                    $invokeParams = $invokeParams + $invokeParam
                }

                "System.String" {
                    $invokeParam = @{
                        "User"         = $User
                        "Token"        = $Token
                        "ResultSize"   = $ResultSize
                        "FunctionName" = $MyInvocation.MyCommand
                    }
                    if ($Delta) { $invokeParam.Add("Delta", $true) }

                    $name = if ($InputObjectItem.IsWellKnownName) { $InputObjectItem.Name } else { $InputObjectItem.Id }
                    if ($name.length -eq 152 -or $name.length -eq 136) {
                        # Id is a message
                        Write-PSFMessage -Level VeryVerbose -Message "Gettings messages with Id '$($InputObjectItem)'" -Tag "InputValidation"
                        $invokeParam.Add("Field", "messages/$($name)")
                    } elseif ($name.length -eq 120 -or $name.length -eq 104) {
                        # Id is a folder
                        Write-PSFMessage -Level VeryVerbose -Message "Gettings messages in folder with Id '$($InputObjectItem)'" -Tag "InputValidation"
                        $invokeParam.Add("Field", "mailFolders/$($name)/messages")
                    } elseif ($InputObjectItem.IsWellKnownName -and $name) {
                        # a well known folder is specified by name
                        $invokeParam.Add("Field", "mailFolders/$($name)/messages")
                    } else {
                        # not a valid Id -> should not happen
                        Write-PSFMessage -Level Warning -Message "The specified Id seeams not be a valid Id. Skipping object '$($name)'" -Tag "InputValidation"
                        continue
                    }

                    $invokeParams = $invokeParams + $invokeParam
                    Remove-Variable -Name name -Force -ErrorAction Ignore -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false
                }

                Default { Write-PSFMessage -Level Critical -Message "Failed on type validation. Can not handle $($InputObjectItem.TypeName)" -EnableException $true -Tag "TypeValidation" }
            }
        }
    }

    end {
        $fielList = @()
        $InvokeParamsUniqueList = @()
        Write-PSFMessage -Level Verbose -Message "Checking $( ($InvokeParams | Measure-Object).Count ) objects on unique calls..."
        foreach ($invokeParam in $InvokeParams) {
            if ($invokeParam.Field -and ($invokeParam.Field -notin $fielList)) {
                $InvokeParamsUniqueList = $InvokeParamsUniqueList + $invokeParam
                $fielList = $fielList + $invokeParam.Field
            } elseif ($invokeParam.deltaLink -notin $fielList) {
                $InvokeParamsUniqueList = $InvokeParamsUniqueList + $invokeParam
                $fielList = $fielList + $invokeParam.deltaLink
            }
        }
        Write-PSFMessage -Level Verbose -Message "Invoking $( ($InvokeParamsUniqueList | Measure-Object).Count ) REST calls for gettings messages"

        # run the message query and process the output
        foreach ($invokeParam in $InvokeParamsUniqueList) {
            $data = Invoke-MgaRestMethodGet @invokeParam | Where-Object { $_.subject -like $Subject }
            $output = foreach ($messageOutput in $data) {
                New-MgaMailMessageObject -RestData $messageOutput
            }
        }

        if ($output) {
            $output
        } else {
            Write-PSFMessage -Level Warning -Message "Message not found." -Tag "QueryData"
        }
    }
}

function Move-MgaMailMessage {
    <#
    .SYNOPSIS
        Move message(s) to a folder
 
    .DESCRIPTION
        Move message(s) to a folder in Exchange Online using the graph api.
 
    .PARAMETER Message
        Carrier object for Pipeline input. Accepts messages and strings.
 
    .PARAMETER DestinationFolder
        The destination folder where to move the message to
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> $mails | Move-MgaMailMessage -DestinationFolder $destinationFolder
 
        Moves messages in variable $mails to the folder in the variable $destinationFolder.
        also possible:
        PS C:\> Move-MgaMailMessage -Message $mails -DestinationFolder $destinationFolder
 
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Inbox -ResultSize 1
 
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    .EXAMPLE
        PS C:\> Move-MgaMailMessage -Id $mails.id -DestinationFolder $destinationFolder
 
        Moves messages into the folder $destinationFolder.
 
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Inbox -ResultSize 1
 
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    .EXAMPLE
        PS C:\> Get-MgaMailMessage -Folder Inbox | Move-MgaMailMessage -DestinationFolder $destinationFolder
 
        Moves ALL messages from your inbox into the folder $destinationFolder.
        The variable $destinationFolder can be represent:
        PS C:\> $destinationFolder = Get-MgaMailFolder -Name "Archive"
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [Alias()]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('InputObject', 'MessageId', 'Id', 'Mail', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(Mandatory = $true, Position = 1)]
        [MSGraph.Exchange.Mail.FolderParameter]
        $DestinationFolder,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        #region checking DestinationFolder and query folder if required
        if ($DestinationFolder.TypeName -like "System.String") {
            $DestinationFolder = Resolve-MailObjectFromString -Object $DestinationFolder -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
            if (-not $DestinationFolder) { throw }
        }
        #endregion checking DestinationFolder and query folder if required

        $bodyHash = @{
            destinationId = ($DestinationFolder.Id | ConvertTo-Json)
        }
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings messages by parameter set $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        # Put parameters (JSON Parts) into a valid JSON-object together and output the result
        $bodyJSON = Merge-HashToJson $bodyHash

        #region move message
        foreach ($messageItem in $Message) {
            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            if ($pscmdlet.ShouldProcess("message '$($messageItem)'", "Move to folder '$($DestinationFolder.Name)'")) {
                Write-PSFMessage -Tag "MessageUpdate" -Level Verbose -Message "Move message '$($messageItem)' to folder '$($DestinationFolder)'"
                $invokeParam = @{
                    "Field"        = "messages/$($messageItem.Id)/move"
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                $output = Invoke-MgaRestMethodPost @invokeParam
                if ($PassThru) { New-MgaMailMessageObject -RestData $output }
            }
        }
        #endregion move message
    }

    end {
    }
}

function New-MgaMailMessage {
    <#
    .SYNOPSIS
        Creates a folder in Exchange Online using the graph api.
 
    .DESCRIPTION
        Creates a new folder in Exchange Online using the graph api.
 
    .PARAMETER Folder
        The folder where the new folder should be created in. Do not specify to create
        a folder on the root level.
 
        Possible values are a valid folder Id or a Mga folder object passed in.
        Tab completion is available on this parameter for a list of well known folders.
 
    .PARAMETER Subject
        The subject of the new message.
 
    .PARAMETER Sender
        The account that is actually used to generate the message.
        (Updatable only when sending a message from a shared mailbox or sending a message as a delegate.
        In any case, the value must correspond to the actual mailbox used.)
 
    .PARAMETER From
        The mailbox owner and sender of the message.
        Must correspond to the actual mailbox used.
 
    .PARAMETER ToRecipients
        The To recipients for the message.
 
    .PARAMETER CCRecipients
        The Cc recipients for the message.
 
    .PARAMETER BCCRecipients
        The Bcc recipients for the message.
 
    .PARAMETER ReplyTo
        The email addresses to use when replying.
 
    .PARAMETER Body
        The body of the message.
 
    .PARAMETER Categories
        The categories associated with the message.
 
    .PARAMETER Importance
        The importance of the message.
        The possible values are: Low, Normal, High.
 
    .PARAMETER InferenceClassification
        The classification of the message for the user, based on inferred relevance or importance, or on an explicit override.
        The possible values are: focused or other.
 
    .PARAMETER InternetMessageId
        The message ID in the format specified by RFC2822.
 
    .PARAMETER IsDeliveryReceiptRequested
        Indicates whether a delivery receipt is requested for the message.
 
    .PARAMETER IsReadReceiptRequested
        Indicates whether a read receipt is requested for the message.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information go to:
        https://docs.microsoft.com/en-us/graph/api/user-post-messages?view=graph-rest-1.0
 
    .LINK
 
    .EXAMPLE
        PS C:\> New-MgaMailMessage -ToRecipients 'someone@something.org' -Subject 'A new Mail' -Body 'This is a new mail'
 
        Creates a new message in the drafts folder
 
    .EXAMPLE
        PS C:\> New-MgaMailMessage -Subject 'A new Mail' -Folder 'MyFolder'
 
        Creates a new message in the folder named "MyFolder"
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0)]
        [Alias('Name', 'Title')]
        [string[]]
        $Subject,

        [Parameter(Mandatory = $false, Position = 1, ParameterSetName = 'WithFolder')]
        [Alias('FolderName', 'FolderId')]
        [MSGraph.Exchange.Mail.FolderParameter]
        $Folder,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $Sender,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $From,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [Alias('To', 'Recipients')]
        [string[]]
        $ToRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $CCRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $BCCRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $ReplyTo,

        [String]
        $Body,

        [String[]]
        $Categories,

        [ValidateSet("Low", "Normal", "High")]
        [String]
        $Importance,

        [ValidateSet("focused", "other")]
        [String]
        $InferenceClassification,

        [String]
        $InternetMessageId,

        [bool]
        $IsDeliveryReceiptRequested,

        [bool]
        $IsReadReceiptRequested,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        #region checking input object type and query folder if required
        if ($Folder.TypeName -like "System.String") {
            $Folder = Resolve-MailObjectFromString -Object $Folder -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
            if (-not $Folder) { throw }
        }

        if ($Folder) {
            $User = Resolve-UserInMailObject -Object $Folder -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
        }
        #endregion checking input object type and query message if required
    }

    process {
        Write-PSFMessage -Level Debug -Message "Creating message(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        #region Put parameters (JSON Parts) into a valid "message"-JSON-object together
        $jsonParams = @{}

        $names = "Subject", "Sender", "From", "ToRecipients", "CCRecipients", "BCCRecipients", "ReplyTo", "Body", "Categories", "Importance", "InferenceClassification", "IsDeliveryReceiptRequested", "IsReadReceiptRequested"
        foreach ($name in $names) {
            if (Test-PSFParameterBinding -ParameterName $name) {
                Write-PSFMessage -Level Debug -Message "Add $($name) from parameters to message" -Tag "ParameterParsing"
                $jsonParams.Add($name, (Get-Variable $name -Scope 0).Value)
            }
        }

        $bodyJSON = New-JsonMailObject @jsonParams -FunctionName $MyInvocation.MyCommand
        #endregion Put parameters (JSON Parts) into a valid "message"-JSON-object together

        #region create messages
        if ($pscmdlet.ShouldProcess($Subject, "New")) {
            $msg = "Creating message '$($Subject)'"
            if ($Folder) { $msg = $msg + " in '$($Folder)'" } else { $msg = $msg + " in drafts folder" }
            Write-PSFMessage -Level Verbose -Message $msg -Tag "MessageCreation"

            $invokeParam = @{
                "User"         = $User
                "Body"         = $bodyJSON
                "ContentType"  = "application/json"
                "Token"        = $Token
                "FunctionName" = $MyInvocation.MyCommand
            }
            if ($Folder.Id) {
                $invokeParam.Add("Field", "mailFolders/$($Folder.Id)/messages")
            } else {
                $invokeParam.Add("Field", "messages")
            }

            $output = Invoke-MgaRestMethodPost @invokeParam
            if ($output) {
                New-MgaMailMessageObject -RestData $output -FunctionName $MyInvocation.MyCommand
            }
        }
        #endregion create messages
    }

    end {
    }
}

function Remove-MgaMailMessage {
    <#
    .SYNOPSIS
        Remove message(s) in Exchange Online using the graph api.
 
    .DESCRIPTION
        Remove message(s) in Exchange Online using the graph api.
 
        ATTENTION! The command does what it is name to!
        The message will not be moved to 'deletedObjects', it will be deleted.
 
    .PARAMETER Message
        The message to be removed.
        This can be the id of the message or a message object passed in.
 
    .PARAMETER Force
        If specified the user will not prompted on confirmation.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> Remove-MgaMailMessage -Message $message
 
        Removes message represented by the variable $message.
        This example will purge (the first 100 messages in) the inbox.
        You will be prompted for confirmation.
 
        The variable $message can be represent:
        PS C:\> $message = Get-MgaMailMessage -Folder Inbox
 
    .EXAMPLE
        PS C:\> $message | Remove-MgaMailMessage -Force
 
        Removes message represented by the variable $message.
        This example will purge (the first 100 messages in) the inbox.
        ATTENTION, there will be NO prompt for confirmation!
 
        The variable $mails can be represent:
        PS C:\> $message = Get-MgaMailMessage -Folder Inbox
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('InputObject', 'MessageId', 'Id', 'Mail', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [switch]
        $Force,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings message(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        foreach ($messageItem in $Message) {
            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            if ($Force) { $doAction = $true } else { $doAction = $pscmdlet.ShouldProcess($messageItem, "Remove (ATTENTION! Message will not be moved to 'deletedObjects')") }
            if ($doAction) {
                Write-PSFMessage -Tag "MessageRemove" -Level Verbose -Message "Remove message '$($messageItem)'"
                $invokeParam = @{
                    "Field"        = "messages/$($messageItem.Id)"
                    "User"         = $User
                    "Body"         = ""
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "Force"        = $true
                    "FunctionName" = $MyInvocation.MyCommand
                }
                $null = Invoke-MgaRestMethodDelete @invokeParam
                if ($PassThru) {
                    $messageItem.InputObject
                }
            }
        }
    }

    end {
    }
}

function Send-MgaMailMessage {
    <#
    .SYNOPSIS
        Send message(s) in Exchange Online using the graph api.
 
    .DESCRIPTION
        Send a previously created draft message(s) and save the message in the SendItems folder.
        Alternatively, the command can directly send a message by specifing a recipient, subject, ...
 
    .PARAMETER Message
        Carrier object for Pipeline input.
        This can be the id of the message or a message object passed in.
 
    .PARAMETER Subject
        The subject of the new message.
 
    .PARAMETER Sender
        The account that is actually used to generate the message.
        (Updatable only when sending a message from a shared mailbox or sending a message as a delegate.
        In any case, the value must correspond to the actual mailbox used.)
 
    .PARAMETER From
        The mailbox owner and sender of the message.
        Must correspond to the actual mailbox used.
 
    .PARAMETER ToRecipients
        The To recipients for the message.
 
    .PARAMETER CCRecipients
        The Cc recipients for the message.
 
    .PARAMETER BCCRecipients
        The Bcc recipients for the message.
 
    .PARAMETER ReplyTo
        The email addresses to use when replying.
 
    .PARAMETER Body
        The body of the message.
 
    .PARAMETER Categories
        The categories associated with the message.
 
    .PARAMETER Importance
        The importance of the message.
        The possible values are: Low, Normal, High.
 
    .PARAMETER InferenceClassification
        The classification of the message for the user, based on inferred relevance or importance, or on an explicit override.
        The possible values are: focused or other.
 
    .PARAMETER IsDeliveryReceiptRequested
        Indicates whether a delivery receipt is requested for the message.
 
    .PARAMETER IsReadReceiptRequested
        Indicates whether a read receipt is requested for the message.
 
    .PARAMETER SaveToSentItems
        Indicates whether to save the message in Sent Items.
        Only needed to be specified if the parameter should be $false, default is $true.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/message-send?view=graph-rest-1.0
        https://docs.microsoft.com/en-us/graph/api/user-sendmail?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> $mail | Send-MgaMailMessage
 
        Send message(s) in variable $mail.
        also possible:
        PS C:\> Send-MgaMailMessage -Message $mail
 
        The variable $mail can be represent:
        PS C:\> $mail = New-MgaMailMessage -ToRecipients 'someone@something.org' -Subject 'A new Mail' -Body 'This is a new mail'
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'DirectSend')]
    [Alias()]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true, ParameterSetName = 'ByInputObject')]
        [Alias('InputObject', 'MessageId', 'Id', 'Mail', 'MailId')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [Parameter(ParameterSetName = 'DirectSend', Mandatory = $true)]
        [Alias('Name', 'Title')]
        [string[]]
        $Subject,

        [Parameter(ParameterSetName = 'DirectSend')]
        [String]
        $Body,

        [Parameter(ParameterSetName = 'DirectSend', Mandatory = $true)]
        [Alias('To', 'Recipients')]
        [string[]]
        $ToRecipients,

        [Parameter(ParameterSetName = 'DirectSend')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $CCRecipients,

        [Parameter(ParameterSetName = 'DirectSend')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $Sender,

        [Parameter(ParameterSetName = 'DirectSend')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $From,

        [Parameter(ParameterSetName = 'DirectSend')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $BCCRecipients,

        [Parameter(ParameterSetName = 'DirectSend')]
        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $ReplyTo,

        [Parameter(ParameterSetName = 'DirectSend')]
        [String[]]
        $Categories,

        [Parameter(ParameterSetName = 'DirectSend')]
        [ValidateSet("Low", "Normal", "High")]
        [String]
        $Importance = "Normal",

        [Parameter(ParameterSetName = 'DirectSend')]
        [ValidateSet("focused", "other")]
        [String]
        $InferenceClassification = "other",

        [Parameter(ParameterSetName = 'DirectSend')]
        [bool]
        $IsDeliveryReceiptRequested = $false,

        [Parameter(ParameterSetName = 'DirectSend')]
        [bool]
        $IsReadReceiptRequested = $false,

        [Parameter(ParameterSetName = 'DirectSend')]
        [bool]
        $SaveToSentItems = $true,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.Send"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        Write-PSFMessage -Level Debug -Message "Working on parameter set $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        #region send message
        switch ($PSCmdlet.ParameterSetName) {
            'ByInputObject' {
                foreach ($messageItem in $Message) {
                    #region checking input object type and query message if required
                    if ($messageItem.TypeName -like "System.String") {
                        $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                        if (-not $messageItem) { continue }
                    }

                    $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
                    #endregion checking input object type and query message if required

                    #region send message
                    if ($pscmdlet.ShouldProcess($messageItem, "Send")) {
                        Write-PSFMessage -Tag "MessageSend" -Level Verbose -Message "Send message '$($messageItem)'"
                        $invokeParam = @{
                            "Field"        = "messages/$($messageItem.Id)/send"
                            "User"         = $User
                            "Body"         = ""
                            "ContentType"  = "application/json"
                            "Token"        = $Token
                            "FunctionName" = $MyInvocation.MyCommand
                        }
                        $null = Invoke-MgaRestMethodPost @invokeParam
                        if ($PassThru) { $messageItem.InputObject }
                    }
                    #endregion send message
                }
            }

            'DirectSend' {
                #region Put parameters (JSON Parts) into a valid "message"-JSON-object together
                $jsonParams = @{}

                $names = "Subject", "Sender", "From", "ToRecipients", "CCRecipients", "BCCRecipients", "ReplyTo", "Body", "Categories", "Importance", "InferenceClassification", "IsDeliveryReceiptRequested", "IsReadReceiptRequested"
                foreach ($name in $names) {
                    if (Test-PSFParameterBinding -ParameterName $name) {
                        Write-PSFMessage -Level Debug -Message "Add $($name) from parameters to message" -Tag "ParameterParsing"
                        $jsonParams.Add($name, (Get-Variable $name -Scope 0).Value)
                    }
                }

                $bodyHash = @{
                    "message"         = (New-JsonMailObject @jsonParams -FunctionName $MyInvocation.MyCommand)
                    "saveToSentItems" = ($SaveToSentItems | ConvertTo-Json)
                }

                $bodyJSON = Merge-HashToJson $bodyHash
                #endregion Put parameters (JSON Parts) into a valid "message"-JSON-object together

                #region send message
                if ($pscmdlet.ShouldProcess($Subject, "Send")) {
                    Write-PSFMessage -Tag "MessageSend" -Level Verbose -Message "Send message with subject '$($Subject)' to recipient '$($ToRecipients)'"
                    $invokeParam = @{
                        "Field"        = "sendMail"
                        "User"         = $User
                        "Body"         = $bodyJSON
                        "ContentType"  = "application/json"
                        "Token"        = $Token
                        "FunctionName" = $MyInvocation.MyCommand
                    }
                    $null = Invoke-MgaRestMethodPost @invokeParam
                    if ($PassThru) { $messageItem.InputObject }
                }
                #endregion send message
            }

            Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
        }
        #endregion send message
    }

    end {
    }
}

function Set-MgaMailMessage {
    <#
    .SYNOPSIS
        Set properties on message(s)
 
    .DESCRIPTION
        Set properties on message(s) in Exchange Online using the graph api.
 
    .PARAMETER Message
        Carrier object for Pipeline input. Accepts messages.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER IsRead
        Indicates whether the message has been read.
 
    .PARAMETER Subject
        The subject of the message.
        (Updatable only if isDraft = true.)
 
    .PARAMETER Sender
        The account that is actually used to generate the message.
        (Updatable only if isDraft = true, and when sending a message from a shared mailbox,
        or sending a message as a delegate. In any case, the value must correspond to the actual mailbox used.)
 
    .PARAMETER From
        The mailbox owner and sender of the message.
        Must correspond to the actual mailbox used.
        (Updatable only if isDraft = true.)
 
    .PARAMETER ToRecipients
        The To recipients for the message.
        (Updatable only if isDraft = true.)
 
    .PARAMETER CCRecipients
        The Cc recipients for the message.
        (Updatable only if isDraft = true.)
 
    .PARAMETER BCCRecipients
        The Bcc recipients for the message.
        (Updatable only if isDraft = true.)
 
    .PARAMETER ReplyTo
        The email addresses to use when replying.
        (Updatable only if isDraft = true.)
 
    .PARAMETER Body
        The body of the message.
        (Updatable only if isDraft = true.)
 
    .PARAMETER Categories
        The categories associated with the message.
 
    .PARAMETER Importance
        The importance of the message.
        The possible values are: Low, Normal, High.
 
    .PARAMETER InferenceClassification
        The classification of the message for the user, based on inferred relevance or importance, or on an explicit override.
        The possible values are: focused or other.
 
    .PARAMETER InternetMessageId
        The message ID in the format specified by RFC2822.
        (Updatable only if isDraft = true.)
 
    .PARAMETER IsDeliveryReceiptRequested
        Indicates whether a delivery receipt is requested for the message.
 
    .PARAMETER IsReadReceiptRequested
        Indicates whether a read receipt is requested for the message.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the token to the console
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .EXAMPLE
        PS C:\> $mail | Set-MgaMailMessage -IsRead $false
 
        Set messages represented by variable $mail to status "unread"
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Inbox -ResultSize 1
 
    .EXAMPLE
        PS C:\> $mail | Set-MgaMailMessage -IsRead $false -categories "Red category"
 
        Set status "unread" and category "Red category" to messages represented by variable $mail
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Inbox -ResultSize 1
 
    .EXAMPLE
        PS C:\> $mail | Set-MgaMailMessage -ToRecipients "someone@something.org"
 
        Set reciepent from draft mail represented by variable $mail
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Drafts
 
    .EXAMPLE
        PS C:\> Set-MgaMailMessage -Id $mail.Id -ToRecipients "someone@something.org" -Subject "Something important"
 
        Set reciepent from draft mail represented by variable $mail
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Drafts
 
    .EXAMPLE
        PS C:\> $mail | Set-MgaMailMessage -ToRecipients $null
 
        Clear reciepent from draft mail represented by variable $mail
        The variable $mails can be represent:
        PS C:\> $mails = Get-MgaMailMessage -Folder Drafts
 
 
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'Default')]
    [Alias("Update-MgaMailMessage")]
    [OutputType([MSGraph.Exchange.Mail.Message])]
    param (
        [Parameter(Mandatory = $true, Position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [Alias('InputObject', 'MessageId', 'Id')]
        [MSGraph.Exchange.Mail.MessageParameter[]]
        $Message,

        [ValidateNotNullOrEmpty()]
        [bool]
        $IsRead,

        [string]
        $Subject,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $Sender,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string]
        $From,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [Alias('To', 'Recipients')]
        [string[]]
        $ToRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $CCRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $BCCRecipients,

        [AllowNull()]
        [AllowEmptyCollection()]
        [AllowEmptyString()]
        [string[]]
        $ReplyTo,

        [String]
        $Body,

        [String[]]
        $Categories,

        [ValidateSet("Low", "Normal", "High")]
        [String]
        $Importance,

        [ValidateSet("focused", "other")]
        [String]
        $InferenceClassification,

        [String]
        $InternetMessageId,

        [bool]
        $IsDeliveryReceiptRequested,

        [bool]
        $IsReadReceiptRequested,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "Mail.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        Write-PSFMessage -Level Debug -Message "Gettings folder(s) by parameterset $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        #region Put parameters (JSON Parts) into a valid "message"-JSON-object together
        $jsonParams = @{}
        $boundParameters = @()
        $names = "IsRead", "Subject", "Sender", "From", "ToRecipients", "CCRecipients", "BCCRecipients", "ReplyTo", "Body", "Categories", "Importance", "InferenceClassification", "InternetMessageId", "IsDeliveryReceiptRequested", "IsReadReceiptRequested"
        foreach ($name in $names) {
            if (Test-PSFParameterBinding -ParameterName $name) {
                Write-PSFMessage -Level Debug -Message "Add $($name) from parameters to message" -Tag "ParameterParsing"
                $boundParameters = $boundParameters + $name
                $jsonParams.Add($name, (Get-Variable $name -Scope 0).Value)
            }
        }
        $bodyJSON = New-JsonMailObject @jsonParams -FunctionName $MyInvocation.MyCommand
        #endregion Put parameters (JSON Parts) into a valid "message"-JSON-object together

        #region Update messages
        foreach ($messageItem in $Message) {
            #region checking input object type and query message if required
            if ($messageItem.TypeName -like "System.String") {
                $messageItem = Resolve-MailObjectFromString -Object $messageItem -User $User -Token $Token -NoNameResolving -FunctionName $MyInvocation.MyCommand
                if (-not $messageItem) { continue }
            }

            $User = Resolve-UserInMailObject -Object $messageItem -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
            #endregion checking input object type and query message if required

            if ($pscmdlet.ShouldProcess("message '$($messageItem)'", "Update properties '$([string]::Join("', '", $boundParameters))'")) {
                Write-PSFMessage -Tag "MessageUpdate" -Level Verbose -Message "Update properties '$([string]::Join("', '", $boundParameters))' on message '$($messageItem)'"
                $invokeParam = @{
                    "Field"        = "messages/$($messageItem.Id)"
                    "User"         = $User
                    "Body"         = $bodyJSON
                    "ContentType"  = "application/json"
                    "Token"        = $Token
                    "FunctionName" = $MyInvocation.MyCommand
                }
                $output = Invoke-MgaRestMethodPatch @invokeParam
                if ($output -and $PassThru) { New-MgaMailMessageObject -RestData $output }
            }
        }
        #endregion Update messages
    }

}

function Get-MgaMailboxSetting {
    <#
    .SYNOPSIS
        Get the mailbox settings from Exchange Online using the graph api.
 
    .DESCRIPTION
        Get the mailbox settings from Exchange Online using the graph api.
        This includes settings for automatic replies (notify people automatically
        upon receipt of their email), locale (language and country/region),
        and time zone, and working hours.
 
        You can view all mailbox settings, or get specific settings by
        specifing switch parameters.
 
    .PARAMETER AutomaticReplySetting
        If specified, only the settings for automatic notifications to
        senders of an incoming email are outputted.
 
        Fun fact:
        Here's an interesting historical question - when we say Out of Office,
        why does it sometimes get shortened to ‘OOF’? Shouldn’t it be ‘OOO’?
        https://blogs.technet.microsoft.com/exchange/2004/07/12/why-is-oof-an-oof-and-not-an-ooo/
 
    .PARAMETER LanguageSetting
        If specified, only the information about the locale, including the
        preferred language and country/region are displayed.
 
    .PARAMETER TimeZoneSetting
        If specified, only the timezone settings from the users mailbox are displayed.
 
    .PARAMETER WorkingHoursSetting
        If specified, only the settings for the days of the week and hours in a
        specific time zone that the user works are displayed.
 
    .PARAMETER ArchiveFolderSetting
        If specified, only the archive folder settings from the users mailbox are displayed.
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/user-get-mailboxsettings?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> Get-MgaMailboxSetting
 
        Return all mailbox settings for the user connected to through the registered token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailboxSetting -AutomaticReplySetting
 
        Return only the settings for automatic notifications to senders of an incoming email
        for the user connected to through the registered token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailboxSetting -LanguageSetting
 
        Return only the information about the locale, including the preferred language and
        country/region, for the user connected to through the registered token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailboxSetting -TimeZoneSetting
 
        Return only the timezone settings for the user connected to through the registered token.
 
    .EXAMPLE
        PS C:\> Get-MgaMailboxSetting -WorkingHoursSetting
 
        Return only the settings for the days of the week and hours in a specific time zone
        the user connected to through the registered token works.
 
    .EXAMPLE
        PS C:\> Get-MgaMailboxSetting -ArchiveFolderSetting
 
        Return only the settings for the folder where mails are archived in the user
        connected to through the registered token works.
 
    #>
    [CmdletBinding(ConfirmImpact = 'Low', DefaultParameterSetName = 'AllSettings')]
    param (
        [Parameter(ParameterSetName = 'AutomaticReplySetting')]
        [Alias('AutoReply', 'OutOfOffice', 'OutOfOfficeSetting', 'OOFSettings', 'OOF')]
        [switch]
        $AutomaticReplySetting,

        [Parameter(ParameterSetName = 'LanguageSetting')]
        [Alias('Language')]
        [switch]
        $LanguageSetting,

        [Parameter(ParameterSetName = 'TimeZoneSetting')]
        [Alias('TimeZone')]
        [switch]
        $TimeZoneSetting,

        [Parameter(ParameterSetName = 'WorkingHoursSetting')]
        [Alias('WorkingsHour')]
        [switch]
        $WorkingHoursSetting,

        [Parameter(ParameterSetName = 'ArchiveFolderSetting')]
        [Alias('ArchiveFolder')]
        [switch]
        $ArchiveFolderSetting,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token
    )
    begin {
        $requiredPermission = "MailboxSettings.Read"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand
    }

    process {
        Write-PSFMessage -Level Verbose -Message "Getting mailbox settings for '$(Resolve-UserString -User $User)' by ParameterSet $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"

        #region query data
        $invokeParam = @{
            "Token"        = $Token
            "User"         = $User
            "FunctionName" = $MyInvocation.MyCommand
        }
        switch ($PSCmdlet.ParameterSetName) {
            {$_ -like 'AllSettings' -or $_ -like 'ArchiveFolderSetting'} { $invokeParam.Add('Field', 'mailboxSettings') }
            #'AllSettings' { $invokeParam.Add('Field', 'mailboxSettings') }
            'AutomaticReplySetting' { $invokeParam.Add('Field', 'mailboxSettings/automaticRepliesSetting') }
            'LanguageSetting' { $invokeParam.Add('Field', 'mailboxSettings/language') }
            'TimeZoneSetting' { $invokeParam.Add('Field', 'mailboxSettings/timeZone') }
            'WorkingHoursSetting' { $invokeParam.Add('Field', 'mailboxSettings/workingHours') }
            Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
        }

        $data = Invoke-MgaRestMethodGet @invokeParam
        #endregion query data

        #region output data
        foreach ($output in $data) {
            $mailboxSettingObject = New-MgaMailboxSettingObject -RestData $output -Type $PSCmdlet.ParameterSetName -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
            $mailboxSettingObject
        }
        #endregion output data
    }

    end {
    }
}

function Set-MgaMailboxSetting {
    <#
    .SYNOPSIS
        Set the mailbox settings from Exchange Online using the graph api.
 
    .DESCRIPTION
        set the mailbox settings in Exchange Online using the graph api.
        This includes settings for automatic replies (notify people automatically
        upon receipt of their email), locale (language and country/region),
        and time zone, and working hours.
 
        You can parse in modified settings from Get-MgaMailboxSetting command.
 
    .PARAMETER InputObject
        Carrier object for Pipeline input. Accepts all the different setting objects
        outputted by Get-MgaMailboxSetting.
 
    .PARAMETER AutomaticReply
        If specified, the command will set AutomaticReply settings
 
    .PARAMETER Language
        If specified, the command will set Language settings
 
    .PARAMETER TimeZone
        If specified, the command will set TimeZone settings
 
    .PARAMETER WorkingHours
        If specified, the command will set WorkingHour settings
 
    .PARAMETER User
        The user-account to access. Defaults to the main user connected as.
        Can be any primary email name of any user the connected token has access to.
 
    .PARAMETER Token
        The token representing an established connection to the Microsoft Graph Api.
        Can be created by using New-MgaAccessToken.
        Can be omitted if a connection has been registered using the -Register parameter on New-MgaAccessToken.
 
    .PARAMETER PassThru
        Outputs the mailbox settings to the console.
 
    .PARAMETER Confirm
        If this switch is enabled, you will be prompted for confirmation before executing any operations that change state.
 
    .PARAMETER WhatIf
        If this switch is enabled, no actions are performed but informational messages will be displayed that explain what would happen if the command were to run.
 
    .NOTES
        For addiontional information about Microsoft Graph API go to:
        https://docs.microsoft.com/en-us/graph/api/user-update-mailboxsettings?view=graph-rest-1.0
 
    .EXAMPLE
        PS C:\> Set-MgaMailboxSetting
 
        Return all mailbox settings for the user connected to through the registered token.
 
    .EXAMPLE
        PS C:\> Set-MgaMailboxSetting -AutomaticReply
 
        Set
 
    .EXAMPLE
        PS C:\> Set-MgaMailboxSetting -Language
 
        Set
 
    .EXAMPLE
        PS C:\> Set-MgaMailboxSetting -TimeZone
 
        Set
 
    .EXAMPLE
        PS C:\> Get-MgaMailboxSetting -WorkingHours
 
        Set
    #>
    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'Medium', DefaultParameterSetName = 'InputObject')]
    param (
        [Parameter(ParameterSetName = 'InputObject')]
        [Alias('MailboxSetting', 'ArchiveFolderSetting', 'AutomaticReplySetting', 'LanguageSetting', 'TimeZoneSetting', 'WorkingHoursSetting', 'Setting', 'SettingObject')]
        [MSGraph.Exchange.MailboxSetting.MailboxSettingParameter]
        $InputObject,

        [Parameter(ParameterSetName = 'AutomaticReplySetting')]
        [Alias()]
        [switch]
        $AutomaticReply,

        [Parameter(ParameterSetName = 'LanguageSetting')]
        [Alias()]
        [switch]
        $Language,

        [Parameter(ParameterSetName = 'TimeZoneSetting')]
        [Alias()]
        [switch]
        $TimeZone,

        [Parameter(ParameterSetName = 'WorkingHoursSetting')]
        [Alias()]
        [switch]
        $WorkingHours,

        [string]
        $User,

        [MSGraph.Core.AzureAccessToken]
        $Token,

        [switch]
        $PassThru
    )
    begin {
        $requiredPermission = "MailboxSettings.ReadWrite"
        $Token = Invoke-TokenScopeValidation -Token $Token -Scope $requiredPermission -FunctionName $MyInvocation.MyCommand

        $invokeParam = @{
            "Field"        = "mailboxSettings"
            "Token"        = $Token
            "User"         = $User
            "FunctionName" = $MyInvocation.MyCommand
        }
    }

    process {
        #region prepare rest data
        switch ($PSCmdlet.ParameterSetName) {
            'InputObject' {
                Write-PSFMessage -Level Verbose -Message "Working on mailbox settings '$($InputObject)' for '$(Resolve-UserString -User $User)' by ParameterSet $($PSCmdlet.ParameterSetName)" -Tag "ParameterSetHandling"
                $User = Resolve-UserInMailObject -Object $InputObject -User $User -ShowWarning -FunctionName $MyInvocation.MyCommand
                $bodyJSON = New-JsonMailboxSettingObject -SettingObject $InputObject -User $User -FunctionName $MyInvocation.MyCommand
                $invokeParam.Add('Body', $bodyJSON)
            }

            Default { Stop-PSFFunction -Message "Unhandled parameter set. ($($PSCmdlet.ParameterSetName)) Developer mistake." -EnableException $true -Category MetadataError -FunctionName $MyInvocation.MyCommand }
        }
        #endregion prepare rest data

        if ($pscmdlet.ShouldProcess("mailbox of '$(Resolve-UserString -User $User -ContextData)'", "Set $InputObject")) {
            # set data
            $data = Invoke-MgaRestMethodPatch @invokeParam

            #region output data
            if($PassThru) {
                foreach ($output in $data) {
                    $mailboxSettingObject = New-MgaMailboxSettingObject -RestData $output -Type $InputObject.Name -User $User -Token $Token -FunctionName $MyInvocation.MyCommand
                    $mailboxSettingObject
                }
            }
            #endregion output data
        }
    }

    end {
    }
}

<#
This is the configuration file for default values in the module
 
By default, it is enough to have a single one of them,
however if you have enough configuration settings to justify having multiple copies of it,
feel totally free to split them into multiple files.
#>

# module creation defaults - used by module creation framework (PSModuleDevelopment)
Set-PSFConfig -Module 'MSGraph' -Name 'Import.DoDotSource' -Value $false -Initialize -Validation 'bool' -Description "Whether the module files should be dotsourced on import. By default, the files of this module are read as string value and invoked, which is faster but worse on debugging."
Set-PSFConfig -Module 'MSGraph' -Name 'Import.IndividualFiles' -Value $false -Initialize -Validation 'bool' -Description "Whether the module files should be imported individually. During the module build, all module code is compiled into few files, which are imported instead by default. Loading the compiled versions is faster, using the individual files is easier for debugging and testing out adjustments."

#region Settings inside the module
# Azure Active Directory App
Set-PSFConfig -Module 'MSGraph' -Name 'Tenant.Application.ClientID' -Value "bbc256f6-f642-44a4-add5-7f665e8b90cb" -Initialize -Validation 'string' -Description "Well known ClientID from registered Application in Azure tenant"
Set-PSFConfig -Module 'MSGraph' -Name 'Tenant.Application.RedirectUrl' -Value "https://login.microsoftonline.com/common/oauth2/nativeclient" -Initialize -Validation 'string' -Description "Redirection URL specified in MS Azure Application portal for the registered application"
Set-PSFConfig -Module 'MSGraph' -Name 'Tenant.Application.DefaultPermission' -Value @("Mail.ReadWrite.Shared") -Initialize -Validation 'string' -Description "The default permission to consent when getting a token"
Set-PSFConfig -Module 'MSGraph' -Name 'Tenant.ApiConnection' -Value "https://graph.microsoft.com" -Initialize -Validation 'string' -Description "The App ID URI of the target web API (secured resource). To find the App ID URI, in the Azure Portal, click Azure Active Directory, click Application registrations, open the application's Settings page, then click Properties."
Set-PSFConfig -Module 'MSGraph' -Name 'Tenant.ApiVersion' -Value "v1.0" -Initialize -Validation 'string' -Description "Specifies the API version used to query objects in Microsoft Graph. For more information goto https://docs.microsoft.com/en-us/graph/versioning-and-support"
Set-PSFConfig -Module 'MSGraph' -Name 'Tenant.Authentiation.IdentityPlatformVersion' -Value "2.0" -Initialize -Validation 'string' -Description "Specifies the endpoint version of the logon platform (Microsoft identity platform) where to connect for logon. For more information goto https://docs.microsoft.com/en-us/azure/active-directory/develop/about-microsoft-identity-platform"
Set-PSFConfig -Module 'MSGraph' -Name 'Tenant.Authentiation.Endpoint' -Value "https://login.microsoftonline.com" -Initialize -Validation 'string' -Description "The URI for authentication and query tokens (access and refresh)"

# web client
Set-PSFConfig -Module 'MSGraph' -Name 'WebClient.UserAgentName' -Value "PowerShellModule.MSGraph.RestClient" -Initialize -Validation 'string' -Description "Name of the user agent in the web client used by module"
Set-PSFConfig -Module 'MSGraph' -Name 'WebClient.UserAgentVersion' -Value "1.1" -Initialize -Validation 'string' -Description "Version for the user agent in the web client used by module"

# command behavior
Set-PSFConfig -Module 'MSGraph' -Name 'Query.ResultSize' -Value 100 -Initialize -Validation integer -Description "Limit of amount of records returned by a function. Use 0 for unlimited."
Set-PSFConfig -Module 'MSGraph' -Name 'Hierarchy.Path.Separator' -Value "\" -Initialize -Validation string -Description "the character used to process hierarchical names (like FullName property on folders) in MSGraph module."

#endregion Settings inside the module

# defining module wide variables

New-Variable -Name msgraph_Token -Scope Script -Visibility Public -Description "Variable for registered token. This is for convinience use with the commands in MSGraph module" -Force


<#
# Example:
Register-PSFTeppScriptblock -Name "MSGraph.alcohol" -ScriptBlock { 'Beer','Mead','Whiskey','Wine','Vodka','Rum (3y)', 'Rum (5y)', 'Rum (7y)' }
#>


Register-PSFTeppScriptblock -Name "MSGraph.Exchange.Mail.WellKnowFolders" -ScriptBlock { [enum]::GetNames([MSGraph.Exchange.Mail.WellKnownFolder]) | ForEach-Object { (Get-Culture).TextInfo.ToTitleCase( $_ ) } }

Register-PSFTeppScriptblock -Name "MSGraph.Exchange.Category.Colors" -ScriptBlock { [enum]::GetNames([MSGraph.Exchange.Category.ColorName]) }

Register-PSFTeppScriptblock -Name "MSGraph.Core.Permission.Consent.User" -ScriptBlock { @(
    'email',
    'openid',
    'profile',
    'offline_access',
    'Bookings.Manage.All',
    'Bookings.Read.All',
    'Bookings.ReadWrite.All',
    'BookingsAppointment.ReadWrite.All',
    'Calendars.Read',
    'Calendars.Read.Shared',
    'Calendars.ReadWrite',
    'Calendars.ReadWrite.Shared',
    'Contacts.Read',
    'Contacts.Read.Shared',
    'Contacts.ReadWrite',
    'Contacts.ReadWrite.Shared',
    'Device.Command',
    'Device.Read',
    'EAS.AccessAsUser.All',
    'Files.Read',
    'Files.Read.All',
    'Files.Read.Selected',
    'Files.ReadWrite',
    'Files.ReadWrite.All',
    'Files.ReadWrite.AppFolder',
    'Files.ReadWrite.Selected',
    'Financials.ReadWrite.All',
    'Mail.Read',
    'Mail.Read.Shared',
    'Mail.ReadWrite',
    'Mail.ReadWrite.Shared',
    'Mail.Send',
    'Mail.Send.Shared',
    'MailboxSettings.Read',
    'MailboxSettings.ReadWrite',
    'Notes.Create',
    'Notes.Read',
    'Notes.Read.All',
    'Notes.ReadWrite',
    'Notes.ReadWrite.All',
    'Notes.ReadWrite.CreatedByApp',
    'Notifications.ReadWrite.CreatedByApp',
    'People.Read',
    'Sites.Manage.All',
    'Sites.Read.All',
    'Sites.ReadWrite.All',
    'Tasks.Read',
    'Tasks.Read.Shared',
    'Tasks.ReadWrite',
    'Tasks.ReadWrite.Shared',
    'User.Read',
    'User.ReadBasic.All',
    'User.ReadWrite',
    'UserActivity.ReadWrite.CreatedByApp',
    'UserTimelineActivity.Write.CreatedByApp'
) }

<#
# Example:
Register-PSFTeppArgumentCompleter -Command Get-Alcohol -Parameter Type -Name MSGraph.alcohol
#>

Register-PSFTeppArgumentCompleter -Command New-MgaAccessToken -Parameter "Permission" -Name "MSGraph.Core.Permission.Consent.User"

Register-PSFTeppArgumentCompleter -Command Get-MgaMailFolder -Parameter "Name" -Name "MSGraph.Exchange.Mail.WellKnowFolders"
Register-PSFTeppArgumentCompleter -Command Move-MgaMailFolder -Parameter "DestinationFolder" -Name "MSGraph.Exchange.Mail.WellKnowFolders"
Register-PSFTeppArgumentCompleter -Command New-MgaMailFolder -Parameter "ParentFolder" -Name "MSGraph.Exchange.Mail.WellKnowFolders"
Register-PSFTeppArgumentCompleter -Command Remove-MgaMailFolder -Parameter "Folder" -Name "MSGraph.Exchange.Mail.WellKnowFolders"

Register-PSFTeppArgumentCompleter -Command Get-MgaMailMessage -Parameter "FolderName" -Name "MSGraph.Exchange.Mail.WellKnowFolders"
Register-PSFTeppArgumentCompleter -Command Move-MgaMailMessage -Parameter "DestinationFolder" -Name "MSGraph.Exchange.Mail.WellKnowFolders"

Register-PSFTeppArgumentCompleter -Command Get-MgaExchCategory -Parameter "Color" -Name "MSGraph.Exchange.Category.Colors"
Register-PSFTeppArgumentCompleter -Command New-MgaExchCategory -Parameter "Color" -Name "MSGraph.Exchange.Category.Colors"
Register-PSFTeppArgumentCompleter -Command Set-MgaExchCategory -Parameter "Color" -Name "MSGraph.Exchange.Category.Colors"


New-PSFLicense -Product 'MSGraph' -Manufacturer 'Friedrich Weinmann, Andreas Bellstedt' -ProductVersion $ModuleVersion -ProductType Module -Name MIT -Version "1.0.0.0" -Date (Get-Date "2018-08-28") -Text @"
Copyright (c) 2018 Friedrich Weinmann, Andreas Bellstedt
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
"@
#endregion Load compiled code