Microsoft Outlook is Microsoft's personal information manager, part of Microsoft 365, with email, calendar, contacts and tasks. The UnifyApps Microsoft Outlook connector uses the Microsoft Graph API v1.0 to send, reply to, forward and draft emails, read, move and update messages and their attachments, manage mail folders and contacts, read task lists, users and groups, and react to new emails and contacts from workflows and agents.
This guide covers every authentication type available on the connection form, and the actions and triggers supported, along with the Microsoft Graph permission each one needs.
Authentication
Before you begin, you should have the following information:
Connection name: a descriptive name such as MyAppOutlookIntegration, so the connection is easy to identify later.
Authentication type: select the type of authentication for connecting to your Outlook account:
OAuth 2.0 (Authorization)
OAuth 2.0 (Authorization) With Custom Credentials
OAuth 2.0 (Client Credentials)
Client certificate credentials with config
Every authentication type also shows a Connection field, which defaults to Directly. Choose Via On-Prem Agent and an On-Prem Group only if UnifyApps must reach Microsoft Graph through an on-premises agent. The optional Event Hub fields are needed only for the New mail (Event Hubs delivery) trigger; see Event Hub fields at the end of this section.
The Tenant ID field is optional on the first three types. If you leave it blank, common is used, which lets users of any organization sign in.
1. OAuth 2.0 (Authorization)
Use this when you want to connect with your own Microsoft account and do not need to register an app in Azure.
Enter a Connection name.
Select OAuth 2.0 (Authorization) as the Authentication type.
Leave Tenant ID blank (
common), or enter your tenant ID to restrict sign-in to one organization.Select the Scopes the connection needs; see the tables below.
offline_accessis always added so the connection can refresh its token.Keep Delegated scopes turned on, so actions run as the signed-in user.
Click Authorize. You are redirected to the Microsoft sign-in page.
Sign in with the Microsoft account whose mailbox the connection should use.
Review the permissions requested on the consent screen and click Accept.
You are redirected back to UnifyApps with a confirmation that the account is connected.
2. OAuth 2.0 (Authorization) With Custom Credentials
Use this when your organization wants the connection to use its own Azure app registration, while actions still run on behalf of a signed-in user.
Step 1: App registration in Azure
Log in to the Azure portal, search for App registrations and click New registration.


Enter a name and choose the supported account type: single tenant (only your organization) or multitenant (any Microsoft Entra ID tenant).
Under Redirect URI, choose platform Web and paste the Callback URL shown at the top of the connection form (it is copyable and differs per environment).
Click Register.


On the Overview tab, copy the Application (client) ID and the Directory (tenant) ID.


Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions and add
offline_accessand the permissions the connection needs, for exampleMail.ReadandMail.Send. Click Grant admin consent if your tenant requires it.


Go to Certificates & secrets → New client secret, add a description and expiry, and click Add. Copy the secret Value immediately and store it securely. It is not shown again.


Step 2: Connection setup in UnifyApps
Open Connections → New Connection → Microsoft Outlook and enter a Connection name.
Select OAuth 2.0 (Authorization) With Custom Credentials as the Authentication type.
Enter the Client ID and Client secret copied from Azure.
Enter the Tenant ID. Use your Directory (tenant) ID if the app is single tenant; leave it blank (
common) only for a multitenant app.Select the same Scopes you added as delegated permissions in Azure.
Keep Delegated scopes turned on.
Click Authorize, sign in with Microsoft and accept the consent screen.
Confirm the success message after the redirect back to UnifyApps.
3. OAuth 2.0 (Client Credentials)
Use this for app-only access that does not depend on a signed-in user, for example a workflow that reads a shared support mailbox. The app acts as itself with Application permissions, and needs admin consent.
Step 1: Register the app in Azure
Log in to the Azure portal, search for App registrations and click New registration.
Enter a name and supported account type, and click Register. No redirect URI is needed for this flow.
From Overview, copy the Application (client) ID and Directory (tenant) ID.


Go to API permissions → Add a permission → Microsoft Graph → Application permissions and add the permissions the connection needs, for example
Mail.ReadandMail.Send.Click Grant admin consent. Application permissions do not work until an administrator grants consent.


