Settings: e-mail via Microsoft 365

MasterKey can send automatic e-mails (for example reports and notifications) from a mailbox of your own organization in Microsoft 365. To do this, your IT department creates an app registration in your own Microsoft 365 environment, and an administrator enters its details in MasterKey.

• MasterKey only gets the right to send e-mail from the mailbox you choose. No user password is stored.
• You decide which mailbox MasterKey may send from.
• You can revoke access at any time by deleting the client secret or the app registration.
• Because the e-mails are really sent from your own mailbox, no SPF record for MasterKey is needed, and sent e-mails appear in the Sent Items folder of that mailbox.

This page is intended for your IT department (steps 1 to 5) and for the MasterKey administrator within your organization (steps 6 and 7). Steps 1 to 5 require an account with the Application Administrator role and, for step 5, Exchange Administrator. Allow about 30 minutes.

Choose or create the mailbox that MasterKey will send from. We recommend a shared mailbox, for example quality@yourcompany.com; it does not need a license. If replies from recipients should be read, choose a mailbox that someone monitors.

Exchange Online has sending limits per mailbox: at most 10,000 recipients per day and 30 messages per minute. The default maximum message size is 35 MB.

1. Open the Microsoft Entra admin center (https://entra.microsoft.com) with an account that has the Application Administrator role or higher.
2. Go to Identity → Applications → App registrations → New registration.
3. Name: for example MasterKey mail.
4. Supported account types: Accounts in this organizational directory only (single tenant).
5. Redirect URI: leave empty. MasterKey does not sign in users, so no callback URL is needed.
6. Click Register. On the overview page, note the Directory (tenant) ID and the Application (client) ID.

1. In the app registration, go to API permissions → Add a permission → Microsoft Graph → Application permissions.
2. Add Mail.Send and Mail.ReadWrite. MasterKey sends small e-mails in one go with Mail.Send. For e-mails with large attachments (from about 3 MB), MasterKey first creates a draft in the mailbox, adds the attachments separately and then sends the draft; this requires Mail.ReadWrite. MasterKey does not read any other e-mail in the mailbox.
3. Remove the default User.Read permission; it is not needed.

With only these permissions the app cannot do anything yet: in step 5 you grant consent, preferably limited to one mailbox.

1. Go to Certificates & secrets → New client secret.
2. Choose a duration (maximum 24 months) and note the expiry date.
3. Copy the Value of the secret immediately. It cannot be viewed again later. Note: do not use the Secret ID.

Treat the secret like a password: do not send it by regular e-mail. Preferably enter it in MasterKey yourself (step 6), together with the MasterKey administrator.

With a regular admin consent, the app may work from and in all mailboxes of your organization. We recommend limiting this to the mailbox from step 1 with RBAC for Applications in Exchange Online. In that case, do not grant admin consent under API permissions (or revoke it via Enterprise applications → MasterKey mail → Permissions), because that consent applies to all mailboxes and cancels the restriction.

Run the following in Exchange Online PowerShell. Use the object ID of the app under Enterprise applications, not the one under App registrations.

Install-Module ExchangeOnlineManagement   # once
Connect-ExchangeOnline
New-ServicePrincipal -AppId <Application (client) ID> -ObjectId <Object ID from Enterprise applications> -DisplayName "MasterKey mail"
New-ManagementScope -Name "MasterKey mail" -RecipientRestrictionFilter "PrimarySmtpAddress -eq 'quality@yourcompany.com'"
New-ManagementRoleAssignment -App <Application (client) ID> -Role "Application Mail.Send" -CustomResourceScope "MasterKey mail"
New-ManagementRoleAssignment -App <Application (client) ID> -Role "Application Mail.ReadWrite" -CustomResourceScope "MasterKey mail"

Check the restriction; both roles must show InScope True. For any other mailbox, InScope should be False:

Test-ServicePrincipalAuthorization -Identity <Application (client) ID> -Resource quality@yourcompany.com

It can take up to 2 hours before Microsoft has applied the permissions everywhere. To allow more mailboxes later, adjust the filter, for example to a mail-enabled security group: -RecipientRestrictionFilter “MemberOfGroup -eq '<DistinguishedName of the group>'”.

If you do not want to restrict the app, click Grant admin consent for <your organization> under API permissions.

Does your organization use Conditional Access for workload identities with a location restriction? Then ask MasterKey for the current outbound IP addresses and allow them for the app MasterKey mail. Regular Conditional Access policies for users do not apply to this app.

An administrator in MasterKey goes to Settings → Application → E-Mail and selects Microsoft 365 as the Mailserver. Fill in:

• Send from mailbox: the mailbox from step 1.
• Directory (tenant) ID and Application (client) ID: from step 2.
• Client secret (value): the value from step 4. After saving, the secret is stored encrypted and never shown again; leave the field empty later to keep the saved secret.
• Secret expires on: the expiry date from step 4.

Click Save and then Send test mail. MasterKey then sends a test e-mail to your own e-mail address. If this fails, MasterKey shows Microsoft's message, for example when the secret is incorrect or the app has no permission for the mailbox (see Common messages).

From 30 days before the expiry date, MasterKey shows a warning under Settings → Application → E-Mail. After the expiry date, MasterKey can no longer send e-mail. Renew the secret in time:

1. Have your IT department create a new client secret (step 4). The old secret remains valid until its expiry date.
2. Enter the new value and expiry date in MasterKey, save and send a test mail.
3. Then have the old secret deleted in Entra.

You can stop the connection at any time; MasterKey can then no longer send e-mail from your mailbox:

• delete the client secret, or
• delete the app registration MasterKey mail, or
• remove the permissions from step 5 with Remove-ManagementRoleAssignment.

Then choose a different mail server in MasterKey under Settings → Application → E-Mail, otherwise no more e-mails will be sent.

• The client secret is encrypted as soon as it is saved (AES-256-GCM) and is only stored in encrypted form in the MasterKey database, with your organization's settings.
• The key used to encrypt the secret is not in the database but kept separately, in a protected environment of the MasterKey servers. A copy of the database alone is therefore not enough to read the secret.
• The secret is never sent back to the browser and does not appear in log files.
• Only the MasterKey mail service decrypts the secret, and only at the moment of sending.

Still stuck? Contact MasterKey support and include the full message. Never include the client secret.

Back to Settings: Application
Back to Settings