Unify Integrations
Logo
Microsoft Outlook

Microsoft Outlook

Logo

13 mins READ

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:

    1. OAuth 2.0 (Authorization)

    2. OAuth 2.0 (Authorization) With Custom Credentials

    3. OAuth 2.0 (Client Credentials)

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

  1. Enter a Connection name.

  2. Select OAuth 2.0 (Authorization) as the Authentication type.

  3. Leave Tenant ID blank (common), or enter your tenant ID to restrict sign-in to one organization.

  4. Select the Scopes the connection needs; see the tables below. offline_access is always added so the connection can refresh its token.

  5. Keep Delegated scopes turned on, so actions run as the signed-in user.

  6. Click Authorize. You are redirected to the Microsoft sign-in page.

  7. Sign in with the Microsoft account whose mailbox the connection should use.

  8. Review the permissions requested on the consent screen and click Accept.

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

  1. Log in to the Azure portal, search for App registrations and click New registration.

microsoft-outlook-screenshot-1.png
microsoft-outlook-screenshot-1.png

  1. Enter a name and choose the supported account type: single tenant (only your organization) or multitenant (any Microsoft Entra ID tenant).

  2. 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).

  3. Click Register.

microsoft-outlook-screenshot-2.png
microsoft-outlook-screenshot-2.png

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

microsoft-outlook-screenshot-3.png
microsoft-outlook-screenshot-3.png

  1. Go to API permissions → Add a permission → Microsoft Graph → Delegated permissions and add offline_access and the permissions the connection needs, for example Mail.Read and Mail.Send. Click Grant admin consent if your tenant requires it.

microsoft-outlook-screenshot-4.png
microsoft-outlook-screenshot-4.png

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

microsoft-outlook-screenshot-5.png
microsoft-outlook-screenshot-5.png

Step 2: Connection setup in UnifyApps

  1. Open Connections → New Connection → Microsoft Outlook and enter a Connection name.

  2. Select OAuth 2.0 (Authorization) With Custom Credentials as the Authentication type.

  3. Enter the Client ID and Client secret copied from Azure.

  4. Enter the Tenant ID. Use your Directory (tenant) ID if the app is single tenant; leave it blank (common) only for a multitenant app.

  5. Select the same Scopes you added as delegated permissions in Azure.

  6. Keep Delegated scopes turned on.

  7. Click Authorize, sign in with Microsoft and accept the consent screen.

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

  1. Log in to the Azure portal, search for App registrations and click New registration.

  2. Enter a name and supported account type, and click Register. No redirect URI is needed for this flow.

  3. From Overview, copy the Application (client) ID and Directory (tenant) ID.

microsoft-outlook-screenshot-6.png
microsoft-outlook-screenshot-6.png

  1. Go to API permissions → Add a permission → Microsoft Graph → Application permissions and add the permissions the connection needs, for example Mail.Read and Mail.Send.

  2. Click Grant admin consent. Application permissions do not work until an administrator grants consent.

microsoft-outlook-screenshot-7.png
microsoft-outlook-screenshot-7.png

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

  1. Select OAuth 2.0 (Client Credentials) as the Authentication type.

  2. Enter the Client ID and Client secret.

  3. Enter the Tenant ID. Use your actual tenant ID here; the default common is meant for the sign-in based flows.

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

  5. Turn off Delegated scopes (it is on by default). With app-only access there is no signed-in user to act as.

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

  1. Log in to the Azure portal, search for App registrations and click New registration.

  2. Enter a name and supported account type, and click Register. No redirect URI is needed.

  3. From Overview, copy the Application (client) ID and Directory (tenant) ID.

  4. Go to API permissions → Add a permission → Microsoft Graph → Application permissions, add the permissions the connection needs, and click Grant admin consent.

  5. Have a certificate ready as a .cer, .pem or .crt file, together with its private key in PEM format.

  6. Go to Certificates & secrets → Certificates → Upload certificate, select the certificate file and click Add.

  7. Copy the certificate's Thumbprint from the list.

Step 2: Create the connection in UnifyApps

  1. Select Client certificate credentials with config as the Authentication type.

  2. Enter the Client ID and the Tenant ID (both required).

  3. Enter the Thumbprint copied from Azure. The hex value shown in the Azure portal, with or without colons, or a base64url value is accepted.

  4. Paste the Private key that belongs to the uploaded certificate.

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

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

  1. In the Azure portal, select Create a resource, search for Event Hubs and create an Event Hubs namespace.

  2. Open the namespace, select Event Hubs → + Event Hub, enter a name and click Create.

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

  4. Open the event hub, go to Shared access policies → + Add, create a policy with Listen, and copy its Connection string–primary key.

  5. On the connection form, enter:

    • Event Hub Namespace and Event Hub Name, for example contoso-ns and outlook-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

Create Contact

Adds a contact to the root Contacts folder in Microsoft Outlook.

Contacts.ReadWrite

Create draft email with attachments

