Microsoft Outlook Integration - Crewai

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 account with an active subscription
A Microsoft account with Outlook access
Connected your Microsoft account through the Integrations page

Setting Up Microsoft Outlook Integration

1. Connect Your Microsoft Account

Navigate to CrewAI AMP Integrations
Find Microsoft Outlook in the Authentication Integrations section
Click Connect and complete the OAuth flow
Grant the necessary permissions for mail, calendar, and contact access
Copy your Enterprise Token from Integration Settings

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: ["[email protected]", "[email protected]"].
- `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 '[email protected]' with subject 'Project Update' and body 'Hi, here is the latest project update. Best regards.'",
    agent=outlook_agent,
    expected_output="Email sent successfully to [email protected]"
)

# 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 '[email protected]' 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:[email protected]"> Contact our support team for assistance with Microsoft Outlook integration setup or troubleshooting. </Card>