Unable to create New-SensorParameters -RawType paessler.microsoft365.mailbox_sensor

[MikeSouthwell]

What's going on?

Hi Lordmilko,

Can you please assist me in creating this sensor type.

I want to do this using raw properties, rather than just cloning an existing sensor created in the UI.

Currently I am trying this command:

$params = $currentDevice | New-SensorParameters -RawType paessler.microsoft365.mailbox_sensor
$newSensor = $params | Add-Sensor

But I'm getting this error:

New-SensorParameters : Failed to process request for sensor type 'paessler.microsoft365.mailbox_sensor': sensor query target parameters are required, however none were specified. Please retry the request specifying the parameters
'paessler-microsoft365-mailbox_premeta_section-mailbox_premeta_group-shared_user_'.

What parameters does it need?

I have also tried doing this a a raw sensor using the following:

$params = @{
"paessler-microsoft365-mailbox_premeta_section-mailbox_premeta_group-shared_user_" = "test@domain.com"
}
$newSensor = $currentDevice | New-SensorParameters -RawType paessler.microsoft365.mailbox_sensor -QueryParameters $params

$createdSensor = $newSensor | Add-Sensor

But I'm getting this error:

New-SensorParameters : An exception occurred while trying to resolve sensor targets: The authorization expired. You can renew the authorization in the sensor settings. Specified sensor type may not be valid on this device, or sensor query
target parameters may be incorrect. Check the Device 'Host' is still valid or try adding sensor with the PRTG UI.

However, we didn't setup our existing sensors in the UI with a shared user mailbox, we used "Credentials for Microsoft 365" on the parent group for the device we are creating the sensor on. We specified the tenant ID, client ID and client secret and that is inherited by the device.

Due Dilligance

• It wasn't covered by the wiki, I swear!
• I have tried doing some basic research on this issue but haven't been able to come up with anything. Please help!

[lordmilko]

Hi @MikeSouthwell,

When you do

C:\> $params = $currentDevice | New-SensorParameters -RawType paessler.microsoft365.mailbox_sensor

you get the error

New-SensorParameters : Failed to process request for sensor type 'paessler.microsoft365.mailbox_sensor': sensor query
target parameters are required, however none were specified. Please retry the request specifying the parameters
'paessler-microsoft365-mailbox_premeta_section-mailbox_premeta_group-shared_user_'.

because, as the error suggests, you have not specified any sensor query targets. These are described on the wiki. You are specifying sensor query parameters which are related but different

If you were to try and create a new Microsoft 365 Mailbox sensor using the PRTG UI, my expectation is it would give you a prompt asking you which user you want to use. The value that you then enter for that gets stored in the 'paessler-microsoft365-mailbox_premeta_section-mailbox_premeta_group-shared_user_' query parameter. So ostensibly, you need to do

C:\> $params = $currentDevice | New-SensorParameters -RawType paessler.microsoft365.mailbox_sensor -qt something

where something is whatever the normal value is that you should put here. Typically, when a sensor supports sensor query targets, it will list what all of the various options are. Thus, if you do

(get-sensortype snmplibrary).querytargets

you will see all the allowed query targets for a SNMP Library sensor. When you specify a query target to New-SensorParameters, PrtgAPI looks up the value that you specified against this list, and if the sensor type does not support query targets, or you specified a bad value, it will tell you.

It seems like the Microsoft 365 Mailbox sensor behaves very differently: it seems to support dynamic query targets. When I tried to create a sensor of this type in the PRTG UI, I got a popup trying to redirect me to a page to authorize PRTG to talk to Office 365. I'm not sure if you would get a popup like this every time once PRTG is already authorized.

Ultimately, it seems like dynamic sensor query targets (which is what we effectively have here with the Microsoft 365 Mailbox sensor type) are not supported by PrtgAPI. You can potentially get it going by creating a set of custom parameters however this would effectively require you to reverse engineer the final payload that gets sent to PRTG when you create the sensor. To do this

1. Assuming you're using Chrome, open the Chrome Debug Tools with Ctrl+Shift+J
2. Go to the Network tab
3. Add a sensor of this kind normally using the PRTG UI
4. Inspect the parameters that were specified to addsensor5.htm

Using this you can potentially craft a set of custom parameters that include all of the values that are required to create this type of sensor. Dynamic Sensor parameters try and prefill all of the required parameters for you, but we are being blocked from doing that in this case

[MikeSouthwell]

I've combed through the output in dev tools when creating a sensor in the UI and tried to do this with the PRTG API using the code below, but I get this error:

"Invoke-WebRequest : 24.3.98.1210 Class TOctpaessler.microsoft365.mailbox not found"

PowerShell Code:

