MS Graph (email)

MS Graph connects TAS to Microsoft 365 mailboxes: it can create cases from incoming mail and can send mail from TAS through Graph (or through 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 as of 5.19.12, so MS Graph is the only supported option.

Creating cases from incoming mail

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

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

A separate cron, MsGraphCheckUnprocessedMailsCron, checks whether any unprocessed mail remains 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 of them set up 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 that the Entra ID administrator has approved for the app).
items[].folders.in.id / .out.idID of the folder to read from, and of the folder that messages are moved to after processing.
items[].process.user_id, .tproc_id, .header_idThe user who creates the case, and the template/header used for it.
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 an 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 / .ignoreInlineAttachmentsControl which attachments are added 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 need 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, approved by the tenant administrator. From the registration you need tenantId, clientId and clientSecret (for the secret type).

Store the client secret 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 with the client secret for sending mail below.

Sending mail through Graph or SMTP with OAuth2

Outgoing mail is set up in Configuration (email section), separately from the crons above. TAS supports two independent methods:

Type (integrations.mail.type)How it worksKey parameters
msgraphMail is sent directly through the Graph API (/sendMail), not through 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 general 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). For details on editing them in Configuration, see the Configuration article.

Related: Crons, Configuration, Vault, Authentication.

MS Graph - preparing the mailbox
Syca (opens in a new tab)

Powered by HelpDocs (opens in a new tab)