Outlook Connector

Overview

The Microsoft Outlook connector integrates Xurrent iPaaS runbooks with Microsoft 365 mailboxes. It reads email from user and shared mailboxes into Xurrent, sends email as those mailboxes, creates and deletes events in their calendars, and starts workflows when new mail arrives.

Status: The connector is published as Microsoft Outlook Connector.

The connector calls the Microsoft Graph API for its outbound actions and consumes Microsoft Graph change notifications for its inbound trigger.

It provides:

• Reading mail — list, search, and get messages from user and shared mailboxes.
• Sending mail — send a message as a mailbox.
• Attachments — list the attachments of a message and download file attachments.
• Organizing mail — move messages between folders and archive them.
• Calendar — create an event in a mailbox's calendar, with invitations to attendees, and delete it again.
• Triggers — start a workflow when a message arrives in a mailbox folder, kept alive by the Renew Subscriptions action.

Prerequisites

To use this connector, you need:

• A Microsoft Entra ID tenant with Exchange Online mailboxes.
• An app registration in Microsoft Entra (single tenant, no redirect URI). Obtain:
  • Tenant ID: Microsoft Entra admin center → Entra ID → Overview → Properties → Tenant ID.
  • Client ID: the Application (client) ID on the app registration's Overview page.
  • Client secret: created under Certificates & secrets → Client secrets. Copy the Value at creation time; it is not shown again. A secret lives at most 24 months.
• Application permissions for Microsoft Graph, granted on the app registration and consented by a Privileged Role Administrator or Global Administrator (see Authentication).

Authentication

The connector signs in as the application (OAuth 2.0 client credentials). No user logs in.

Field	Value
Tenant ID	The Directory (tenant) ID of your Microsoft Entra tenant, a GUID or a verified domain name.
Client ID	The Application (client) ID of the app registration.
Client secret	The client secret Value, stored as a secret.
Cloud	Selects the Microsoft login host and the Graph host together, used for token requests and API calls.
Default mailbox	Used when an action leaves its mailbox empty (see Mailbox identifiers). The connection's Test reads the inbox of this mailbox.

The token request goes to {login host}/{tenant_id}/oauth2/v2.0/token with the scope {graph host}/.default; both hosts follow the selected Cloud. Access tokens are cached until they expire and renewed automatically. When the client secret expires or is revoked, every job on the connection fails with Microsoft's own error text until a new secret is entered.

Microsoft Graph permissions

Grant these as Application permissions on the app registration. Grant only what the runbooks use:

Permission	Grants
Mail.Read	Read mail in every mailbox the app may reach.
Mail.ReadWrite	Move and update mail.
Mail.Send	Send mail as any mailbox.
Calendars.ReadWrite	Create and delete events in every calendar the app may reach.

The required permission depends on which trigger and actions you use:

Trigger / Action	Permission
New Email Received	Mail.Read
Renew Subscriptions	The read permission of what is watched: Mail.Read for a mailbox folder
List / Search / Get Email	Mail.Read
List Attachments / Download Attachment	Mail.Read
Send Email	Mail.Send
Move Email / Archive Email	Mail.ReadWrite
Create Calendar Event / Delete Calendar Event	Calendars.ReadWrite

Calendar-only connections: Test reads the inbox of the Default mailbox, so an app that holds Calendars.ReadWrite and no mail permission fails Test while its calendar actions work. Leave Default mailbox empty on such a connection, and name the mailbox on every step.

Restricting mailbox access (optional)

Limit the app to chosen mailboxes with RBAC for Applications in Exchange Online. The Entra grant and the Exchange grant add up, so remove the tenant-wide Entra grant when a scope should apply.

Mailbox identifiers

Every action names the mailbox it works on, as a user principal name, an object id, or an SMTP address. Microsoft documents the first two; an SMTP address works when it equals the user principal name, which is common but not guaranteed.

The Default mailbox on the connection is used when an action leaves its mailbox empty. The New Email Received trigger is the exception: it always needs a named mailbox.

Triggers

This connector provides one inbound trigger.

New Email Received

