MsGraphCheckUnprocessedMailsCron - Checking Unprocessed Emails
The MsGraphCheckUnprocessedMailsCron cron is a monitoring (check) job. It verifies that emails processed through the Microsoft Graph integration actually became cases in TAS. If it finds an email for which no case was created, it notifies the designated administrators by email. It acts as a safeguard against silent failures in mail processing.
MsGraphCreateProcessesFromMailCron). This job only checks that everything that should have been processed was actually processed.What it is for (in a nutshell)
In simplified terms, incoming mail processing in TAS works like this:
- An email arrives in the monitored mailbox.
- TAS processes it according to the settings and creates a case from it.
- The processed email is moved to the "out" folder (handled emails).
The MsGraphCheckUnprocessedMailsCron cron then looks into the "out" folder and verifies that a matching case exists for every email in it. If an email is in the folder but no case exists for it, there is a problem (a processing error, incorrect mapping settings, etc.), and the cron sends a report.
How the cron works
- Loads the configuration from the crons table in the database.
- Connects to the mailbox via Microsoft Graph and downloads emails from the "out" folder for the specified period.
- Extracts values from the emails according to the configured mapping (sender, subject, body…).
- Compares these values against the variables of existing cases of the given template.
- Finds unmatched emails, i.e. emails for which no case exists.
- Sends an HTML report to the specified addresses if it found any unmatched emails.
- Logs the run to the application logs.
Property | Value |
Schedule | Every hour ( |
Timeout | 600 seconds (10 minutes) per run |
Processing | Each mailbox separately. An error in one does not block the others. |
Default state | Inactive. It must be enabled manually in the administration. |
Configuration
The configuration is stored as JSON in the cron parameters in the administration. The items array can contain multiple mailboxes, and each one is processed independently.
Example of a real configuration (sensitive data is truncated):
{
"items": [
{
"numberOfDays": "10",
"reportAddresses": [
"frantisek.brych@neit.group"
],
"auth": {
"emailAddress": "vytezovana_adresa@teamassistant.app",
"tenantId": "103bsdf-a80a-...",
"clientId": "sdfsdsdfds-140249...",
"clientSecret": "Msdfsdfsdfsdf-...",
"type": "secret"
},
"folders": {
"out": {
"id": "AAMkAD...AAA="
}
},
"process": {
"user_id": "1",
"tproc_id": "1786",
"header_id": "2043"
},
"mapping": {
"_mail": {
"value": "mail",
"isConstant": true
},
"mailBody": "body.content",
"mailSubject": {
"value": "subject",
"option": "optional"
}
}
}
]
}clientSecret is the application password. Never share it, send it by email or commit it to a version control system. Always redact it in reports and when reporting errors.Parameters of a single mailbox
Parameter | Required | Description |
| Yes | How many days back emails and cases are checked. For example, |
| Yes | List of email addresses that receive the report on unmatched emails. At least one is required. With multiple addresses, the first one goes in the "To" field and the others are sent as blind copies (BCC). |
| Yes | Email address of the monitored mailbox in Microsoft 365 (the address emails are extracted from). |
| Yes | Tenant ID in Azure AD (Microsoft Entra). You can find it in Azure Portal → Microsoft Entra ID → Properties. |
| Yes | Application (client) ID of the registered application in Azure Portal. |
| Yes (for | Value of the client secret from the app registration. Sensitive data. |
| Yes | Sign-in method. For automated cron runs, use |
| Yes | ID of the "out" folder in Microsoft Graph that processed emails are moved to. This is the folder the cron checks. |
| Yes | ID of the TAS user under whom cases are created. |
| Yes | Process template ID. The cron matches emails against cases created from this template. |
| Yes | Process header (group) ID. It further narrows down which cases are included in the comparison. |
| Yes | Specifies which values are extracted from the email and which case variables they are compared against. See below. |
numberOfDays, tproc_id, header_id, user_id) can also be written in the configuration as quoted text (e.g. "10", "1786"), as shown in the test example. TAS reads them correctly.Mapping email fields
The mapping object says: "take this value from the email and compare it against the case variable with the same name". The key on the left is the case variable name, and the value on the right specifies where in the email the data comes from.
Simple mapping: variable name → email field:
"mailBody": "body.content"
The content of the email body is put into the mailBody variable.
Extended mapping: with additional options:
"mailSubject": {
"value": "subject",
"option": "optional"
}The email subject is put into the mailSubject variable. option: "optional" means the field is optional (it may be missing).
Constant: a fixed value for every email:
"_mail": {
"value": "mail",
"isConstant": true
}With isConstant: true, the _mail variable does not receive a value from the email but the fixed string "mail". It is used to distinguish or label records.
Most common email fields to map:
from: sender address,subject: subject,body.content: body text,toRecipients/ccRecipients: recipients / copy (CC) recipients.
Prerequisites on the Azure side
The cron reads mail through the Microsoft Graph API. Before you enable it, the following must be in place:
- App registration in Azure Portal: an App Registration with the
Mail.Readpermission (orMail.ReadWrite), of type Application, not Delegated. - Client secret: generated if you use
type: "secret". Write down the Application ID and Tenant ID. - Mailbox access: the service application must have permission to access the monitored mailbox (typically granted through the Exchange Admin Center).
- Network: the TAS server must have outbound HTTPS access to
https://graph.microsoft.com(TCP 443).
Enabling and monitoring
After deployment, the cron is inactive. To enable it, go to Administration → Crons, select "Check unprocessed MS Graph mails" and activate it.
On the same screen you can monitor:
- Status: Active / Inactive,
- Last run: time of the last run,
- Next run: scheduled time,
- Last error: "Y" indicates an error in the last run, "N" indicates success.
Each run is also written to the application logs. Examples:
Successful run (no action needed)
INFO: No unprocessed MS Graph mails found
mailCount: 125
processCount: 125
Unmatched emails found (a report is sent)
WARNING: Found 3 unprocessed MS Graph mails
failedMails: [
{ subject: "Objednávka #12345" },
{ subject: "Faktura-2024-06" }
]
Troubleshooting common problems
Symptom | Likely cause and solution |
"No report addresses defined…" | The |
Sign-in error / "Unknown credentials type" | Incorrect |
The report lists all emails as unprocessed | Most often caused by an incorrect |
"Folder Not Found" / invalid | The folder ID is wrong or the folder was deleted. You can find the correct ID using Microsoft Graph Explorer: |
Timeout (run longer than 10 minutes) | The mailbox contains too many emails or the network is slow. Reduce |
The cron does not run / log entries are missing | The cron is most likely inactive. Check its status in the administration and verify network access to |
Updated
by Frantisek Brych