Go to Certificates & secrets → New client secret, click Add, and copy the secret Value immediately.
Note: Application permissions such as Mail.Read let the app read every mailbox in the organization. To limit the app to specific mailboxes, an Exchange administrator can use RBAC for Applications in Exchange Online.
Step 2: Create the connection in UnifyApps
Select OAuth 2.0 (Client Credentials) as the Authentication type.
Enter the Client ID and Client secret.
Enter the Tenant ID. Use your actual tenant ID here; the default
commonis meant for the sign-in based flows.Enter the Run-time user: the email address of the mailbox the connection acts on. If you leave it blank, actions use the mailbox given in the action, or the mailbox of the UnifyApps user who runs it.
Turn off Delegated scopes (it is on by default). With app-only access there is no signed-in user to act as.
Click Test Connection to validate the credentials, then click Create.
4. Client certificate credentials with config
Use this for app-only access like type 3, but with a certificate instead of a client secret. Microsoft recommends certificates over client secrets for production.
Step 1: Register the app and upload a certificate in Azure
Log in to the Azure portal, search for App registrations and click New registration.
Enter a name and supported account type, and click Register. No redirect URI is needed.
From Overview, copy the Application (client) ID and Directory (tenant) ID.
Go to API permissions → Add a permission → Microsoft Graph → Application permissions, add the permissions the connection needs, and click Grant admin consent.
Have a certificate ready as a .cer, .pem or .crt file, together with its private key in PEM format.
Go to Certificates & secrets → Certificates → Upload certificate, select the certificate file and click Add.
Copy the certificate's Thumbprint from the list.
Step 2: Create the connection in UnifyApps
Select Client certificate credentials with config as the Authentication type.
Enter the Client ID and the Tenant ID (both required).
Enter the Thumbprint copied from Azure. The hex value shown in the Azure portal, with or without colons, or a base64url value is accepted.
Paste the Private key that belongs to the uploaded certificate.
Leave Delegated scopes turned off (the default for this type). Actions use the mailbox given in the action, or the mailbox of the UnifyApps user who runs it.
Click Test Connection to validate the credentials, then click Create.
Event Hub fields
These fields are optional and only used by the New mail (Event Hubs delivery) trigger, which receives mail notifications through Azure Event Hubs instead of a webhook. Leave them blank otherwise.
In the Azure portal, select Create a resource, search for Event Hubs and create an Event Hubs namespace.
Open the namespace, select Event Hubs → + Event Hub, enter a name and click Create.
In the namespace, go to Access Control (IAM) → + Add → Add role assignment, select the Azure Event Hubs Data Sender role, add the Microsoft Graph Change Tracking service principal as the member, and click Review + assign.
Open the event hub, go to Shared access policies → + Add, create a policy with Listen, and copy its Connection string–primary key.
On the connection form, enter:
Event Hub Namespace and Event Hub Name, for example
contoso-nsandoutlook-mail.Event Hub Consumer Group, or leave it blank to use
$Default.Event Hub Resource ID:
https://<namespace>.servicebus.windows.net/eventhubname/<event hub name>.Event Hub Tenant Domain: your tenant's primary domain, for example
contoso.com(shown on the Microsoft Entra ID overview page).Event Hub Listen Connection String: the connection string copied in step 4.
Event Hub Decryption Private Key and Decryption Key Password: leave blank for notifications without resource data.
See Receive change notifications through Azure Event Hubs for details.
Actions
Permissions are Microsoft Graph permissions. Unless a row lists Delegated and Application separately, the same name applies to both: select it in Scopes for types 1 and 2, or add it as an Application permission in Azure for types 3 and 4. When the least-privileged permission is not in the form's Scopes list, select the broader one in brackets. Mail.ReadBasic returns messages without their body and attachments (its Application form is Mail.ReadBasic.All); use Mail.Read to get them. To act on another user's or a shared mailbox with a delegated connection, use the shared variant, for example Mail.ReadWrite.Shared.
Actions | Description | Scopes Required |
|---|---|---|
| Adds a contact to the root Contacts folder in Microsoft Outlook. | Contacts.ReadWrite |
| Creates a draft email with attachments in Microsoft Outlook. | Mail.ReadWrite |
| Creates a draft email in the specified user's mailbox in Microsoft Outlook. | Mail.ReadWrite |
| Creates a mail folder in Microsoft Outlook. | Mail.ReadWrite |
| Deletes a contact in Microsoft Outlook. | Contacts.ReadWrite |
| Deletes a message from the specified user's mailbox in Microsoft Outlook. | Mail.ReadWrite |
| Downloads a message from Microsoft Outlook in MIME format. | Mail.Read |
| Fetches all tasks in a task list from Microsoft Outlook. | Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All |
| Fetches all groups a user is a member of in Microsoft Outlook. | Delegated: User.Read.All; Application: Directory.Read.All |
| Fetches all contacts in Microsoft Outlook. | Contacts.Read |
| Fetches a message by its ID in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Fetches all messages in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Fetches the messages of a mailbox in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Fetches all messages from a mailbox folder path in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Fetches all task lists from Microsoft Outlook. | Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All |
| Retrieves user details from Microsoft Outlook. | Delegated: User.Read; Application: User.Read.All |
| Forwards a message in Microsoft Outlook. | Mail.Send |
| Retrieves the properties and relationships of a contact in Microsoft Outlook. | Contacts.Read |
| Gets the details of a specific folder in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Retrieves an email attached to a message, with its nested attachments expanded and flattened into a list of messages and file attachments. | Mail.Read |
| Gets the messages added, updated or deleted in a mail folder since the last delta call. Pass the returned delta token to the next call to get only new changes. | Mail.ReadBasic (or Mail.Read) |
| Retrieves messages from a specified mailbox and mail folder in Microsoft Outlook. | Delegated: Mail.Read.Shared (or Mail.ReadWrite.Shared); Application: Mail.ReadBasic.All (or Mail.Read) |
| Gets all the categories defined for a user in Microsoft Outlook. | MailboxSettings.Read |
| Retrieves the list of contacts in Microsoft Outlook. | Contacts.Read |
| Gets all the mail folders in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Lists all the mail folders in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Fetches the members or owners of a group in Microsoft Outlook. | GroupMember.Read.All (or Group.Read.All) |
| Lists the message rules for a mail folder in Microsoft Outlook. | MailboxSettings.Read |
| Lists users in Microsoft Outlook. | Delegated: User.ReadBasic.All (or User.Read.All); Application: User.Read.All |
| Moves a message to another folder within the specified user's mailbox. | Mail.ReadWrite |
| Retrieves an attachment of a message in Microsoft Outlook. | Mail.Read |
| Retrieves the attachments of a message in Microsoft Outlook, with their content as files. | Mail.Read |
| Retrieves the list of attachments of a message in Microsoft Outlook. | Mail.Read |
| Fetches the contacts that match a query in Microsoft Outlook. | Contacts.Read |
| Searches emails in Microsoft Outlook. | Mail.Read (delegated types only; Microsoft Search covers only the signed-in user's own mailbox) |
| Sends an existing draft (a new message, reply, reply-all or forward) and saves it in Sent Items. | Mail.Send |
| Sends an email from Microsoft Outlook. | Mail.ReadWrite and Mail.Send (the email is saved as a draft, then sent) |
| Replies to the sender or all recipients of a message in Microsoft Outlook. | Mail.ReadWrite and Mail.Send (the reply is saved as a draft, then sent) |
| Updates a contact in Microsoft Outlook. | Contacts.ReadWrite |
| Updates a mail folder in Microsoft Outlook. | Mail.ReadWrite |
| Updates a message in Microsoft Outlook. | Mail.ReadWrite |
| Fetches every To Do task list in Microsoft Outlook using the delta query, which is not cut short like the plain list. | Delegated: Tasks.ReadWrite; Application: Tasks.Read.All |
| Fetches a specific attachment of a task in Microsoft Outlook and returns its content as a file. | Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All |
| Fetches all attachments of a task in Microsoft Outlook. | Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All |
| Fetches a single task by its ID in Microsoft Outlook. | Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All |
| Fetches a single task list by its ID in Microsoft Outlook. | Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All |
| Gets user information by user ID from Microsoft Outlook. | Delegated: User.Read for your own profile, User.ReadBasic.All (or User.Read.All) for another user; Application: User.Read.All |
Triggers
Triggers | Description | Scopes Required |
|---|---|---|
| Triggers when a new contact is created. | Contacts.Read |
| Triggers when a contact is created or updated. | Contacts.Read |
| Triggers when a new email arrives in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Triggers when a new email arrives in Microsoft Outlook. Older version of New email. | Mail.ReadBasic (or Mail.Read) |
| Triggers when a new email arrives in a specific folder of a shared mailbox in Microsoft Outlook. | Delegated: Mail.Read.Shared (or Mail.ReadWrite.Shared); Application: Mail.ReadBasic.All (or Mail.Read) |
| Triggers in real time, through a Microsoft Graph webhook subscription, when an email is created, updated or deleted in Microsoft Outlook. | Delegated: Mail.ReadBasic (or Mail.Read); Application: Mail.Read |
| Triggers when an email is created, updated or deleted in a mailbox, delivered through Azure Event Hubs. Deleted notifications carry only the message ID. | Delegated: Mail.ReadBasic (or Mail.Read); Application: Mail.Read; plus the Event Hub fields on the connection |
| Triggers when an email is starred (flagged) in Microsoft Outlook. | Mail.ReadBasic (or Mail.Read) |
| Triggers when a task is created, updated or deleted in a Microsoft Outlook task list. | Delegated: Tasks.ReadWrite; Application: Tasks.ReadWrite.All |