Starts a workflow when a message arrives in a folder of a mailbox, through Microsoft Graph change notifications.

Permission required: Mail.Read

Setting up the subscription

Deploying the solution records the mailbox and folder to watch on the connection, under the runbook of this trigger. Recording alone starts no delivery. The subscription is created, and then kept alive, by the Renew Subscriptions action:

• Put the Renew Subscriptions action in a runbook of its own, on a Scheduler trigger that runs every 15 minutes.
• Set that runbook's concurrency to one run at a time, so two runs never create the same subscription.
• Within 15 minutes of a deploy, or of a change to the mailbox or folder, a run creates the subscription. No step by hand is needed. A run renews the subscription a day before Microsoft would end it.
• A trigger that has gone quiet is repaired the same way: a run creates a subscription Microsoft no longer holds.

Removing the trigger

Deprovision the trigger in the designer before you delete its runbook. Deprovisioning deletes the subscription and its record, while deleting the runbook leaves both behind, and the renewal runbook keeps that subscription alive.

Delivery behavior

• Duplicates: Microsoft can deliver the same notification more than once, so a workflow that must act on a message exactly once checks the Message ID before it acts.
• Outages: An iPaaS outage long enough to time out deliveries makes Microsoft slow down or drop notifications to this endpoint for a while afterwards, and mail that arrives while deliveries are dropped is not delivered later.
• Batching: One request can carry several notifications, so one arrival of the trigger can report several messages.
• Message content: A notification carries the message id, not the message. A workflow that needs the subject or the body calls Get Email with that message id.

Input Parameters

Parameter	Type	Required	Default	Description
Mailbox	string	Yes	—	User principal name, object id or SMTP address. One subscription watches one named mailbox, so this trigger does not fall back to the connection's Default mailbox.
Folder	string	No	inbox	A well-known folder name such as inbox, archive, junkemail, or a folder id. Only mail that arrives in this folder starts a workflow.
URL postfix	string	No	—	Leave it empty. Microsoft sends its notifications to one address, so deploying refuses a postfix.

Output

Field	Type	Description
Messages	array	One entry per message in the request, each carrying Message ID, the id of the message that arrived. Read the list with the Flow connector's Loop action.
Mailbox	string	The mailbox the subscription watches.
Folder	string	The folder the subscription watches.
Subscription ID	string	The Microsoft subscription that sent the notification. One subscription sends every message in a request, so this names the request rather than a message.

Actions

Reading mail

List Emails

Returns one page of message summaries from a folder of a mailbox, newest first, through the list messages API.

Permission required: Mail.Read

The step repeats once per page, and steps placed inside it run for every page. The connector keeps the position between pages, so no page token is ever mapped by hand.

Input Parameters

Parameter	Type	Required	Default	Description
Mailbox	string	No	Default mailbox	User principal name, object id or SMTP address. Falls back to the connection's Default mailbox.
Folder	string	No	inbox	Pick a folder from the mailbox, or type a well-known folder name such as inbox, sentitems, archive, drafts, or a folder id (see the note below).
Page size	integer	No	25	How many messages one page holds (maximum 1000).
Page limit	integer	No	1	How many pages to fetch in total (maximum 100).
Fetch all pages	boolean	No	false	Ignore Page limit and keep going until the mailbox has no more messages.

Folder picker: The list reads the folders of the mailbox typed into Mailbox on this step. A Mailbox that carries a value from another step reaches the list as nothing, so the list then reads the connection's Default mailbox, as it does when Mailbox is empty. The list names every parent folder before the folder itself, and two folders can carry the same name: the value the step stores is the folder id, never the name.

Output

Messages (array of message summaries) and Has next page (boolean) — true while the step will run again for a further page.

Message summary fields: message id, subject, from (name and address), received date time, has attachments, is read, importance, body preview.

Search Emails

Returns the messages of a mailbox that match the criteria you give, in one bounded result set, through the list messages API.

Permission required: Mail.Read

The step runs once and returns every match it read, up to Result limit. Order is not guaranteed, so bound the range with Received after and Received before when the range matters. A message must match every criterion you filled. A criterion you leave empty narrows nothing.

