MS Graph (email)

MS Graph connects TAS to Microsoft 365 mailboxes: it can create cases from incoming mail and send mail from TAS via Graph (or via SMTP with OAuth2). An administrator sets it up in Crons and in Configuration; it requires an app registration in Microsoft Entra ID. EWS (the older connection to Exchange Web Services) is no longer available in TAS – MS Graph is the only supported option.

From version 5.21
Cases from incoming mail are created by the Email processing cron, using a connection from Administration → Email Processing. The crons described in the section Creating cases from incoming mail do not exist in version 5.21. How to migrate their settings is described in the From version 5.21 section below. Sending mail does not change.

Creating cases from incoming mail

Two crons download mail and create cases. Only one of them may run at a time; TAS enforces this and blocks the other cron:

CronNote
Create Processes from MS Graph mailsOlder variant.
Create Processes from MS Graph mails (v2)Successor, recommended for new deployments. When you upgrade an installation that used the older cron, TAS automatically creates the v2 variant with the same settings, but inactive – activate it yourself once you have verified that the settings are correct.

A separate cron, MsGraphCheckUnprocessedMailsCron, checks whether unprocessed mail is left in the mailbox, for example because of a processing error.

v2 cron settings

ParameterMeaning
amountOfEmailByRunHow many emails the cron processes per run (default 100).
runSummary.log / .sendEmail / .emailAddressesWhether the run is logged and/or a summary email is sent, and to whom.
items[]One item = one monitored mailbox/folder; the cron can have several configured at once.
items[].auth.emailAddressAddress of the mailbox to read from.
items[].auth.tenantId, .clientId, .clientSecretDetails of the app registered in Entra ID (see below). Apply only to type: "secret".
items[].auth.typesecret (app with a client secret) or dedicated (interactive sign-in without a stored secret).
items[].auth.scopePermission scope; if left empty, https://graph.microsoft.com/.default is used (all application permissions the Entra ID administrator granted to the app).
items[].folders.in.id / .out.idID of the folder to read from and of the folder messages are moved to after processing.
items[].process.user_id, .tproc_id, .header_idThe user under which the case is created, and the template/header it is created in.
items[].mapping, .headerMappingMapping of email fields (subject, body, sender, attachments) to case variables.
items[].messageClass.enabled, .allowedPrefixes, .ignoredClassesRestriction by message type (e.g. skipping automatic replies).
items[].config.setEmailProcessedOnErrorWhether the email is marked as processed even after an error, so the cron does not get stuck on the same message.
items[].config.ignoreAllAttachments / .ignoreSpecificAttachments / .ignoredAttachmentTypes / .ignoreInlineAttachmentsControls which attachments are attached to the case.
items[].config.attachEmailAsPdfAttaches the email itself as a PDF.
items[].config.useEmailObjectInDataHolderMakes the whole email available as an object for template calculations instead of mapping it to individual variables.
Discovering folder IDs
You can get the mailbox folder IDs for folders.in/folders.out by calling the administrator endpoint POST /ms-graph/discover-folders; you do not have to look them up manually in Graph Explorer.

App registration in Entra ID

The cron needs an app registered in Microsoft Entra ID with an application permission to read (and, if needed, write) mail in the target mailbox, granted by the tenant administrator. From the registration you need tenantId, clientId and clientSecret (for the secret variant).

The client secret belongs in the Vault
Do not enter the value directly in the clientSecret field of the cron parameters – store it as a secret in the Vault and reference it with {{vault:nazev-klice}}. Do the same for the client secret used for sending mail below.

Sending mail via Graph or SMTP with OAuth2

Outgoing mail is configured in Configuration (email section), independently of the crons above. TAS supports two independent methods:

Type (integrations.mail.type)How it worksKey parameters
msgraphMail is sent directly via the Graph API (/sendMail), not via SMTP.tenantId, clientId, clientSecret, sender, optionally scope (default .default).
oauth2A standard SMTP server, but a short-lived OAuth2 token is used instead of a password (a generic mechanism, not only for Microsoft 365).host, port, basicAuth.user (mailbox), oauth2.host (token endpoint), oauth2.clientId, oauth2.clientSecret, oauth2.grantType, oauth2.scope.

Both sets of parameters can also be set with environment variables (TAS_MAIL_SMTP_TYPE, TAS_MAIL_MSGRAPH_* for the first type, TAS_MAIL_SMTP_* and TAS_MAIL_OAUTH2_* for the second) – details on editing in Configuration are in the article Configuration.

From version 5.21: migrating to Email Processing

Version 5.21 removed the crons Create Processes from MS Graph mails (MsGraphCreateProcessesFromMailCron), Create Processes from MS Graph mails (v2) (MsGraphCreateProcessesFromMailCron2) and Check unprocessed MS Graph mails (MsGraphCheckUnprocessedMailsCron). Their rows in Crons remain after the upgrade, including their parameters, so that the settings can be carried over; delete them once migrated. You now configure a mailbox once as a connection in Administration → Email Processing, and cases are created from it by the Email processing cron. Details are in the article Email Processing.

Migrating the settings

  1. In the Service Console, run return await sys.mail.migrateMsGraphToNewEmailStuff();. The function only lists what it would do and changes nothing.
  2. If the preview is correct, run return await sys.mail.migrateMsGraphToNewEmailStuff(true);. For each mailbox address from the old crons, it creates a connection of type msgraph. It derives the name from the address (for example invoices@company.com → invoices-company-com) and writes the source cron into the description. A client secret entered directly in the parameters is stored in the Vault as the secret msgraph-<connection name>; an existing {{vault:…}} reference is kept. If a mailbox is used in several crons, the details from the v2 variant are used. You can run the function repeatedly; existing connections are skipped.
  3. Review the warnings in the result: add the client secret manually to connections that lack one; connections using the discontinued dedicated sign-in are migrated as secret – switch them to managedIdentity if appropriate.
  4. The function does not migrate the cron settings. In Administration → Crons, open the Email processing cron (or create it with the Add cron button) and add a mailbox for each connection. From the old parameters, take over the folders (folders.in.id, folders.out.id), the user, template and header (process.user_id, tproc_id, header_id) and the variable mapping.
  5. Enable the Email processing cron and delete the old cron rows.
Original parameterIn the Email processing cron
items[].mappingVariables fields: Subject, Sender, Recipients, Body, Received At and Message Id. The new cron assigns a variable to each email detail; it does not support expressions.
items[].headerMappingVariables: Headers, but reversed: header name on the left, variable on the right. {"InvoiceId": "X-Invoice-Id"} becomes X-Invoice-Id → InvoiceId.
config.ignoreAllAttachmentsAttachments = skip.
config.ignoreSpecificAttachments, config.ignoredAttachmentTypesA single Ignored Attachment Types list.
config.attachEmailAsPdf, messageClassThe same options Attach Email As Pdf and Message Class. Message Class still works only with Microsoft Graph.
runSummary, errorEmailAddressesRemoved; no run summary email is sent. Every error is recorded in Logs and in Email Records.
Cron Check unprocessed MS Graph mailsNo replacement. Unprocessed emails are shown in Email Records and on the System Status page.
Other changes
The sys.msGraph* functions in the Service Console have been replaced by sys.mail.* functions, which take the connection name instead of the mailbox's position in the cron parameters. The POST /ms-graph/discover-folders endpoint has been replaced by the Discover folders action on the connection. The configuration key featureFlag.msGraph.maxHeadSize has been renamed to featureFlag.mail.maxHeadSize. If you changed it, set the value again under the new key.

Related: Email Processing, Crons, Configuration, Vault, Authentication.

MS Graph - preparing the mailbox

Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)