# Connect EMQX Agents to Outlook

The Outlook connector lets EMQX Agents work with Outlook email, mailbox folders, attachments, contacts, and calendar events. Use it to automate email and calendar workflows through an authorized Microsoft account.

## Common Use Cases

- Search an operations mailbox and summarize recent incident messages.
- Draft or send an email after an agent detects an abnormal condition.
- Create or update a maintenance calendar event.
- Read an attachment and use its content in a workflow.

Example chat prompt:

```text
Use the operations-outlook connector to find unread messages about device outages from the last 24 hours and create a summary. Do not send any email.
```

## Prerequisites

Before adding the connector, prepare:

- A Microsoft account with access to Outlook.
- Permission to authorize the required mail, contact, and calendar operations.
- Access to any shared mailbox, calendar, contact folder, or attachment required by the workflow.

## Add an Outlook Connector

1. In the left navigation menu, click **Connectors**.
2. On the **Available** tab, locate **Outlook** and click **Add**.
3. Enter a descriptive connector name.
4. Click **Confirm**. The Microsoft authorization flow opens in a dialog.
5. Select the Microsoft account to connect, or select **Use another account**.
6. Wait for the authorization dialog to close and return to EMQX Agents.
7. On the **Added** tab, verify that the connector status is **Authorized**.

<!-- TODO: Confirm the Microsoft OAuth scopes, tenant consent requirements, shared mailbox support, and whether mail or calendar write operations require per-action approval. -->

## Supported Tools

### Calendar

| Tool | Access | Description |
|---|---|---|
| `OUTLOOK_ACCEPT_EVENT` | Write | Accepts a calendar event invitation. |
| `OUTLOOK_CANCEL_EVENT` | Destructive | Cancels a calendar event. |
| `OUTLOOK_GET_CALENDAR_VIEW` | Read | Gets events that occur or overlap within a time range. |
| `OUTLOOK_LIST_EVENTS` | Read | Lists calendar events. |
| `OUTLOOK_LIST_USER_CALENDAR_VIEW` | Read | Gets events in a user's calendar within a time range. |
| `OUTLOOK_SEARCH_EVENTS` | Read | Searches calendar events. |
| `OUTLOOK_CALENDAR_CREATE_EVENT` | Write | Creates an event in the default calendar. |
| `OUTLOOK_CREATE_CALENDAR_EVENT_IN_CALENDAR` | Write | Creates an event in a selected calendar. |
| `OUTLOOK_UPDATE_CALENDAR_EVENT` | Write | Updates an event in the default calendar. |
| `OUTLOOK_UPDATE_CALENDAR_EVENT_IN_CALENDAR` | Write | Updates an event in a selected calendar. |

### Send Mail and Manage Drafts

| Tool | Access | Description |
|---|---|---|
| `OUTLOOK_CREATE_DRAFT` | Write | Creates an email draft with recipients, subject, body, or attachments. |
| `OUTLOOK_CREATE_DRAFT_REPLY` | Write | Creates a reply draft for a message. |
| `OUTLOOK_REPLY_EMAIL` | Write | Replies to an email. |
| `OUTLOOK_SEND_DRAFT` | Write | Sends an email draft. |
| `OUTLOOK_SEND_EMAIL` | Write | Sends an email through Outlook. |

### Mailbox Folders

| Tool | Access | Description |
|---|---|---|
| `OUTLOOK_GET_MAIL_FOLDER` | Read | Gets a mailbox folder. |
| `OUTLOOK_GET_MAIL_FOLDER_MESSAGE` | Read | Gets a message from a selected mailbox folder. |
| `OUTLOOK_LIST_MAIL_FOLDER_MESSAGES` | Read | Lists messages in a mailbox folder. |
| `OUTLOOK_LIST_MAIL_FOLDERS` | Read | Lists mailbox folders. |

### Read and Manage Mail

| Tool | Access | Description |
|---|---|---|
| `OUTLOOK_MOVE_MESSAGE` | Write | Moves a message to another mailbox folder. |
| `OUTLOOK_UPDATE_EMAIL` | Write | Updates message properties. |
| `OUTLOOK_GET_ME_MESSAGE_MIME_CONTENT` | Read | Gets the MIME content of a message. |
| `OUTLOOK_GET_MESSAGE` | Read | Gets a message by message ID. |
| `OUTLOOK_LIST_MESSAGES` | Read | Lists messages in the mailbox. |
| `OUTLOOK_LIST_SENT_ITEMS_MESSAGES` | Read | Lists sent messages. |
| `OUTLOOK_QUERY_EMAILS` | Read | Queries messages in a folder by using OData conditions. |
| `OUTLOOK_SEARCH_MESSAGES` | Read | Searches a mailbox by using KQL. |

### Attachments

| Tool | Access | Description |
|---|---|---|
| `OUTLOOK_DOWNLOAD_OUTLOOK_ATTACHMENT` | Read | Downloads an email attachment. |
| `OUTLOOK_GET_USER_MESSAGES_ATTACHMENTS` | Read | Gets attachment information for a message. |

### Contacts and User

| Tool | Access | Description |
|---|---|---|
| `OUTLOOK_CREATE_CONTACT` | Write | Creates a contact in an Outlook contact folder. |
| `OUTLOOK_LIST_USER_CONTACTS` | Read | Lists contacts for a user. |
| `OUTLOOK_UPDATE_CONTACT` | Write | Updates a contact. |
| `OUTLOOK_GET_PROFILE` | Read | Gets an Outlook user profile. |

::: warning Important Notice
Email send and reply tools communicate externally. Calendar cancellation and update tools change attendee schedules. Message move and update tools change mailbox state.
:::

## Use the Connector in a Chat

1. In the chat input area, click the connector icon.
2. Select the authorized **Outlook** connector.
3. In the prompt, identify the external resource and operation that the agent should use.
4. Review the generated agent definition and confirm that it contains only the required tools.

## Permissions and Data Access

The connector uses the authorized Microsoft account. Microsoft 365 tenant policies, mailbox permissions, calendar sharing, and contact folder access determine available resources and operations.

Do not include external service credentials or access tokens in the chat prompt or agent instructions.

## Limitations

- Microsoft Graph API quotas and Microsoft 365 tenant policies apply.
- Shared mailbox and delegated calendar access can require administrator configuration.
- Message search behavior differs between OData queries and KQL search.

<!-- TODO: Confirm service-specific result size limits, file limits, API rate limits, plan restrictions, and unsupported resource types. -->

## Troubleshooting

| Symptom | Resolution |
|---|---|
| The connector remains **Unauthorized**. | Retry authorization and select the Microsoft account to connect. |
| A tool returns a permission error. | Verify the authorized account's access to the target resource and operation. |
| A required tool is unavailable. | Verify that the tool is supported and approved for this connector, then select the connector again in the chat. |
| Requests are rejected intermittently. | Check the external service status, API quota, rate limits, and account plan. |

## Related Links

- [Connectors](../connectors.md)
- [Start a Chat](../chats.md)
- [Manage Agents](../agents.md)