Input Parameters

Parameter	Type	Required	Default	Description
Mailbox	string	No	Default mailbox	User principal name, object id or SMTP address. Falls back to the connection's Default mailbox.
Folder	string	No	—	A well-known folder name such as inbox, sentitems, archive, drafts, or a folder id. Empty searches the whole mailbox.
From address	string	No	—	Only messages sent by this address.
To address	string	No	—	Only messages addressed to this address. Microsoft Graph cannot filter on recipients, so this criterion is applied to the messages after they are read.
Subject contains	string	No	—	Only messages whose subject holds this text.
Received after	datetime	No	—	Only messages received at or after this moment.
Received before	datetime	No	—	Only messages received at or before this moment.
Has attachments	boolean	No	—	On returns only messages with an attachment, off only messages without one.
Is unread	boolean	No	—	On returns only unread messages, off only read ones.
Search text	string	No	—	Free text searched in the message content. Microsoft caps a free-text search at a few hundred messages and does not report that it did, so a search that fills this field can miss matches.
Page size	integer	No	25	How many messages one request to Microsoft reads (maximum 1000). It is not how many messages come back.
Result limit	integer	No	100	How many matching messages to return at most (maximum 1000). A run makes at most 50 requests to Microsoft, so a small Page size can stop it before this many are found.

Output

Messages (array of message summaries, same fields as List Emails) and More results exist (boolean).

More results exist is true when matches were left behind, because Result limit was reached, because the run stopped after its 50 requests, or because Microsoft cut a free-text search short.

Get Email

Returns one message with its body, through the get message API.

Permission required: Mail.Read

A message carries one body, either HTML or plain text, never both. The step asks Microsoft for the one it wants. Microsoft treats that as a preference, so the format it actually used comes back as an output field.

Input Parameters

Parameter	Type	Required	Default	Description
Message ID	string	Yes	—	The Message ID an earlier step returned. Ids are never built by hand.
Mailbox	string	No	Default mailbox	User principal name, object id or SMTP address. Falls back to the connection's Default mailbox.
Body format	string	No	HTML	HTML or Plain text.

Output

Everything List Emails returns for a message, plus Body (string) and the Body format (string) Microsoft used.

Sending mail

Send Email

Sends one message from a mailbox through the send mail API. Microsoft delivers it straight away, so nothing is left in Drafts and there is nothing to send later.

Permission required: Mail.Send

A message carries one body and one body type, never a plain text copy beside an HTML one. Attachments are not part of this release.

Input Parameters

Parameter	Type	Required	Default	Description
Mailbox	string	No	Default mailbox	The mailbox the message is sent from, as a user principal name, object id or SMTP address. Falls back to the connection's Default mailbox.
To	string	Yes	—	The recipient addresses.
Cc	string	No	—	The addresses that receive a copy.
Bcc	string	No	—	The addresses that receive a copy the other recipients do not see.
Subject	string	Yes	—	The subject line.
Body	string	Yes	—	The text of the message.
Body type	string	No	text	text keeps the line breaks as typed, html reads the body as markup.

Output

Sent (boolean) — true when Microsoft accepted the message.

Mailbox, To, Cc, Bcc, Subject — what was sent, so a later step can report it without mapping the same values again.

Attachments

List Attachments

Names the attachments of one message through the list attachments API.

Permission required: Mail.Read

The list carries the name and the size of every attachment, and the media type of a file. It never carries the file itself. A message attached to a message is listed too, with no media type, and Download Attachment refuses it because it holds no file. A workflow that needs a file calls Download Attachment with the attachment id from this list.

Input Parameters

Parameter	Type	Required	Default	Description
Message ID	string	Yes	—	The id of the message to read, as returned by List Emails.
Mailbox	string	No	Default mailbox	User principal name, object id or SMTP address. Falls back to the connection's Default mailbox.

Output

Attachments (array of attachment objects).

Attachment object fields: attachment id, name, content type, size in bytes, is inline.

Download Attachment

Reads one attachment of one message, with its bytes as base64 text, through the get attachment API.

Permission required: Mail.Read

