====== 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.

==== Summary ====
^ Item ^ Value ^
| Type of connection | App-only via Microsoft Graph (OAuth 2.0 //client credentials//); MasterKey does not sign in a user |
| Supported account types | Accounts in this organizational directory only (single tenant) |
| Redirect URI (callback URL) | **Not needed**, leave empty |
| Permissions | ''Mail.Send'' and ''Mail.ReadWrite'' (application permissions, not delegated) |
| Authentication | Client secret, valid for up to 24 months |
| SMTP AUTH | Not needed, may stay disabled |
| DNS (SPF, DKIM, DMARC) | No change needed; the e-mail is sent through your own Microsoft 365 |
| Outbound traffic from MasterKey | ''login.microsoftonline.com'' and ''graph.microsoft.com'' (HTTPS, port 443) |
| Details for MasterKey | Mailbox address, Directory (tenant) ID, Application (client) ID, value and expiry date of the client secret |

==== Step 1: Choose a mailbox ====
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.

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

==== Step 3: Add permissions ====
  - In the app registration, go to **API permissions → Add a permission → Microsoft Graph → Application permissions**.
  - 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.
  - 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.

==== Step 4: Create a client secret ====
  - Go to **Certificates & secrets → New client secret**.
  - Choose a duration (maximum 24 months) and note the **expiry date**.
  - 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.

==== Step 5: Grant consent, limited to one mailbox (recommended) ====
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.

<code powershell>
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"
</code>

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

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

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.

==== Step 6: Enter the details in MasterKey ====
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//).

==== Step 7: Before the client secret expires ====
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:
  - Have your IT department create a new client secret (step 4). The old secret remains valid until its expiry date.
  - Enter the new value and expiry date in MasterKey, save and send a test mail.
  - Then have the old secret deleted in Entra.

==== Revoking access ====
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.

==== How MasterKey stores the client secret ====
  * 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.

==== Common messages ====
^ Message contains ^ Cause ^
| AADSTS7000222 | The client secret has expired. Create a new secret (step 7). |
| AADSTS7000215 | The client secret is incorrect; often the //Secret ID// was entered instead of the **Value**. |
| AADSTS700016 | The Application (client) ID does not exist in this Microsoft 365 environment. |
| AADSTS90002 | The Directory (tenant) ID does not exist. |
| ErrorAccessDenied / AccessDenied | The app has no permission for this mailbox (step 5). Just changed? Wait up to 2 hours. If it only fails with large attachments, Mail.ReadWrite is missing. |
| ErrorInvalidUser / MailboxNotEnabledForRESTAPI / ResourceNotFound | The mailbox does not exist or is not an Exchange Online mailbox. |
| ErrorMessageSizeExceeded | The e-mail is larger than the mailbox is allowed to send. Increase the maximum send size of the mailbox. |

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

----

[[en:desktop:instellingen:applicatie|Back to Settings: Application]] \\
[[en:desktop:instellingen|Back to Settings]]