---
title: Microsoft Outlook Integration
description: "Email, calendar, and contact management with Microsoft Outlook integration for CrewAI."
icon: "envelope"
mode: "wide"
---

## Overview

Enable your agents to access and manage Outlook emails, calendar events, and contacts. Send emails, retrieve messages, manage calendar events, and organize contacts with AI-powered automation.

## Prerequisites

Before using the Microsoft Outlook integration, ensure you have:

- A [CrewAI AMP](https://app.crewai.com) account with an active subscription
- A Microsoft account with Outlook access
- Connected your Microsoft account through the [Integrations page](https://app.crewai.com/crewai_plus/connectors)

## Setting Up Microsoft Outlook Integration

### 1. Connect Your Microsoft Account

1. Navigate to [CrewAI AMP Integrations](https://app.crewai.com/crewai_plus/connectors)
2. Find **Microsoft Outlook** in the Authentication Integrations section
3. Click **Connect** and complete the OAuth flow
4. Grant the necessary permissions for mail, calendar, and contact access
5. Copy your Enterprise Token from [Integration Settings](https://app.crewai.com/crewai_plus/settings/integrations)

### 2. Install Required Package

```bash
uv add crewai-tools
```

### 3. Environment Variable Setup

<Note>
  To use integrations with `Agent(apps=[])`, you must set the
  `CREWAI_PLATFORM_INTEGRATION_TOKEN` environment variable with your Enterprise
  Token.
</Note>

```bash
export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token"
```

Or add it to your `.env` file:

```
CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token
```

## Available Actions

<AccordionGroup>
  <Accordion title="microsoft_outlook/get_messages">
    **Description:** Get email messages from the user's mailbox.

    **Parameters:**
    - `top` (integer, optional): Number of messages to retrieve (max 1000). Default is `10`.
    - `filter` (string, optional): OData filter expression (e.g., "isRead eq false").
    - `search` (string, optional): Search query string.
    - `orderby` (string, optional): Order by field (e.g., "receivedDateTime desc"). Default is "receivedDateTime desc".
    - `select` (string, optional): Select specific properties to return.
    - `expand` (string, optional): Expand related resources inline.

  </Accordion>

  <Accordion title="microsoft_outlook/send_email">
    **Description:** Send an email message.

    **Parameters:**
    - `to_recipients` (array, required): Array of recipient email addresses.
    - `cc_recipients` (array, optional): Array of CC recipient email addresses.
    - `bcc_recipients` (array, optional): Array of BCC recipient email addresses.
    - `subject` (string, required): Email subject.
    - `body` (string, required): Email body content.
    - `body_type` (string, optional): Body content type. Enum: `Text`, `HTML`. Default is `HTML`.
    - `importance` (string, optional): Message importance level. Enum: `low`, `normal`, `high`. Default is `normal`.
    - `reply_to` (array, optional): Array of reply-to email addresses.
    - `save_to_sent_items` (boolean, optional): Whether to save the message to Sent Items folder. Default is `true`.

  </Accordion>

  <Accordion title="microsoft_outlook/get_calendar_events">
    **Description:** Get calendar events from the user's calendar.

    **Parameters:**
    - `top` (integer, optional): Number of events to retrieve (max 1000). Default is `10`.
    - `skip` (integer, optional): Number of events to skip. Default is `0`.
    - `filter` (string, optional): OData filter expression (e.g., "start/dateTime ge '2024-01-01T00:00:00Z'").
    - `orderby` (string, optional): Order by field (e.g., "start/dateTime asc"). Default is "start/dateTime asc".

  </Accordion>

  <Accordion title="microsoft_outlook/create_calendar_event">
    **Description:** Create a new calendar event.

    **Parameters:**
    - `subject` (string, required): Event subject/title.
    - `body` (string, optional): Event body/description.
    - `start_datetime` (string, required): Start date and time in ISO 8601 format (e.g., '2024-01-20T10:00:00').
    - `end_datetime` (string, required): End date and time in ISO 8601 format.
    - `timezone` (string, optional): Time zone (e.g., 'Pacific Standard Time'). Default is `UTC`.
    - `location` (string, optional): Event location.
    - `attendees` (array, optional): Array of attendee email addresses.

  </Accordion>

  <Accordion title="microsoft_outlook/get_contacts">
    **Description:** Get contacts from the user's address book.

    **Parameters:**
    - `top` (integer, optional): Number of contacts to retrieve (max 1000). Default is `10`.
    - `skip` (integer, optional): Number of contacts to skip. Default is `0`.
    - `filter` (string, optional): OData filter expression.
    - `orderby` (string, optional): Order by field (e.g., "displayName asc"). Default is "displayName asc".

  </Accordion>

  <Accordion title="microsoft_outlook/create_contact">
    **Description:** Create a new contact in the user's address book.

    **Parameters:**
    - `displayName` (string, required): Contact's display name.
    - `givenName` (string, optional): Contact's first name.
    - `surname` (string, optional): Contact's last name.
    - `emailAddresses` (array, optional): Array of email addresses. Each item is an object with `address` (string) and `name` (string).
    - `businessPhones` (array, optional): Array of business phone numbers.
    - `homePhones` (array, optional): Array of home phone numbers.
    - `jobTitle` (string, optional): Contact's job title.
    - `companyName` (string, optional): Contact's company name.

  </Accordion>

  <Accordion title="microsoft_outlook/get_message">
    **Description:** Get a specific email message by ID.

    **Parameters:**
    - `message_id` (string, required): The unique identifier of the message. Obtain from get_messages action.
    - `select` (string, optional): Comma-separated list of properties to return. Example: "id,subject,body,from,receivedDateTime". Default is "id,subject,body,from,toRecipients,receivedDateTime".

  </Accordion>

  <Accordion title="microsoft_outlook/reply_to_email">
    **Description:** Reply to an email message.

    **Parameters:**
    - `message_id` (string, required): The unique identifier of the message to reply to. Obtain from get_messages action.
    - `comment` (string, required): The reply message content. Can be plain text or HTML. The original message will be quoted below this content.

  </Accordion>

  <Accordion title="microsoft_outlook/forward_email">
    **Description:** Forward an email message.

    **Parameters:**
    - `message_id` (string, required): The unique identifier of the message to forward. Obtain from get_messages action.
    - `to_recipients` (array, required): Array of recipient email addresses to forward to. Example: ["john@example.com", "jane@example.com"].
    - `comment` (string, optional): Optional message to include above the forwarded content. Can be plain text or HTML.

  </Accordion>

  <Accordion title="microsoft_outlook/mark_message_read">
    **Description:** Mark a message as read or unread.

    **Parameters:**
    - `message_id` (string, required): The unique identifier of the message. Obtain from get_messages action.
    - `is_read` (boolean, required): Set to true to mark as read, false to mark as unread.

  </Accordion>

  <Accordion title="microsoft_outlook/delete_message">
    **Description:** Delete an email message.

    **Parameters:**
    - `message_id` (string, required): The unique identifier of the message to delete. Obtain from get_messages action.

  </Accordion>

  <Accordion title="microsoft_outlook/update_event">
    **Description:** Update an existing calendar event.

    **Parameters:**
    - `event_id` (string, required): The unique identifier of the event. Obtain from get_calendar_events action.
    - `subject` (string, optional): New subject/title for the event.
    - `start_time` (string, optional): New start time in ISO 8601 format (e.g., "2024-01-20T10:00:00"). REQUIRED: Must also provide start_timezone when using this field.
    - `start_timezone` (string, optional): Timezone for start time. REQUIRED when updating start_time. Examples: "Pacific Standard Time", "Eastern Standard Time", "UTC".
    - `end_time` (string, optional): New end time in ISO 8601 format. REQUIRED: Must also provide end_timezone when using this field.
    - `end_timezone` (string, optional): Timezone for end time. REQUIRED when updating end_time. Examples: "Pacific Standard Time", "Eastern Standard Time", "UTC".
    - `location` (string, optional): New location for the event.
    - `body` (string, optional): New body/description for the event. Supports HTML formatting.

  </Accordion>

  <Accordion title="microsoft_outlook/delete_event">
    **Description:** Delete a calendar event.

    **Parameters:**
    - `event_id` (string, required): The unique identifier of the event to delete. Obtain from get_calendar_events action.

  </Accordion>
</AccordionGroup>

## Usage Examples

### Basic Microsoft Outlook Agent Setup

```python
from crewai import Agent, Task, Crew

# Create an agent with Microsoft Outlook capabilities
outlook_agent = Agent(
    role="Email Assistant",
    goal="Manage emails, calendar events, and contacts efficiently",
    backstory="An AI assistant specialized in Microsoft Outlook operations and communication management.",
    apps=['microsoft_outlook']  # All Outlook actions will be available
)

# Task to send an email
send_email_task = Task(
    description="Send an email to 'colleague@example.com' with subject 'Project Update' and body 'Hi, here is the latest project update. Best regards.'",
    agent=outlook_agent,
    expected_output="Email sent successfully to colleague@example.com"
)

# Run the task
crew = Crew(
    agents=[outlook_agent],
    tasks=[send_email_task]
)

crew.kickoff()
```

### Email Management and Search

```python
from crewai import Agent, Task, Crew

# Create an agent focused on email management
email_manager = Agent(
    role="Email Manager",
    goal="Retrieve, search, and organize email messages",
    backstory="An AI assistant skilled in email organization and management.",
    apps=['microsoft_outlook/get_messages']
)

# Task to search and retrieve emails
search_emails_task = Task(
    description="Get the latest 20 unread emails and provide a summary of the most important ones.",
    agent=email_manager,
    expected_output="Summary of the most important unread emails with key details."
)

crew = Crew(
    agents=[email_manager],
    tasks=[search_emails_task]
)

crew.kickoff()
```

### Calendar and Contact Management

```python
from crewai import Agent, Task, Crew

# Create an agent for calendar and contact management
scheduler = Agent(
    role="Calendar and Contact Manager",
    goal="Manage calendar events and maintain contact information",
    backstory="An AI assistant that handles scheduling and contact organization.",
    apps=['microsoft_outlook/create_calendar_event', 'microsoft_outlook/get_calendar_events', 'microsoft_outlook/create_contact']
)

# Task to create a meeting and add a contact
schedule_task = Task(
    description="Create a calendar event for tomorrow at 2 PM titled 'Team Meeting' with location 'Conference Room A', and create a new contact for 'John Smith' with email 'john.smith@example.com' and job title 'Project Manager'.",
    agent=scheduler,
    expected_output="Calendar event created and new contact added successfully."
)

crew = Crew(
    agents=[scheduler],
    tasks=[schedule_task]
)

crew.kickoff()
```

## Troubleshooting

### Common Issues

**Authentication Errors**

- Ensure your Microsoft account has the necessary permissions for mail, calendar, and contact access.
- Required scopes include: `Mail.Read`, `Mail.Send`, `Calendars.Read`, `Calendars.ReadWrite`, `Contacts.Read`, `Contacts.ReadWrite`.
- Verify that the OAuth connection includes all required scopes.

**Email Sending Issues**

- Ensure `to_recipients`, `subject`, and `body` are provided for `send_email`.
- Check that email addresses are properly formatted.
- Verify that the account has `Mail.Send` permissions.

**Calendar Event Creation**

- Ensure `subject`, `start_datetime`, and `end_datetime` are provided.
- Use proper ISO 8601 format for datetime fields (e.g., '2024-01-20T10:00:00').
- Verify timezone settings if events appear at incorrect times.

**Contact Management**

- For `create_contact`, ensure `displayName` is provided as it's required.
- When providing `emailAddresses`, use the proper object format with `address` and `name` properties.

**Search and Filter Issues**

- Use proper OData syntax for `filter` parameters.
- For date filters, use ISO 8601 format (e.g., "receivedDateTime ge '2024-01-01T00:00:00Z'").

### Getting Help

<Card title="Need Help?" icon="headset" href="mailto:support@crewai.com">
  Contact our support team for assistance with Microsoft Outlook integration
  setup or troubleshooting.
</Card>