Content bytes holds the base64 text Microsoft sends, not the raw file. A step that takes a file reads raw bytes, so map it through Base64.decode64 first, for example into Upload Attachment on the Xurrent connector:

Base64.decode64(action_output('download-attachment')&.drill(:content_bytes))

Mapping it straight across uploads the base64 text as the file.

Only a file attachment carries bytes. A message attached to a message (an item attachment) and a link to a cloud file (a reference attachment) hold none, so the step fails and says which kind it found.

Input Parameters

Parameter	Type	Required	Default	Description
Message ID	string	Yes	—	The id of the message that holds the attachment, as returned by List Emails.
Attachment ID	string	Yes	—	The id of the attachment, as returned by List Attachments.
Mailbox	string	No	Default mailbox	User principal name, object id or SMTP address. Falls back to the connection's Default mailbox.

Output

Field	Type	Description
Name	string	The file name Microsoft reports, such as report.pdf.
Content bytes	string	The file as base64 text, exactly as Microsoft sends it.
Content type	string	The media type of the file, such as application/pdf.

Organizing mail

Move Email

Moves one or more messages into another folder of the same mailbox, through the move message API.

Permission required: Mail.ReadWrite

Message IDs change: Moving a message gives it a new id. The id that went in stops working, so a later step that reads the message uses the New message ID this action returns.

Microsoft answers a move once per message, so one message can fail while the rest succeed. Every message id that went in comes back as its own row saying whether it moved.

Input Parameters

Parameter	Type	Required	Default	Description
Message IDs	array	Yes	—	The Message IDs an earlier step returned. Ids are never built by hand. At most 20 ids in one step.
Destination folder	string	Yes	—	A well-known folder name such as archive, deleteditems, junkemail, or a folder id. A display name such as Sent Items is not accepted. A folder that does not exist fails every row with Microsoft's Id is malformed, which is the same text a bad message id gets.
Mailbox	string	No	Default mailbox	User principal name, object id or SMTP address. Falls back to the connection's Default mailbox.

Output

Results (array) — one row per message id that went in, and a repeated id comes back once. A row that worked carries the new message id and no error. A row that failed carries the error text and no new message id.

Archive Email

Moves one or more messages into the archive folder of the mailbox, through the same move message API that Move Email uses.

Permission required: Mail.ReadWrite

The destination is fixed to the well-known archive folder. That is the one-click Archive folder in the mailbox, not the separate online archive mailbox, which Microsoft does not reach the same way.

Message IDs change: Archiving a message gives it a new id, exactly as Move Email does. The id that went in stops working, so a later step that reads the message uses the New message ID this action returns.

Input Parameters

Parameter	Type	Required	Default	Description
Message IDs	array	Yes	—	The Message IDs an earlier step returned. Ids are never built by hand. At most 20 ids in one step.
Mailbox	string	No	Default mailbox	User principal name, object id or SMTP address. Falls back to the connection's Default mailbox.

Output

Results (array) — one row per message id that went in, and a repeated id comes back once. A row that worked carries the new message id and no error. A row that failed carries the error text and no new message id.

Calendar

Create Calendar Event

Creates one event in a calendar of a mailbox, through the create event API. Microsoft sends an invitation to every attendee.

Permission required: Calendars.ReadWrite

Start and End are the local date and time in the zone named in Time zone, such as 2026-12-01 08:00 in W. Europe Standard Time. Microsoft applies that zone's clock changes, so the time stays the same in winter and in summer. A Start that does not exist in the zone, such as 02:30 on the night the clocks go forward, is moved later by Microsoft without an error, and Start and End in the output show the time Microsoft stored. When the moved Start falls after End, Microsoft refuses the event.

Repeated runs: A step that runs again creates a second event, unless it carries a Transaction ID. Microsoft remembers the Transaction ID of every event it holds: a second create with the same Transaction ID and the same values returns the event that exists, and one with different values fails. Map a value that is the same for one booking and different for the next one, such as the delivery id of the webhook that asked for the booking.

Input Parameters

