# Microsoft Outlook

Send, find and organize mail in Outlook, work with drafts, attachments and folders, and manage calendar events and contacts.

## Connect Microsoft Outlook

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `microsoft outlook` and choose **Microsoft Outlook**.
3. Press **Sign in with Microsoft Outlook**, then choose your account in Microsoft Outlook’s window and allow access.

Before you sign in, the sheet asks:

- **Account type · Optional**: Which Microsoft accounts may sign in: common (work, school or personal; the default when empty), organizations (work or school only) or consumers (personal only). For your own app registered for one directory only (single tenant), its Directory (tenant) ID.

Microsoft Outlook works with work, school and personal Microsoft accounts (Microsoft 365, Outlook.com, Hotmail). It acts on the signed-in account’s own mailbox, calendars and contacts.

**What if it says “Microsoft Outlook sign-in isn’t set up here”?**

Signing in with Microsoft Outlook needs a Microsoft Outlook app on this installation, and it has none yet.

**On Cloud:** The sheet says “It’s set up once for everyone who uses this service, not by an organization.”

**Self-hosted:** An admin of the installation sees **Set up Microsoft Outlook sign-in** instead, and sets it up once for everyone. Everyone else sees who to ask.

1. Create an app in Microsoft Outlook’s developer settings ([Microsoft Outlook’s guide](https://learn.microsoft.com/entra/identity-platform/quickstart-register-app)).
2. In GoRunner, copy the **Redirect address to add in Microsoft Outlook’s developer settings**, and add it to the app.
3. Paste the **Client ID** and **Client secret**, then press **Save and sign in**.

[Set up a sign-in app](https://docs.gorunner.io/self-host/oauth-apps#other-providers)

**Can I use my own Microsoft Outlook app?**

Yes. In the sheet, open **Use your own Microsoft Outlook app** and paste its **Client ID** and **Client secret**. Add the redirect address it shows to your app first. The connection then signs in through your app instead of the installation’s.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Microsoft Outlook**. The trigger uses the same connection as the steps.

### On Message Received

Checks an Outlook folder about once a minute and starts a run for each email that arrived since the check before, oldest first. The first check after publishing only takes note of what is there (it starts nothing); changing the trigger starts over the same way. Only mail that arrives after that fires: an older message that is moved into the folder or marked unread does not.

- **Trigger on · Required**: What starts a run. Options: Message received. Default: Message received.
- **Folder · Optional**: The folder to watch (subfolders are not included). Default: inbox.
- **Read Status · Optional**: All new mail, or only what is still unread (or already read) when the check sees it. Options: All, Unread, Read. Default: All.
- **From · Optional**: Only mail from these addresses or domains (comma-separated; @contoso.com matches a whole domain).
- **Has Attachments · Optional**: Only mail with attachments. Off by default.
- **Include Body · Optional**: Also return each message's body (bodyPreview always has its start). Off by default.
- **Max Messages per Poll · Optional**: The most new messages one check starts runs for (1–50); any more come on the next check, oldest first. Default: 10.

A later step can use its data, such as `{{trigger.body}}`, `{{trigger.bodyPreview}}`, `{{trigger.change_type}}` and 7 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Microsoft Outlook

Add a **Microsoft Outlook** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Message](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-message): Send · Send and Wait for Approval · Reply · Forward · Get · Get Many · Update · Move · Delete
- [Draft](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-draft): Create · Get · Update · Send · Delete
- [Message Attachment](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-messageattachment): Add · Download · Get · Get Many
- [Folder](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-folder): Create · Get · Get Many · Update · Delete
- [Folder Message](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-foldermessage): Get Many
- [Calendar](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-calendar): Create · Get · Get Many · Update · Delete
- [Event](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-event): Create · Get · Get Many · Update · Respond to Invitation · Delete
- [Contact](https://docs.gorunner.io/apps/microsoft-outlook#fields-f-contact): Create · Get · Get Many · Update · Delete

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Microsoft Outlook can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Microsoft Outlook says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Microsoft Outlook is `pieceId: "microsoftoutlook"` with `actionId: "microsoftoutlook"`, set by `resource` and an `operation_…` field, such as `operation_calendar`. Its trigger is `outlooktrigger` / `outlook_message_received`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Microsoft Outlook › Message

### Send

- **To · Required**: Who receives the message. Separate several with commas or semicolons; "Name \<address>" works too.
- **Subject · Required**: The subject line.
- **Body · Optional**: The message's text (or HTML, with Body Format HTML).
- **Body Format · Optional**: Whether the body is plain text or HTML. Options: Text, HTML. Default: Text.
- **Attachments · Optional**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). Send takes up to 3 MB of files in all; Reply up to 150 MB each.
- **CC · Optional**: Copied recipients. Separate several with commas or semicolons; "Name \<address>" works too.
- **BCC · Optional**: Blind-copied recipients. Separate several with commas or semicolons; "Name \<address>" works too.
- **Reply To · Optional**: Where answers go, when not to you. Separate several with commas or semicolons; "Name \<address>" works too.
- **Importance · Optional**: Leave empty to keep Outlook's default (normal). Options: Low, Normal, High.
- **Save to Sent Items · Optional**: Keep a copy in Sent Items. On by default.

### Send and Wait for Approval

- **To · Required**: Who receives the message. Separate several with commas or semicolons; "Name \<address>" works too.
- **Subject · Required**: The subject line.
- **Message · Required**: What the approver is asked to decide; the Approve and Reject buttons are added below it.
- **Buttons · Optional**: Approve and Reject, or Approve only (an acknowledgement). Options: Approve and Reject, Approve only. Default: Approve and Reject.
- **Auto-continue after (timeout) · Optional**: Resume automatically after this long if no one answers (0 waits indefinitely). On timeout nobody answered, so branch on status == "approved". Default: 0.
- **Timeout Unit · Optional**: The unit of the time above. Options: Seconds, Minutes, Hours, Days. Default: Hours.
- **Public Base URL · Optional**: The address the Approve and Reject links open, when it is not this installation's public URL.

### Reply

- **Message ID · Required**: The message's id, such as from the trigger or from Get Many.
- **Message · Optional**: Your text, written above the quoted original.
- **Reply to Sender Only · Optional**: Answer only the sender. Off answers the sender and everyone else on the message (Reply All). Off by default.
- **Attachments · Optional**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). Send takes up to 3 MB of files in all; Reply up to 150 MB each.

### Forward

- **Message ID · Required**: The message's id, such as from the trigger or from Get Many.
- **To · Required**: Who receives the message. Separate several with commas or semicolons; "Name \<address>" works too.
- **Message · Optional**: Your text, written above the quoted original.

### Get

- **Message ID · Required**: The message's id, such as from the trigger or from Get Many.
- **Output · Optional**: Simple leaves out the body (bodyPreview has its start); Raw returns the whole message as Outlook sends it. Options: Simple, Raw. Default: Simple.
- **Download Attachments · Optional**: Also return each file attachment as a file object under files. Off by default.
- **Include the Message as .eml · Optional**: Also return the whole message in MIME format as a file object under mime. Off by default.

### Get Many

- **Folder · Optional**: Get Many: only this folder (empty searches the whole mailbox). Move: the folder to move the message to.
- **Output · Optional**: Simple leaves out the body (bodyPreview has its start); Raw returns the whole message as Outlook sends it. Options: Simple, Raw. Default: Simple.
- **Return All · Optional**: Read every message, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many messages to return (1–1000). Default: 50. Shows when **Return All** is off.
- **Read Status · Optional**: All mail, or only unread or read mail. Options: All, Unread, Read. Default: All.
- **From · Optional**: Only mail from this address.
- **Has Attachments · Optional**: Only mail with attachments. Off by default.
- **Received After · Optional**: Only mail received at or after this time.
- **Received Before · Optional**: Only mail received before this time.
- **Search · Optional**: Words to find in the subject, body or addresses, Outlook's way (subject:invoice, from:grace). Search replaces the filters above and sorts by Outlook's relevance.
- **OData Filter · Optional**: A Graph $filter of your own, added to the filters above, such as importance eq 'high'.

### Update

- **Message ID · Required**: The message's id, such as from the trigger or from Get Many.
- **Read · Optional**: Mark it read or unread; empty leaves it. Options: Read, Unread.
- **Flag · Optional**: Flag it for follow-up, mark the follow-up complete, or clear the flag; empty leaves it. Options: Flagged, Complete, Not flagged.
- **Categories · Optional**: Category names, comma-separated (they replace the message's categories).
- **Importance · Optional**: Leave empty to keep Outlook's default (normal). Options: Low, Normal, High.

### Move

- **Folder · Optional**: Get Many: only this folder (empty searches the whole mailbox). Move: the folder to move the message to.
- **Message ID · Required**: The message's id, such as from the trigger or from Get Many.

### Delete

- **Message ID · Required**: The message's id, such as from the trigger or from Get Many.

### Microsoft Outlook › Draft

### Create

- **Subject · Optional**: The subject line.
- **Body · Optional**: The message's text (or HTML, with Body Format HTML).
- **Body Format · Optional**: Whether the body is plain text or HTML. Options: Text, HTML. Default: Text.
- **To · Optional**: Who receives the message. Send: replaces the draft's recipients when filled. Separate several with commas or semicolons; "Name \<address>" works too.
- **Attachments · Optional**: Attach one file per row, or switch the field to an expression to pass a whole list from an earlier step (such as {{steps.unzip.files}}). Up to 150 MB each.
- **CC · Optional**: Copied recipients. Separate several with commas or semicolons; "Name \<address>" works too.
- **BCC · Optional**: Blind-copied recipients. Separate several with commas or semicolons; "Name \<address>" works too.
- **Reply To · Optional**: Where answers go, when not to you. Separate several with commas or semicolons; "Name \<address>" works too.
- **Importance · Optional**: Leave empty to keep Outlook's default (normal). Options: Low, Normal, High.

### Get

- **Draft ID · Required**: The draft's id (from Draft › Create).
- **Output · Optional**: Simple leaves out the body (bodyPreview has its start); Raw returns the whole message as Outlook sends it. Options: Simple, Raw. Default: Simple.

### Update

- **Draft ID · Required**: The draft's id (from Draft › Create).
- **Subject · Optional**: The subject line.
- **Body · Optional**: The message's text (or HTML, with Body Format HTML).
- **Body Format · Optional**: Whether the body is plain text or HTML. Options: Text, HTML. Default: Text.
- **To · Optional**: Who receives the message. Send: replaces the draft's recipients when filled. Separate several with commas or semicolons; "Name \<address>" works too.
- **CC · Optional**: Copied recipients. Separate several with commas or semicolons; "Name \<address>" works too.
- **BCC · Optional**: Blind-copied recipients. Separate several with commas or semicolons; "Name \<address>" works too.
- **Reply To · Optional**: Where answers go, when not to you. Separate several with commas or semicolons; "Name \<address>" works too.
- **Importance · Optional**: Leave empty to keep Outlook's default (normal). Options: Low, Normal, High.

### Send

- **Draft ID · Required**: The draft's id (from Draft › Create).
- **To · Optional**: Who receives the message. Send: replaces the draft's recipients when filled. Separate several with commas or semicolons; "Name \<address>" works too.

### Delete

- **Draft ID · Required**: The draft's id (from Draft › Create).

### Microsoft Outlook › Message Attachment

### Add

- **Message ID · Required**: The message or draft the attachment belongs to.
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). Up to 150 MB; files from 3 MB go up in parts.
- **File Name · Optional**: The attachment's name in Outlook; empty keeps the file's own.

### Download and Get

- **Message ID · Required**: The message or draft the attachment belongs to.
- **Attachment ID · Required**: The attachment's id, such as from Get Many.

### Get Many

- **Message ID · Required**: The message or draft the attachment belongs to.
- **Return All · Optional**: Read every attachment, page by page (at most 250; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many attachments to return (1–250). Default: 50. Shows when **Return All** is off.

### Microsoft Outlook › Folder

### Create

- **Parent Folder · Optional**: Create: make it inside this folder (empty: at the top level). Get Many: list this folder's subfolders (empty: the top level).
- **Name · Required**: The folder's name.

### Get and Delete

- **Folder · Required**: The folder.

### Get Many

- **Parent Folder · Optional**: Create: make it inside this folder (empty: at the top level). Get Many: list this folder's subfolders (empty: the top level).
- **Include Hidden Folders · Optional**: Also list folders hidden from Outlook's folder list. Off by default.
- **Return All · Optional**: Read every folder, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many folders to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Folder · Required**: The folder.
- **Name · Required**: The folder's name.

### Microsoft Outlook › Folder Message

### Get Many

- **Folder · Required**: The folder whose messages to read.
- **Output · Optional**: Simple leaves out the body (bodyPreview has its start); Raw returns the whole message as Outlook sends it. Options: Simple, Raw. Default: Simple.
- **Return All · Optional**: Read every message, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many messages to return (1–1000). Default: 50. Shows when **Return All** is off.
- **Read Status · Optional**: All mail, or only unread or read mail. Options: All, Unread, Read. Default: All.
- **From · Optional**: Only mail from this address.
- **Has Attachments · Optional**: Only mail with attachments. Off by default.
- **Received After · Optional**: Only mail received at or after this time.
- **Received Before · Optional**: Only mail received before this time.
- **Search · Optional**: Words to find in the subject, body or addresses, Outlook's way (subject:invoice, from:grace). Search replaces the filters above and sorts by Outlook's relevance.
- **OData Filter · Optional**: A Graph $filter of your own, added to the filters above, such as importance eq 'high'.

### Microsoft Outlook › Calendar

### Create

- **Name · Optional**: The calendar's name.
- **Color · Optional**: The calendar's color in Outlook; empty keeps Outlook's choice. Options: auto, lightBlue, lightGreen, lightOrange, lightGray, lightYellow, lightTeal, lightPink, lightBrown, lightRed.
- **Calendar Group ID · Optional**: Create: put it in this calendar group (empty: My Calendars).

### Get and Delete

- **Calendar · Required**: The calendar.

### Get Many

- **Return All · Optional**: Read every calendar, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many calendars to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Calendar · Required**: The calendar.
- **Name · Optional**: The calendar's name.
- **Color · Optional**: The calendar's color in Outlook; empty keeps Outlook's choice. Options: auto, lightBlue, lightGreen, lightOrange, lightGray, lightYellow, lightTeal, lightPink, lightBrown, lightRed.

### Microsoft Outlook › Event

### Create

- **Calendar · Optional**: Create: the calendar to add it to. Get Many: the calendar to read. Empty is your default calendar.
- **Subject · Optional**: The event's title.
- **Start · Optional**: When it starts: 2026-11-07T10:00 (in the Time Zone below) or with Z or an offset. Required to create.
- **End · Optional**: When it ends. Required to create.
- **Time Zone · Optional**: The zone of Start and End without an offset (such as Europe/Berlin, Pacific Standard Time); empty is UTC.
- **All Day · Optional**: An all-day event: Start and End are dates at midnight (End the day after the last day). Off by default.
- **Description · Optional**: The event's notes.
- **Body Format · Optional**: Whether the body is plain text or HTML. Options: Text, HTML. Default: Text.
- **Location · Optional**: Where it takes place.
- **Attendees · Optional**: Who is invited (they are sent the invitation). Separate several with commas or semicolons; "Name \<address>" works too.
- **Online Meeting · Optional**: Add a Teams meeting link (work or school accounts).
- **Show As · Optional**: Options: Free, Tentative, Busy, Away, Working elsewhere.
- **Importance · Optional**: Leave empty to keep Outlook's default (normal). Options: Low, Normal, High.
- **Sensitivity · Optional**: Options: Normal, Personal, Private, Confidential.
- **Reminder (minutes before) · Optional**
- **Categories · Optional**: Category names, comma-separated.

### Get and Delete

- **Event ID · Required**: The event's id, such as from Get Many.

### Get Many

- **Calendar · Optional**: Create: the calendar to add it to. Get Many: the calendar to read. Empty is your default calendar.
- **From · Optional**: With To: the events in this time range, recurring ones as their single occurrences. Empty lists the events as stored (a series once).
- **To · Optional**: The end of the time range.
- **Return All · Optional**: Read every event, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many events to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Event ID · Required**: The event's id, such as from Get Many.
- **Subject · Optional**: The event's title.
- **Start · Optional**: When it starts: 2026-11-07T10:00 (in the Time Zone below) or with Z or an offset. Required to create.
- **End · Optional**: When it ends. Required to create.
- **Time Zone · Optional**: The zone of Start and End without an offset (such as Europe/Berlin, Pacific Standard Time); empty is UTC.
- **All Day · Optional**: An all-day event: Start and End are dates at midnight (End the day after the last day). Off by default.
- **Description · Optional**: The event's notes.
- **Body Format · Optional**: Whether the body is plain text or HTML. Options: Text, HTML. Default: Text.
- **Location · Optional**: Where it takes place.
- **Attendees · Optional**: Who is invited (they are sent the invitation). Separate several with commas or semicolons; "Name \<address>" works too.
- **Online Meeting · Optional**: Add a Teams meeting link (work or school accounts).
- **Show As · Optional**: Options: Free, Tentative, Busy, Away, Working elsewhere.
- **Importance · Optional**: Leave empty to keep Outlook's default (normal). Options: Low, Normal, High.
- **Sensitivity · Optional**: Options: Normal, Personal, Private, Confidential.
- **Reminder (minutes before) · Optional**
- **Categories · Optional**: Category names, comma-separated.

### Respond to Invitation

- **Event ID · Required**: The event's id, such as from Get Many.
- **Response · Required**: Options: Accept, Tentative, Decline. Default: Accept.
- **Comment · Optional**: Text sent with the answer.
- **Notify the Organizer · Optional**: Send the answer to the organizer. On by default.

### Microsoft Outlook › Contact

### Create

- **First Name · Optional**: The contact's first name.
- **Last Name · Optional**: The contact's last name.
- **Email Addresses · Optional**: The contact's addresses (Outlook keeps up to three). Separate several with commas or semicolons; "Name \<address>" works too.
- **Business Phones · Optional**: Comma-separated.
- **Mobile Phone · Optional**
- **Company · Optional**
- **Job Title · Optional**
- **Notes · Optional**
- **Categories · Optional**: Category names, comma-separated.

### Get and Delete

- **Contact ID · Required**: The contact's id, such as from Get Many.

### Get Many

- **Email Address · Optional**: Get Many: only contacts with this address.
- **Return All · Optional**: Read every contact, page by page (at most 1000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many contacts to return (1–1000). Default: 50. Shows when **Return All** is off.

### Update

- **Contact ID · Required**: The contact's id, such as from Get Many.
- **First Name · Optional**: The contact's first name.
- **Last Name · Optional**: The contact's last name.
- **Email Addresses · Optional**: The contact's addresses (Outlook keeps up to three). Separate several with commas or semicolons; "Name \<address>" works too.
- **Business Phones · Optional**: Comma-separated.
- **Mobile Phone · Optional**
- **Company · Optional**
- **Job Title · Optional**
- **Notes · Optional**
- **Categories · Optional**: Category names, comma-separated.

Source: https://docs.gorunner.io/apps/microsoft-outlook