$prtgApiParams = @{
    'id'                               = $deviceId
    'type'                             = "paessler.microsoft365.mailbox"
    'name'                             = "M365MailboxTestSensor"
    'tags_'                            = "microsoft365,microsoft365sensor,mailsensor"
    'priority_'                        = 3
    'writeresult_'                     = "DiscardResult"
    'username'                         = $user
    'passhash'                         = $passhash
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_subject_' = "contains_any"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_subject_string_' = "Test String"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_from_' = "equals"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_from_string_' = "test@domain.com"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_body_' = "off"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_body_string_' = "Successful, Fixed"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_age_' = "enabled"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_max_age_' = "1560"
}

# The base URL for the PRTG API
$prtgBaseUrl = "$prtgServer/api/addsensor.htm"

# Combine the base URL with the parameters
$queryString = ($prtgApiParams.Keys | ForEach-Object { "$_=$($prtgApiParams.$_)" }) -join '&'

$prtgRequest = $prtgBaseUrl + "?" + $queryString

Invoke-WebRequest -Uri $prtgRequest

[MikeSouthwell]

If I try using your PRTG API I get the following error:

"Add-Sensor : Failed to add sensor for sensor type 'paessler.microsoft365.mailbox': type was not valid or you do not have sufficient permissions on the specified object."

$prtgApiParams = @{
    'id'                               = $deviceId
    'sensortype'                             = "paessler.microsoft365.mailbox"
    'name_'                             = "M365MailboxTestSensor"
    'tags_'                            = "microsoft365,microsoft365sensor,mailsensor"
    'priority_'                        = 3
    'writeresult_'                     = "DiscardResult"
    'username'                         = $user
    'passhash'                         = $passhash
    'paessler-microsoft365-mailbox_premeta_section-mailbox_premeta_group-shared_user_' = ""
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_subject_' = "contains_any"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_subject_string_' = "Test String"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_from_' = "equals"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_from_string_' = "test@domain.com"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_body_' = "off"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_body_string_' = "Successful, Fixed"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_age_' = "enabled"
    'paessler-microsoft365-mailbox_section-mailbox_group-filter_max_age_' = "1560"
}

$params = New-SensorParameters $prtgApiParams
Get-Device -Id $deviceId | Add-Sensor $params

I've also tried this with the sensortype of ""paessler.microsoft365.mailbox_sensor" and ""paessler.microsoft365.mailbox_sensor.65" and neither of them worked either.

[lordmilko]

Hi @MikeSouthwell,

It seems like it may end up being quite difficult trying to get this going. My only recommendation would be to use Fiddler Classic to intercept the request that PRTG makes and PrtgAPI makes, potentially try and automatically replay the requests that Fiddler intercepted from PRTG to see if they work a second time, and ultimately play spot the difference to figure out why it doesn't work when you do it programmatically. This is all very unsupported territory, so unless you need to mass add hundreds of different mailbo sensors, it may be easier to just add the mailbox sensors manually

[MikeSouthwell]

This is as close as I've gotten, based on the output of my existing sensor using:

Get-Sensor -Id $sensorId | Get-ObjectProperty -Raw

function Connect-PRTG-API {
	
	param (
		    [Parameter(Mandatory = $true)]
		    $PRTGPassHash,
		    [Parameter(Mandatory = $true)]
		    $PRTGUsername
	)
	
	# Create a PSCredential Object using the "User" and "Password" parameters that you passed to the job
	$SecurePassword = $PRTGPassHash | ConvertTo-SecureString -AsPlainText -Force
	$PRTGCred = New-Object System.Management.Automation.PSCredential -ArgumentList $PRTGUsername, $SecurePassword

	if ( Get-Package -Name PrtgAPI) {
		#PRTGAPI already imported. Do nothing.
	} 
	else {
		Install-Package PrtgAPI -Source PSGallery -Force
	}

	Connect-PrtgServer -server monitor.aod-ops.com -Credential $PRTGCred -PassHash -Force
}

Connect-PRTG-API -PRTGPassHash "" -PRTGUsername ""

function Get-AppOnlyToken {
    param(
        [Parameter(Mandatory=$true)][string]$ClientId,
        [Parameter(Mandatory=$true)][string]$ClientSecret,
        [Parameter(Mandatory=$true)][string]$TenantId
    )
    
    $tokenEndpoint = "https://login.microsoftonline.com/$TenantId/oauth2/v2.0/token"
    
    $body = @{
        grant_type = "client_credentials"
        client_id = $ClientId
        client_secret = $ClientSecret
        scope = "https://graph.microsoft.com/.default"
    }
    
    try {
        $response = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body -ContentType "application/x-www-form-urlencoded"
        
        Write-Host "App-only token obtained successfully!" -ForegroundColor Green
        Write-Host "Access Token: $($response.access_token)" -ForegroundColor Cyan
        Write-Host "Expires In: $($response.expires_in) seconds" -ForegroundColor Yellow
        
        return @{
            AccessToken = $response.access_token
            ExpiresIn = $response.expires_in
            ExpiresAt = (Get-Date).AddSeconds($response.expires_in)
        }
    }
    catch {
        Write-Error "App-only authentication failed: $($_.Exception.Message)"
        return $null
    }
}