Parameter	Type	Required	Default	Description
Mailbox	string	No	Default mailbox	The mailbox that owns the calendar and sends the invitations, as a user principal name, object id or SMTP address. Falls back to the connection's Default mailbox.
Calendar ID	string	No	Default calendar	The id of a calendar in the mailbox. Empty uses the default calendar of the mailbox. A read-only calendar, such as a holiday calendar, is refused by Microsoft.
Subject	string	Yes	—	The title of the event.
Start	string	Yes	—	The local date and time the event starts, written 2026-12-01 08:00 or 2026-12-01T08:00:00, with no offset and no Z (see the note below).
End	string	Yes	—	The local date and time the event ends, in the same form as Start. End may equal Start, and may not be earlier.
Time zone	string	Yes	—	The zone of Start and End, as a Windows name such as W. Europe Standard Time or an IANA name such as Europe/Zurich.
Body	string	No	—	The text of the event.
Body type	string	No	text	text keeps the line breaks as typed, html reads the body as markup.
Location	object	No	—	Display name, Street, Postal code and City. Only the fields that hold a value are sent.
Attendees	array	No	—	The addresses that receive the invitation, all as required attendees.
Reminder minutes before start	integer	No	—	Turns the reminder on that many minutes before Start. Empty leaves the choice to Microsoft, which turns a 15 minute reminder on.
Transaction ID	string	No	—	A value that makes a repeated create return the existing event instead of a second one. Empty sends none.

Times with an offset: Convert a time that carries an offset first, and name the same zone in Time zone, for example:

<value>.in_time_zone('Europe/Zurich').strftime('%Y-%m-%d %H:%M')

The conversion takes an IANA name only, and it needs a colon in the time: it reads 08.00 as midnight.

Output

Field	Type	Description
Event ID	string	The id that Delete Calendar Event takes.
Web link	string	Opens the event in Outlook on the web.
iCal UID	string	The id every calendar shares for this event, including the copies of the attendees.
Subject	string	The title of the event.
Start / End	object	Each a Date time and a Time zone, as Microsoft stored them.
Organizer	object	Name and address of the organizer.
Attendees	array	Address, name and type of each attendee.
Location	string	The location of the event.
Is reminder on	boolean	Whether a reminder is set.
Reminder minutes before start	integer	How many minutes before Start the reminder fires.
Created date time	datetime	When Microsoft created the event.
Mailbox	string	The mailbox that owns the calendar.

Delete Calendar Event

Deletes one event from the mailbox, through the delete event API. When the mailbox organised the event, Microsoft sends a cancellation to the attendees.

Permission required: Calendars.ReadWrite

An event that Microsoft does not find in the mailbox passes with Deleted false, so a cancel that arrives twice does not fail the second time. Deleted false says only that this mailbox held no such event when the step asked: an earlier delete removed it, an earlier try of this same step removed it before Microsoft answered with a server error, or the Event ID was never in this mailbox. An empty Event ID fails the step, because there is nothing to delete.

Input Parameters

Parameter	Type	Required	Default	Description
Event ID	string	Yes	—	The Event ID that Create Calendar Event returned.
Mailbox	string	No	Default mailbox	The mailbox that holds the event, as a user principal name, object id or SMTP address. Falls back to the connection's Default mailbox.

Output

Field	Type	Description
Deleted	boolean	True when this step deleted the event, false when the mailbox held no event with this id when the step asked.
Event ID	string	What the step asked Microsoft to delete.
Mailbox	string	The mailbox the step asked Microsoft to delete from.

Subscriptions

Renew Subscriptions

Creates and keeps alive every Microsoft Graph subscription the triggers on this connection depend on, through the subscription API.

Permission required: the read permission of what is watched, Mail.Read for a mailbox folder

Microsoft ends a subscription after seven days unless it is renewed. Put this action in a runbook of its own, on a Scheduler trigger that runs every 15 minutes, and set that runbook's concurrency to one run at a time, so two runs never create the same subscription.

Each run:

• lists the subscriptions Microsoft holds for this application,
• deletes any that points at a trigger of this connection but is not recorded,
• creates the subscription of every recorded trigger that has none, and
• renews, in batches of 20, every subscription that ends within a day.