Creates a draft email with attachments in Microsoft Outlook.

Mail.ReadWrite

Create draft mail

Creates a draft email in the specified user's mailbox in Microsoft Outlook.

Mail.ReadWrite

Create mail folder

Creates a mail folder in Microsoft Outlook.

Mail.ReadWrite

Delete contact

Deletes a contact in Microsoft Outlook.

Contacts.ReadWrite

Delete message

Deletes a message from the specified user's mailbox in Microsoft Outlook.

Mail.ReadWrite

Download message

Downloads a message from Microsoft Outlook in MIME format.

Mail.Read

Fetch all tasks

Fetches all tasks in a task list from Microsoft Outlook.

Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All

Fetch all user groups

Fetches all groups a user is a member of in Microsoft Outlook.

Delegated: User.Read.All; Application: Directory.Read.All

Fetch contacts

Fetches all contacts in Microsoft Outlook.

Contacts.Read

Fetch message by id

Fetches a message by its ID in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

Fetch messages

Fetches all messages in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

Fetch messages for mailbox

Fetches the messages of a mailbox in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

Fetch Messages using mailbox path

Fetches all messages from a mailbox folder path in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

Fetch task lists

Fetches all task lists from Microsoft Outlook.

Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All

Fetch user details

Retrieves user details from Microsoft Outlook.

Delegated: User.Read; Application: User.Read.All

Forward mail

Forwards a message in Microsoft Outlook.

Mail.Send

Get contact

Retrieves the properties and relationships of a contact in Microsoft Outlook.

Contacts.Read

Get Folder in Outlook

Gets the details of a specific folder in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

Get Item Attachment (Expanded & Flattened)

Retrieves an email attached to a message, with its nested attachments expanded and flattened into a list of messages and file attachments.

Mail.Read

Get messages delta

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)

Get Messages in Shared Mailbox

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)

List Categories

Gets all the categories defined for a user in Microsoft Outlook.

MailboxSettings.Read

List contacts

Retrieves the list of contacts in Microsoft Outlook.

Contacts.Read

List Folders

Gets all the mail folders in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

List folders in Microsoft Outlook

Lists all the mail folders in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

List group members

Fetches the members or owners of a group in Microsoft Outlook.

GroupMember.Read.All (or Group.Read.All)

List rules

Lists the message rules for a mail folder in Microsoft Outlook.

MailboxSettings.Read

List users

Lists users in Microsoft Outlook.

Delegated: User.ReadBasic.All (or User.Read.All); Application: User.Read.All

Move message

Moves a message to another folder within the specified user's mailbox.

Mail.ReadWrite

Retrieve Attachement

Retrieves an attachment of a message in Microsoft Outlook.

Mail.Read

Retrieve Message Attachments in File

Retrieves the attachments of a message in Microsoft Outlook, with their content as files.

Mail.Read

Retrieves list of attachements

Retrieves the list of attachments of a message in Microsoft Outlook.

Mail.Read

Search contacts

Fetches the contacts that match a query in Microsoft Outlook.

Contacts.Read

Search emails

Searches emails in Microsoft Outlook.

Mail.Read (delegated types only; Microsoft Search covers only the signed-in user's own mailbox)

Send draft message

Sends an existing draft (a new message, reply, reply-all or forward) and saves it in Sent Items.

Mail.Send

Send email

Sends an email from Microsoft Outlook.

Mail.ReadWrite and Mail.Send (the email is saved as a draft, then sent)

Send message reply

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)

Update contact

Updates a contact in Microsoft Outlook.

Contacts.ReadWrite

Update mail folder

Updates a mail folder in Microsoft Outlook.

Mail.ReadWrite

Update message

Updates a message in Microsoft Outlook.

Mail.ReadWrite

Fetch all task lists (delta)

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

Fetch task attachment details

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

Fetch task attachments

Fetches all attachments of a task in Microsoft Outlook.

Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All

Fetch task by ID

Fetches a single task by its ID in Microsoft Outlook.

Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All

Fetch task list by ID

Fetches a single task list by its ID in Microsoft Outlook.

Delegated: Tasks.Read (or Tasks.ReadWrite); Application: Tasks.Read.All

Get user

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

New Contact

Triggers when a new contact is created.

Contacts.Read

New Contact Created or Updated

Triggers when a contact is created or updated.

Contacts.Read

New email

Triggers when a new email arrives in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

New email (LEGACY)

Triggers when a new email arrives in Microsoft Outlook. Older version of New email.

Mail.ReadBasic (or Mail.Read)

New email in shared mailbox

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)

New mail

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

New mail (Event Hubs delivery)

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

New Starred Email

Triggers when an email is starred (flagged) in Microsoft Outlook.

Mail.ReadBasic (or Mail.Read)

On task created, updated or deleted

Triggers when a task is created, updated or deleted in a Microsoft Outlook task list.

Delegated: Tasks.ReadWrite; Application: Tasks.ReadWrite.All