$tokens = Get-AppOnlyToken -ClientId "" -ClientSecret "" -TenantId ""

if ($tokens -and $tokens.AccessToken) {

    # Create the sensor parameters
    $table = @{
    "name_" = "Test"
    "sensortype" = "paessler.microsoft365.mailbox_sensor"
    "tags_" = "mailsensor microsoft365 microsoft365sensor"
    "paessler-microsoft365-mailbox_premeta_section-mailbox_premeta_group-shared_user_" = ""
    "paessler-microsoft365-mailbox_metascan_section-mailbox_metascan_group-folder_id" = "AQMk......AAA=="
    "metascan" = "momo.paessler.microsoft365.mailbox_sensor.mailbox_metascan" 
    "paessler-microsoft365-oauth_section-oauth_group-refreshtoken" = "$($tokens.AccessToken)"
    "paessler-microsoft365-oauth_section-oauth_group-redirecturi" = ""
    "paessler-microsoft365-oauth_section-oauth_group-scope" = ""
    }

    $paramsTest = New-SensorParameters $table
    
    # Display the parameters
    Write-Host "Sensor Parameters:" -ForegroundColor Green
    $paramsTest | Format-List
    
    # Create the sensor
    try {
        $newSensor = $currentDevice | Add-Sensor $paramsTest
        Write-Host "Sensor created successfully!" -ForegroundColor Green
        Write-Host "Sensor ID: $($newSensor.Id)" -ForegroundColor Cyan
        Write-Host "Sensor Name: $($newSensor.Name)" -ForegroundColor Cyan
        Write-Host "Access Token: $($tokens.AccessToken)"
    }
    catch {
        Write-Error "Failed to create sensor: $($_.Exception.Message)"
    }
}
else {
    Write-Error "Failed to obtain access token"
}

This is the output:

App-only token obtained successfully!
Access Token: ***
Expires In: 3599 seconds
Sensor Parameters:

paessler-microsoft365-mailbox_metascan_section-mailbox_metascan_group-folder_id : AQMk......AAA==
paessler-microsoft365-oauth_section-oauth_group-scope :
paessler-microsoft365-oauth_section-oauth_group-accesstoken : ***
paessler-microsoft365-mailbox_premeta_section-mailbox_premeta_group-shared_user_ :
paessler-microsoft365-oauth_section-oauth_group-refreshtoken :
paessler-microsoft365-oauth_section-oauth_group-redirecturi :
metascan : momo.paessler.microsoft365.mailbox_sensor.mailbox_metascan
QueryParameters :
SensorType : paessler.microsoft365.mailbox_sensor
Priority : Three
InheritTriggers : True
InheritInterval : True
Interval : 00:01:00
IntervalErrorMode : OneWarningThenDown
DynamicType : False
Name : Test
Tags : {mailsensor, microsoft365, microsoft365sensor}
Cookie : False

Add-Sensor : PRTG was unable to complete the request. The server responded with the following error: Nothing was selected, no sensors could be created.

[lordmilko]

Impressive!

When you compare the requests that PRTG emits in Fiddler Classic, do they now match the payload that you're sending?

Some other things to consider (adapted from a table listed in PrtgAPI's source):

There are multiple API requests involved in establishing a session with PRTG to be able to create a sensor

Step	Required	Page	Description
1	SensorType, Device ID	addsensor2.htm	Request a tmpid for creating a sensor
2a		addsensor3.htm	Response containing the tmpid requested in step 1
2b	Device ID, TmpID, Query Target Params	addsensor3.htm	Response requesting Query Target Parameters
3	tmpid, Cookie	getaddsensorprogress.htm	Wait for sensor targets to be retrieved
4	tmpid, Cookie	addsensor4.htm	Scrape the contents of the new sensor creation page

After all this, addsensor5.htm is actually called. Even though you're trying to create a sensor using raw parameters, PrtgAPI will still perform the required parts of this handshake for you.

However, when it comes to what you're doing, something to consideris

• Might there bs some differences in these earlier requests that need to be taken into consideration in order for this special sensor type to work?
• is there anything else outside of the raw body that also needs to be included?

Some of the API endpoints listed above require a cookie retrieved from PRTG to be included in the request. It's possible that with this sensor, there may be an additional cookie from Microsoft that also needs to be included? Look on the main overview tab for the request in Fiddler Classic and it will provide a full list of all of the other minor aspects like headers and cookies that you may also need to consider.

If it is an issue of missing headers and/or cookies, its possible you may need to take over this entire handshake process yourself, which will increase the complexity of this