So a trigger is watched within 15 minutes of its deploy, or of a change to its mailbox or folder, with no step by hand. A run with nothing to do ends quietly. A run in which a subscription could not be created or renewed fails after it has handled every other row, and its log names the trigger, what it watched and what Microsoft answered. The next run tries again.

Use the right connection: Use the Outlook connection the triggers use: a run on another connection finds nothing to keep alive. A Scheduler trigger keeps the recurrence it was first deployed with, so after changing it, deprovision and provision that trigger.

Input Parameters

None. The action reads the subscriptions the connection holds.

Output

Field	Type	Description
Results	array	One row per subscription the run touched, with Runbook ID, Resource, Mailbox, Folder, Subscription ID, Expires at, Outcome and Error. Outcome is created, renewed, removed for a subscription nobody recorded that the run deleted, or skipped for a trigger that changed while Microsoft was answering, with the reason in Error. A run in which a row failed ends with the failure instead of this output.
Created	integer	How many rows ended with created.
Renewed	integer	How many rows ended with renewed.
Removed	integer	How many rows ended with removed.

Best Practices

• Schedule the renewal runbook every 15 minutes, one run at a time. Renew Subscriptions creates the subscription of a newly deployed or changed New Email Received trigger within 15 minutes and keeps it alive; no run by hand is needed.
• Deprovision before deleting. Deprovision a New Email Received trigger in the designer before deleting its runbook, or the subscription stays alive.
• Deduplicate on Message ID. Notifications can arrive more than once; check the Message ID before acting when a message must be handled exactly once.
• Use the new Message ID after a move. Move Email and Archive Email give each message a new id; map the New message ID into later steps.
• Decode attachments before uploading. Pass Content bytes through Base64.decode64 before mapping it into a step that takes a file.
• Bound searches by date. Search Emails returns results in no guaranteed order and free-text search can miss matches; use Received after and Received before, and check More results exist.
• Use folder ids or well-known names. Display names such as Sent Items are not accepted as a destination folder.
• Set a Transaction ID on calendar events. Map a value unique to the booking, such as a webhook delivery id, so a repeated Create Calendar Event returns the existing event instead of creating a second one.
• Send local times to Create Calendar Event. Start and End take a local date and time with no offset; convert offset times with in_time_zone and name the same zone in Time zone.
• Grant only the permissions the runbooks use. A calendar-only app needs just Calendars.ReadWrite; leave Default mailbox empty on that connection, since Test reads its inbox.
• Scope the app to the mailboxes you need. Use RBAC for Applications in Exchange Online and remove the tenant-wide Entra grant (see Restricting mailbox access).
• Track the client secret's expiry. A secret lives at most 24 months; when it expires, every job on the connection fails.

Common Use Cases

• Email to Xurrent: New Email Received → Flow connector Loop over Messages → Get Email → create or update a Xurrent record.
• Carry attachments over: List Attachments → Download Attachment → Base64.decode64 → Upload Attachment on the Xurrent connector.
• Clean up after processing: Get Email → process → Archive Email (or Move Email to a processed folder).
• Mailbox sweep: Search Emails with sender, subject and date criteria → Move Email the matches.
• Outbound notifications: Xurrent event → Send Email from a shared mailbox.
• Book a meeting from a Xurrent record: Xurrent event (for example a change implementation window or a scheduled visit) → Create Calendar Event with attendees and a Transaction ID → store the Event ID on the record.
• Cancel a booking: Xurrent record cancelled or rescheduled → Delete Calendar Event with the stored Event ID; attendees receive a cancellation.
• Keep triggers alive: Scheduler every 15 minutes → Renew Subscriptions, in a runbook of its own with concurrency one run at a time.

References

Microsoft Graph API reference

• Microsoft Graph API
• List messages
• Get message
• Send mail
• List attachments
• Get attachment
• Move message
• Create event
• Delete event
• Subscription

Concepts

• Get access without a user
• Microsoft Graph permissions reference
• Microsoft Graph change notifications
• The date, time and time zone of an event

Setup

• Register an application with Microsoft Entra
• Role Based Access Control for Applications in Exchange Online