Accounts¶
You can connect to user and shared mailboxes in your M365 environment. Follow the steps below and skip not applicable parts.
First Steps¶
Check your FQDN under Settings > System > Fully Qualified Domain Name in the admin interface of Zammad. If it is not correct, change it now. Otherwise the setup of the channel will fail.
Go to Channels > Microsoft 365 Graph Email and click on Connect Microsoft 365 App. Copy the provided callback URL.
Configuration¶
Go to Microsoft’s Entra admin center and log in as an administrator (at least application administrator permission is required).
Create App¶
Create a new app by going to Applications > App registrations and select New registration.
Enter a fitting name and select an account type. Supported types are:
Accounts in this organizational directory only (Single tenant)
Accounts in any organizational directory (Multitenant)
Under “Redirect URI”, select “Web” as platform and paste your already copied callback URL from Zammad.
Click on Register.
In the overview screen, copy the “Application (client) ID”, switch to Zammad and paste it in the “Client ID” field in the pop up.
Only required for single tenant setup: copy the “Directory (tenant) ID” and paste it in the “Tenant UUID/Name” field in Zammad.
Create Secret¶
In Entra, go to “Certificates & secrets” and add a secret by clicking the New client secret button.
Enter a description, set an expiry duration and click Add.
Copy the string under “Value”, this is the secret. Paste it to Zammad in the “Client Secret” field.
Configure API Permissions¶
Go to “API permissions” and Add a permission.
Select “Microsoft Graph” and “Delegated permissions”.
Add the following permissions:
offline_accessopenidprofileMail.ReadWriteMail.SendMail.ReadWrite.SharedMail.Send.Shared
Save it by clicking the Add permissions button.
Configure the Channel in Zammad¶
App Configuration¶
If you followed this guide, you already should have pasted your app information. If not, here is a short summary:
In Zammad’s channel configuration, click on Configure App.
Enter your app details:
Client ID: Application (client) ID
Client Secret: Value from client secret
Tenant UUID/Name: Directory (tenant) ID (not required for shared mailboxes)
Click on Submit.
Add Account¶
Now you can add your account to Zammad. Do so by clicking the Add account button in the top right corner. Select the correct mailbox type. In case you selected “Shared Mailbox”, you have to enter the email address of the shared mailbox. Confirm by clicking the Authenticate button, enter your credentials and confirm the requested permissions by clicking the Accept button.
After that, Zammad will ask you to assign a destination group. Select a group which should (initially) handle the incoming tickets of this channel. You can also specify a folder from which Zammad should fetch emails from. If you do so, make sure that the emails are routed to this folder somehow. Otherwise you won’t receive tickets. Leave it empty to fetch all emails from the inbox. After that, choose if fetched emails should remain on the server or not.
Depending if there are already email messages in this account, the archive mode dialog may be shown.
How should old emails be imported?¶
During the process of setting up an email based channel, Zammad checks if emails are present in the inbox. If Zammad detects at least one email, the archive mode dialog is triggered and the archive mode is turned on by default. This dialog is also present if you edit an existing email based channel. The archive mode lets you:
Set an archive cut-off time, which means: older emails are imported in archive mode, newer ones as standard tickets (including auto-reply messages and in state “new”).
Select a target state for the archived emails: in most cases you might want to import these archived emails in “closed” state. However, if your use case is different, you can choose another one which fits for you.
By archiving emails, their creation date and time is preserved and no automatic actions (e.g. trigger with auto-reply) will take place. If imported as regular tickets, the date and time is always the time of the import.
To import all emails as regular tickets, just turn the archive mode toggle off.
Danger
If you turn off the archive mode, Zammad treats all emails (even old ones) as if they had been sent today. This means senders will receive auto-replies and tickets are created with state “new” for each message.
If you want to differentiate even more, you have to do it manually and disable things like triggers before adding an email account, depending on your use case.
Now your channel is ready and can be used! If something doesn’t work, have a look at the common errors section, where you can find common errors related to the M365 configuration.
Note
🤔 How do I use my Microsoft 365 account for outgoing system notifications?
On subscription/cloud-hosted instances, you can’t. Notifications will always come from “Notification Master <noreply@your.zammad.domain>”.
On self-hosted instances, we still don’t recommend it. Using a Microsoft account for automated, outgoing messages is risky: users who exceed Microsoft’s email sending limits can have their accounts suspended.
Set up a generic email channel instead, then use the Email Notification setting.
Re-Authenticate¶
If your token got invalid, you have to replace the token due to other reasons, you want to use a shared mailbox with another user, you can use the Re-Authenticate button.
In case you are using an user mailbox, the new user has to match the existing one, otherwise it will result in a user mismatch error. In this case, you should delete the channel and add a new account.
Request Admin Consent¶
It is possible to request the permissions via admin consent. In this case Zammad will request necessary permissions for you from your admin, and then your admin (if it’s not the same user as you) can accept them on Microsoft side. Trigger this process via the Request Admin Consent button in Zammad.