Overview

The Graph API email integration connects Pro ESM to your Microsoft 365 mailboxes through the Microsoft Graph API. You can receive the emails of a mailbox as data cards in the ESM database, and you can send an email to one recipient directly from a data card.

Secure, Service-based Authentication

The integration uses modern, service-based authentication. Instead of signing in to a mailbox with a user name and password, Pro ESM signs in as an application that you register in Microsoft Entra. The application identifies itself with its client ID and client secret, and Microsoft issues the access token that Pro ESM uses to call the Microsoft Graph API.

This approach has several benefits:

• You do not store a mailbox user name or password in Pro ESM for this integration. You enter only the details of the registered application and the mailbox that the integration reads.
• You decide what the application can do. You select the Microsoft Graph permissions when you register the application, and you grant them with admin consent.
• You manage access in Microsoft Entra. You choose the duration of the client secret when you create it, so you can renew it on your own schedule.

Current Capabilities and Limitations

What You Can Do

• Receive emails from a Microsoft 365 mailbox through the Microsoft Graph API. Each email is stored as a data card.
• Since 26.2 release: Send an email to one recipient from the Graph API email attribute on a data card.

Limitations

• The integration is a beta. You should use it in test environments only.
• Do not connect the Graph API email task and a regular MailTask to the same mailbox folder. Both tasks remove an email from the mailbox after they import it, so only the task that runs first imports it.
• You cannot attach files when you send an email.
• When you send an email, you can enter one recipient in the To field. The form has no CC or BCC fields.

Setup

1. Register app in Microsoft Entra admin center.
   1. Microsoft's documentation: "Microsoft Graph Tutorial - Register the app in the portal".
2. Select Applications → App registrations from left panel.
   
3. Select New registration and enter a name for your application.
4. Set Supported account types to Accounts in this organizational directory only.
5. Select Register.
6. On the application's Overview page, copy the value of the Application (client) ID and Directory (tenant) ID and save them. Enter these values in the ESM platform settings graph.api.clientid and graph.api.tenant. When you receive email, you can enter them as properties of the scheduled task instead.
   
7. Select API permissions under Manage.
8. Select Add a permission, then Microsoft Graph.
9. Select Application permissions.
10. Select User.Read.All, Mail.ReadWrite, and Mail.Send, then select Add permissions.
11. Select Grant admin consent for..., then select Yes to provide admin consent for the selected permission.
12. Select Certificates and secrets under Manage, then select New client secret.
13. Enter a description, choose a duration, and select Add.
14. Copy the secret from the Value column and enter it in the ESM platform setting graph.api.secret. When you receive email, you can enter it as a property of the scheduled task instead.
    1. Important - This client secret is never shown again, so make sure you copy it now!
15. If you want to send emails, enter the mailbox that sends them in the platform setting graph.api.sending.address. The Azure application needs the Send As permission for this mailbox.
16. In the ESM application, set the platform setting graph.api.enabled to true and restart the application. The restart creates the system template Email, which stores incoming and outgoing emails as data cards.
17. Add the email attribute to the data card template where you want to read and send emails, for example the Incident template. In the template editor, add a new attribute and set it up as follows:
    • Select Reference as the data type of the attribute. The attribute is always multi-value.
    • Select GraphAPIEmail as the handler. Pro ESM selects the system template Email, which the restart in the previous step created, as the target of the reference automatically.
18. If you want to receive emails, create a new scheduled task [BETA]GraphApiMailTask.
    1. Set up the following properties:

Set up these properties for the scheduled task. All of them are required.

• The Application (client) ID, the client secret, and the Directory (tenant) ID. If you leave these empty, the task uses the platform settings graph.api.clientid, graph.api.secret, and graph.api.tenant.
• The email address of the mailbox that the task reads, and the name of the mailbox folder.
• The code of the mail template, and the folder where ESM saves the mail data cards.
• The codes of the attributes for the mail tracking ID, the mail body, the mail subject, and the attribute that stores the email data card references.

Platform settings

Setting names and availability can change between versions.

Sending an Email

Before you send an email, add the email attribute to the data card template as described in the setup steps, and set the platform settings graph.api.enabled, graph.api.tenant, graph.api.clientid, graph.api.secret, and graph.api.sending.address.

1. On the data card, open the Graph API email attribute and select New Email. You need edit permission on the attribute.
   • If a default email template exists, the form opens with the subject filled in with the mail tracking tag of the data card, for example [#ID:123#].
   • If email templates exist but none is the default, the form opens empty.
   • If no email template exists yet, the dialog Create email message template opens first. Enter a Name, select the Tracking attribute, and select Create template. The first template becomes the default automatically, and the form then opens.
2. In To, enter one email address. This is required.
3. In Subject, enter a subject. This is required. Keep the tracking tag in the subject.
4. Optionally, enter the message body.
5. Select Send. The button is available when To contains a valid address and Subject is not empty.

About Email Message Templates

In 26.2, an email message template is deliberately minimal. It records which data card template and email attribute it applies to, which attribute holds the tracking ID, and whether it is the default template. When an agent starts a new email, the template fills in the tracking tag in the subject, and the agent writes the rest. Templates do not yet carry a sender, recipients, subject text, body text or attachments, which the email templates in EntityStateMail do.

You must create at least one email message template before you can send a manual email, because the template links the email to the data card. Richer templates are part of the planned work for later stages. The scope will be announced when it is confirmed.

Email-template

The system template Email has the following attributes.