> **Building with AI coding agents?** If you're using an AI coding agent, install the official Scalekit plugin. It gives your agent full awareness of the Scalekit API — reducing hallucinations and enabling faster, more accurate code generation.
>
> - **Claude Code**: `/plugin marketplace add scalekit-inc/claude-code-authstack` then `/plugin install <auth-type>@scalekit-auth-stack`
> - **GitHub Copilot CLI**: `copilot plugin marketplace add scalekit-inc/github-copilot-authstack` then `copilot plugin install <auth-type>@scalekit-auth-stack`
> - **Codex**: run the bash installer, restart, then open Plugin Directory and enable `<auth-type>`
> - **Skills CLI** (Windsurf, Cline, 40+ agents): `npx skills add scalekit-inc/skills --list` then `--skill <skill-name>`
>
> `<auth-type>` / `<skill-name>`: `agentkit`, `full-stack-auth`, `mcp-auth`, `modular-sso`, `modular-scim` — [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Outlook

**Authentication:** OAuth 2.0
**Categories:** Communication
## What you can do

Connect this agent connector to let your agent:

- **Delete todo tasks, todo lists, delete** — Permanently delete a task from a Microsoft To Do task list
- **Update todo tasks, todo lists, mailbox settings** — Update a task in a Microsoft To Do task list
- **Get todo tasks, todo lists, mailbox settings** — Get a specific task from a Microsoft To Do task list
- **Create todo tasks, todo lists, create** — Create a new task in a Microsoft To Do task list with optional body, due date, importance, and reminder
- **List todo tasks, todo lists, list** — List all tasks in a Microsoft To Do task list with optional filtering and pagination
- **Message reply to** — Reply to an existing email message

## Authentication

This connector uses **OAuth 2.0**. Scalekit acts as the OAuth client: it redirects your user to Outlook, obtains an access token, and automatically refreshes it before it expires. Your agent code never handles tokens directly — you only pass a `connectionName` and a user `identifier`.

You supply your Outlook **Connected App** credentials (Client ID + Secret) once per environment in the Scalekit dashboard.

Before calling this connector from your code, create the Outlook connection in **AgentKit** > **Connections** and copy the exact **Connection name** from that connection into your code. The value in code must match the dashboard exactly.

## Set up the connector

Register your Scalekit environment with the Outlook connector so Scalekit handles the authentication flow and token lifecycle for you. The connection name you create will be used to identify and invoke the connection programmatically. Then complete the configuration in your application as follows:

1. ### Create the Outlook connection in Scalekit

   - In [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Connections** > **Create Connection**. Search for **Outlook** and click **Create**.

     > Image: Search for Outlook and create a new connection

   - In the **Configure Outlook Connection** dialog, copy the **Redirect URI**. You will need this when registering your app in Azure.

     > Image: Copy the redirect URI from the Configure Outlook Connection dialog

2. ### Register an application in Azure

   - Sign into [portal.azure.com](https://portal.azure.com) and go to **Microsoft Entra ID** → **App registrations**.

     > Image: App registrations page in Azure portal

   - Click **New registration**. Enter a name for your app (for example, "Scalekit Outlook Connector").

   - Under **Supported account types**, select **Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts**.

   - Under **Redirect URI**, select **Web** and paste the redirect URI you copied from the Scalekit dashboard. Click **Register**.

     > Image: Paste the Scalekit redirect URI in Azure

3. ### Get your client credentials

   - From the app's **Overview** page, copy the **Application (client) ID**.

     > Image: Copy the Application (client) ID from the Azure app overview

   - Go to **Certificates & secrets** in the left sidebar, then click **+ New client secret**.

     > Image: Certificates and secrets page in Azure portal

   - Enter a description (for example, "Secret for Scalekit Agent Actions"), set an expiry period, and click **Add**. Copy the secret **Value** immediately — it is only shown once.

     > Image: Add a client secret in Azure portal

4. ### Add credentials in Scalekit

   - In [Scalekit dashboard](https://app.scalekit.com), go to **AgentKit** > **Connections** and open the Outlook connection you created.

   - Enter your credentials:
     - **Client ID** — the Application (client) ID from the Azure app overview
     - **Client Secret** — the secret value from Certificates & secrets
     - **Scopes** — select the permissions your app needs (for example, `Calendars.Read`, `Calendars.ReadWrite`, `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`, `Contacts.Read`, `Contacts.ReadWrite`, `User.Read`, `offline_access`). See [Microsoft Graph permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference) for the full list.

   - Click **Save**.

## Code examples

Connect a user's Outlook account and make API calls on their behalf — Scalekit handles OAuth and token management automatically.

## Proxy API Calls

  ### Node.js

```typescript

const connectionName = 'outlook'; // get your connection name from connection configurations
const identifier = 'user_123';  // your unique user identifier

// Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENV_URL,
  process.env.SCALEKIT_CLIENT_ID,
  process.env.SCALEKIT_CLIENT_SECRET
);
const actions = scalekit.actions;

// Authenticate the user
const { link } = await actions.getAuthorizationLink({
  connectionName,
  identifier,
});
console.log('🔗 Authorize Outlook:', link);
process.stdout.write('Press Enter after authorizing...');
await new Promise(r => process.stdin.once('data', r));

// Make a request via Scalekit proxy
const result = await actions.request({
  connectionName,
  identifier,
  path: '/v1.0/me/messages',
  method: 'GET',
});
console.log(result);
```

  ### Python

```python

from dotenv import load_dotenv
load_dotenv()

connection_name = "outlook"  # get your connection name from connection configurations
identifier = "user_123"     # your unique user identifier

# Get your credentials from app.scalekit.com → Developers → Settings → API Credentials
scalekit_client = scalekit.client.ScalekitClient(
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
    env_url=os.getenv("SCALEKIT_ENV_URL"),
)
actions = scalekit_client.actions

# Authenticate the user
link_response = actions.get_authorization_link(
    connection_name=connection_name,
    identifier=identifier
)
# present this link to your user for authorization, or click it yourself for testing
print("🔗 Authorize Outlook:", link_response.link)
input("Press Enter after authorizing...")

# Make a request via Scalekit proxy
result = actions.request(
    connection_name=connection_name,
    identifier=identifier,
    path="/v1.0/me/messages",
    method="GET"
)
print(result)
```

## Tool list

Use the exact tool names from the **Tool list** below when you call `execute_tool`. If you're not sure which name to use, list the tools available for the current user first.

## Tool list

### `outlook_create_calendar_event`

Create a new calendar event in the user's Outlook calendar. Supports attendees, recurrence, reminders, online meetings, multiple locations, and event properties.

Parameters:

- `end_datetime` (`string`, required): No description.
- `end_timezone` (`string`, required): No description.
- `start_datetime` (`string`, required): No description.
- `start_timezone` (`string`, required): No description.
- `subject` (`string`, required): No description.
- `attendees_optional` (`string`, optional): Array of email addresses for optional attendees
- `attendees_required` (`string`, optional): Array of email addresses for required attendees
- `attendees_resource` (`string`, optional): Array of email addresses for resources (meeting rooms, equipment)
- `body_content` (`string`, optional): No description.
- `body_contentType` (`string`, optional): No description.
- `hideAttendees` (`boolean`, optional): When true, each attendee only sees themselves
- `importance` (`string`, optional): Event importance level
- `isAllDay` (`boolean`, optional): Mark as all-day event
- `isOnlineMeeting` (`boolean`, optional): Create an online meeting (Teams/Skype)
- `isReminderOn` (`boolean`, optional): Enable or disable reminder
- `location` (`string`, optional): No description.
- `locations` (`string`, optional): JSON array of location objects with displayName, address, coordinates
- `onlineMeetingProvider` (`string`, optional): Online meeting provider
- `recurrence_days_of_week` (`string`, optional): Days of week for weekly recurrence (comma-separated)
- `recurrence_end_date` (`string`, optional): End date for recurrence (YYYY-MM-DD), required if range_type is endDate
- `recurrence_interval` (`integer`, optional): How often the event recurs (e.g., every 2 weeks = 2)
- `recurrence_occurrences` (`integer`, optional): Number of occurrences, required if range_type is numbered
- `recurrence_range_type` (`string`, optional): How the recurrence ends
- `recurrence_start_date` (`string`, optional): Start date for recurrence (YYYY-MM-DD)
- `recurrence_type` (`string`, optional): Recurrence pattern type
- `reminderMinutesBeforeStart` (`integer`, optional): Minutes before event start to show reminder
- `sensitivity` (`string`, optional): Event sensitivity/privacy level
- `showAs` (`string`, optional): Free/busy status

### `outlook_create_contact`

Create a new contact in the user's mailbox with name, email addresses, and phone numbers.

Parameters:

- `givenName` (`string`, required): First name of the contact
- `surname` (`string`, required): Last name of the contact
- `businessPhones` (`array`, optional): Array of business phone numbers
- `companyName` (`string`, optional): Company name
- `emailAddresses` (`array`, optional): Array of email address objects with 'address' and optional 'name' fields
- `jobTitle` (`string`, optional): Job title
- `mobilePhone` (`string`, optional): Mobile phone number

### `outlook_delete_calendar_event`

Delete a calendar event by ID.

Parameters:

- `event_id` (`string`, required): No description.

### `outlook_get_attachment`

Download a specific attachment from an Outlook email message by attachment ID. Returns the full attachment including base64-encoded file content in the contentBytes field. Use List Attachments to get the attachment ID first.

Parameters:

- `attachment_id` (`string`, required): The ID of the attachment to download.
- `message_id` (`string`, required): The ID of the message containing the attachment.

### `outlook_get_calendar_event`

Retrieve an existing calendar event by ID from the user's Outlook calendar.

Parameters:

- `event_id` (`string`, required): No description.

### `outlook_get_message`

Retrieve a specific email message by ID from the user's Outlook mailbox, including full body content, sender, recipients, attachments info, and metadata.

Parameters:

- `message_id` (`string`, required): The ID of the message to retrieve.

### `outlook_list_attachments`

List all attachments on a specific Outlook email message. Returns attachment metadata including ID, name, size, and content type. Use the attachment ID with Get Attachment to download the file content.

Parameters:

- `message_id` (`string`, required): The ID of the message to list attachments for.

### `outlook_list_calendar_events`

List calendar events from the user's Outlook calendar with filtering, sorting, pagination, and field selection.

Parameters:

- `filter` (`string`, optional): OData filter expression to filter events (e.g., startsWith(subject,'All'))
- `orderby` (`string`, optional): OData orderby expression to sort events (e.g., start/dateTime desc)
- `select` (`string`, optional): Comma-separated list of properties to include in the response
- `skip` (`number`, optional): Number of events to skip for pagination
- `top` (`number`, optional): Maximum number of events to return

### `outlook_list_contacts`

List all contacts in the user's mailbox with support for filtering, pagination, and field selection.

Parameters:

- `$filter` (`string`, optional): Filter expression to narrow results (e.g., "emailAddresses/any(a:a/address eq 'user@example.com')")
- `$orderby` (`string`, optional): Property to sort by (e.g., "displayName")
- `$select` (`string`, optional): Comma-separated list of properties to return (e.g., "displayName,emailAddresses,phoneNumbers")
- `$skip` (`integer`, optional): Number of contacts to skip for pagination
- `$top` (`integer`, optional): Number of contacts to return (default: 10)

### `outlook_list_messages`

List all messages in the user's mailbox with support for filtering, pagination, and field selection. Returns 10 messages by default.

Parameters:

- `$filter` (`string`, optional): Filter expression to narrow results (e.g., "from/emailAddress/address eq 'user@example.com'")
- `$orderby` (`string`, optional): Property to sort by (e.g., "receivedDateTime desc")
- `$select` (`string`, optional): Comma-separated list of properties to return (e.g., "subject,from,receivedDateTime")
- `$skip` (`integer`, optional): Number of messages to skip for pagination
- `$top` (`integer`, optional): Number of messages to return (1-1000, default: 10)

### `outlook_mailbox_settings_get`

Retrieve the mailbox settings for the signed-in user. Returns automatic replies (out-of-office) configuration, language, timezone, working hours, date/time format, and delegate meeting message delivery preferences.

### `outlook_mailbox_settings_update`

Update mailbox settings for the signed-in user. Supports configuring automatic replies (out-of-office), language, timezone, working hours, date/time format, and delegate meeting message delivery preferences. Only fields provided will be updated.

Parameters:

- `automaticRepliesSetting` (`object`, optional): Configuration for automatic replies (out-of-office). Set status, internal/external reply messages, and optional scheduled time window.
- `dateFormat` (`string`, optional): Preferred date format string for the mailbox (e.g., 'MM/dd/yyyy', 'dd/MM/yyyy', 'yyyy-MM-dd').
- `delegateMeetingMessageDeliveryOptions` (`string`, optional): Controls how meeting messages are delivered when a delegate is configured.
- `language` (`object`, optional): Language and locale for the mailbox. Object with locale (e.g., 'en-US') and displayName.
- `timeFormat` (`string`, optional): Preferred time format string for the mailbox (e.g., 'hh:mm tt' for 12-hour, 'HH:mm' for 24-hour).
- `timeZone` (`string`, optional): Preferred time zone for the mailbox (e.g., 'UTC', 'Pacific Standard Time', 'Eastern Standard Time').
- `workingHours` (`object`, optional): Working hours configuration including days of week, start/end times, and time zone.

### `outlook_reply_to_message`

Reply to an existing email message. The reply is automatically sent to the original sender and saved in the Sent Items folder.

Parameters:

- `comment` (`string`, required): Reply message content
- `messageId` (`string`, required): The unique identifier of the message to reply to

### `outlook_search_messages`

Search messages by keywords across subject, body, sender, and other fields. Returns matching messages with support for pagination.

Parameters:

- `query` (`string`, required): Search query string (searches across subject, body, from, to)
- `$select` (`string`, optional): Comma-separated list of properties to return (e.g., "subject,from,receivedDateTime")
- `$skip` (`integer`, optional): Number of messages to skip for pagination
- `$top` (`integer`, optional): Number of messages to return (1-1000, default: 10)

### `outlook_send_message`

Send an email message using Microsoft Graph API. The message is saved in the Sent Items folder by default.

Parameters:

- `body` (`string`, required): Body content of the email
- `subject` (`string`, required): Subject line of the email
- `toRecipients` (`array`, required): Array of email addresses to send to
- `bccRecipients` (`array`, optional): Array of email addresses to BCC
- `bodyType` (`string`, optional): Content type of the body (Text or HTML)
- `ccRecipients` (`array`, optional): Array of email addresses to CC
- `saveToSentItems` (`boolean`, optional): Save the message in Sent Items folder (default: true)

### `outlook_todo_lists_create`

Create a new Microsoft To Do task list.

Parameters:

- `display_name` (`string`, required): The name of the task list.

### `outlook_todo_lists_delete`

Permanently delete a Microsoft To Do task list and all its tasks.

Parameters:

- `list_id` (`string`, required): The ID of the task list to delete.

### `outlook_todo_lists_get`

Get a specific Microsoft To Do task list by ID.

Parameters:

- `list_id` (`string`, required): The ID of the task list.

### `outlook_todo_lists_list`

List all Microsoft To Do task lists for the current user.

### `outlook_todo_lists_update`

Rename a Microsoft To Do task list.

Parameters:

- `display_name` (`string`, required): The new name for the task list.
- `list_id` (`string`, required): The ID of the task list to update.

### `outlook_todo_tasks_create`

Create a new task in a Microsoft To Do task list with optional body, due date, importance, and reminder.

Parameters:

- `list_id` (`string`, required): The ID of the task list to add the task to.
- `title` (`string`, required): The title of the task.
- `body` (`string`, optional): The body/notes of the task (plain text).
- `categories` (`array`, optional): Array of category names to assign to the task.
- `due_date` (`string`, optional): Due date in YYYY-MM-DD format (e.g. "2026-04-15").
- `due_time_zone` (`string`, optional): Time zone for the due date (e.g. "UTC", "America/New_York"). Defaults to UTC.
- `importance` (`string`, optional): The importance of the task: low, normal, or high.
- `reminder_date_time` (`string`, optional): Reminder date and time in ISO 8601 format (e.g. "2026-04-15T09:00:00").
- `reminder_time_zone` (`string`, optional): Time zone for the reminder (e.g. "UTC"). Defaults to UTC.
- `status` (`string`, optional): The status of the task: notStarted, inProgress, completed, waitingOnOthers, or deferred.

### `outlook_todo_tasks_delete`

Permanently delete a task from a Microsoft To Do task list.

Parameters:

- `list_id` (`string`, required): The ID of the task list.
- `task_id` (`string`, required): The ID of the task to delete.

### `outlook_todo_tasks_get`

Get a specific task from a Microsoft To Do task list.

Parameters:

- `list_id` (`string`, required): The ID of the task list.
- `task_id` (`string`, required): The ID of the task.

### `outlook_todo_tasks_list`

List all tasks in a Microsoft To Do task list with optional filtering and pagination.

Parameters:

- `list_id` (`string`, required): The ID of the task list.
- `$filter` (`string`, optional): OData filter expression (e.g. "status eq 'notStarted'").
- `$orderby` (`string`, optional): Property to sort by (e.g. "createdDateTime desc").
- `$skip` (`integer`, optional): Number of tasks to skip for pagination.
- `$top` (`integer`, optional): Number of tasks to return (default: 10).

### `outlook_todo_tasks_update`

Update a task in a Microsoft To Do task list. Only provided fields are changed.

Parameters:

- `list_id` (`string`, required): The ID of the task list.
- `task_id` (`string`, required): The ID of the task to update.
- `body` (`string`, optional): New body/notes for the task (plain text).
- `categories` (`array`, optional): Array of category names to assign to the task.
- `due_date` (`string`, optional): Due date in YYYY-MM-DD format.
- `due_time_zone` (`string`, optional): Time zone for the due date. Defaults to UTC.
- `importance` (`string`, optional): The importance: low, normal, or high.
- `status` (`string`, optional): The status: notStarted, inProgress, completed, waitingOnOthers, or deferred.
- `title` (`string`, optional): New title for the task.

### `outlook_update_calendar_event`

Update an existing Outlook calendar event. Only provided fields will be updated. Supports time, attendees, location, reminders, online meetings, recurrence, and event properties.

Parameters:

- `event_id` (`string`, required): The ID of the calendar event to update
- `attendees_optional` (`string`, optional): Comma-separated optional attendee emails
- `attendees_required` (`string`, optional): Comma-separated required attendee emails
- `attendees_resource` (`string`, optional): Comma-separated resource emails (meeting rooms, equipment)
- `body_content` (`string`, optional): Event description/body
- `body_contentType` (`string`, optional): Content type of body
- `categories` (`string`, optional): Comma-separated categories
- `end_datetime` (`string`, optional): Event end time in RFC3339 format
- `end_timezone` (`string`, optional): Timezone for end time
- `hideAttendees` (`boolean`, optional): When true, each attendee only sees themselves
- `importance` (`string`, optional): Event importance level
- `isAllDay` (`boolean`, optional): Mark as all-day event
- `isOnlineMeeting` (`boolean`, optional): Create an online meeting (Teams/Skype)
- `isReminderOn` (`boolean`, optional): Enable or disable reminder
- `location` (`string`, optional): Physical or virtual location
- `locations` (`string`, optional): JSON array of location objects with displayName, address, coordinates
- `onlineMeetingProvider` (`string`, optional): Online meeting provider
- `recurrence_days_of_week` (`string`, optional): Days of week for weekly recurrence (comma-separated)
- `recurrence_end_date` (`string`, optional): End date for recurrence (YYYY-MM-DD)
- `recurrence_interval` (`integer`, optional): How often the event recurs (e.g., every 2 weeks = 2)
- `recurrence_occurrences` (`integer`, optional): Number of occurrences
- `recurrence_range_type` (`string`, optional): How the recurrence ends
- `recurrence_start_date` (`string`, optional): Start date for recurrence (YYYY-MM-DD)
- `recurrence_type` (`string`, optional): Recurrence pattern type
- `reminderMinutesBeforeStart` (`integer`, optional): Minutes before event start to show reminder
- `sensitivity` (`string`, optional): Event sensitivity/privacy level
- `showAs` (`string`, optional): Free/busy status
- `start_datetime` (`string`, optional): Event start time in RFC3339 format
- `start_timezone` (`string`, optional): Timezone for start time
- `subject` (`string`, optional): Event title/summary


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |