Skip to main content

Graph Mailserver and Mail Repository

In order to be able to fully use the Graph Mailserver, it is essential to grant the following permissions to the Adito Application: Mail.ReadWrite and Mail.Send.

Breakdown of Used API Endpoints and Corresponding Permissions​

The following operations are potentially performed by the Graph Mailserver or the Graph Mail Repository:

  • Fetching Mails (GraphMailRepository.getMessages):
    • Uses: GET /users/{id}/mailFolders/{id}/messages
    • Permission: Mail.Read or Mail.ReadWrite
  • Editing/Updating Mails (GraphMailRepository.setFlag):
    • Uses: PATCH /users/{id}/mailFolders/{id}/messages/{id}
    • Permission: Mail.ReadWrite
  • Creating/Storing Mails (GraphMailRepository.storeMessages):
    • Uses: POST /users/{id}/mailFolders/{id}/messages
    • Permission: Mail.ReadWrite
  • Deleting Mails (GraphMailRepository.deleteMessages):
    • Uses: DELETE /users/{id}/mailFolders/{id}/messages/{id}
    • Permission: Mail.ReadWrite
  • Copying Mails (GraphMailRepository.copyMessages):
    • Uses: POST /users/{id}/mailFolders/{id}/messages/{id}/copy
    • Permission: Mail.ReadWrite
  • Sending Mails (GraphMailServer.sendMessages):
    • Uses: POST /users/{id}/sendMail
    • Permission: Mail.Send

So the permission Mail.ReadWrite is needed if any operation is performed on the mailserver that modifies the mail or a mailbox. In the most minimal example a flag is set when an email is read because it must be marked as read in the mailbox. Otherwise, it would be fetched again at the next run of the mailbridge.

So as the mailbridge is setting Flags on the mails it processes, as of now, it is necessary to have the Mail.ReadWrite permission, whenever you are using a mailbridge.

info

The permission Mail.Send is needed if any operation is performed on the mailserver that sends an email.

tip

Sometimes company security policies don't allow or at least discourage Mail.ReadWrite. If you will only be reading emails from the mailbox, you might consider only using the Mail.Read permission.

Configuration​

This section briefly explains how to configure the Graph Mailserver in Adito. Compared to the other mailbridge implementation, the configuration is much simpler. You only need the clientId and the tenantId as base information.

There are two authentication methods available: SHARED_SECRET and CERTIFICATE. It can be selected in the serverAuthMethod property combo box. Depending on what is chosen here you either have to provide a clientSecret or a certificateName.

This shows an example of a configuration for the SHARED_SECRET authentication method: New Alias Definition

This shows an example of a configuration for the CERTIFICATE authentication method: New Alias Definition

The clientSecret can be found in the Azure Portal under Certificates & Secrets. It is possible to add more than one secret. The certificateName is the name of the certificate that was uploaded to the Azure Key Vault.

After logging in to the Azure Portal, go to App registrations and select the application you created.

Azure

Click on the link just next to Client credentials to get to the mask where you can add a secret.

Azure Secrets

In this case we can either add a new secret or upload a certificate.

Azure Secrets

Certificate Authentication​

For more detailed information on how to set up and use certificate-based authentication, please refer to the Certificate Authentication documentation.