Outlook connector

OAuth 2.0CommunicationCalendar

Connect to Microsoft Outlook. Manage emails, calendar events, contacts, and tasks

Outlook connector

Install the SDK
Section titled “Install the SDK”
- Node.js
- Python
Terminal window
1 npm install @scalekit-sdk/node
Terminal window
1 pip install scalekit
Full SDK reference: Node.js | Python
Set your credentials
Section titled “Set your credentials”

Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.
.env
```
SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
SCALEKIT_CLIENT_ID=<your-client-id>
SCALEKIT_CLIENT_SECRET=<your-client-secret>
```
Set up the connector
Section titled “Set up the connector”

Register your Outlook credentials with Scalekit so it handles the token lifecycle. You do this once per environment.
Dashboard setup steps
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, go to AgentKit > Connections > Create Connection. Search for Outlook and click Create.
  - In the Configure Outlook Connection dialog, copy the Redirect URI. You will need this when registering your app in Azure.
2. Register an application in Azure
  - Sign into portal.azure.com and go to Microsoft Entra ID → App registrations.
  - 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.
3. Get your client credentials
  - From the app’s Overview page, copy the Application (client) ID.
  - Go to Certificates & secrets in the left sidebar, then click + New client secret.
  - 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.
4. Add credentials in Scalekit
  - In Scalekit dashboard, 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 for the full list.
  - Click Save.

1
import { ScalekitClient } from '@scalekit-sdk/node'
2
import 'dotenv/config'
3

4
const scalekit = new ScalekitClient(
5
  process.env.SCALEKIT_ENV_URL,
6
  process.env.SCALEKIT_CLIENT_ID,
7
  process.env.SCALEKIT_CLIENT_SECRET,
8
)
9
const actions = scalekit.actions
10

11
const connector = 'outlook'
12
const identifier = 'user_123'
13

14
// Generate an authorization link for the user
15
const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
16
console.log('Authorize Outlook:', link)
17
process.stdout.write('Press Enter after authorizing...')
18
await new Promise(r => process.stdin.once('data', r))
19

20
// Make your first call
21
const result = await actions.executeTool({
22
  connector,
23
  identifier,
24
  toolName: 'outlook_list_calendar_events',
25
  toolInput: {},
26
})
27
console.log(result)

1
import os
2
from scalekit.client import ScalekitClient
3
from dotenv import load_dotenv
4
load_dotenv()
5

6
scalekit_client = ScalekitClient(
7
    env_url=os.getenv("SCALEKIT_ENV_URL"),
8
    client_id=os.getenv("SCALEKIT_CLIENT_ID"),
9
    client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
10
)
11
actions = scalekit_client.actions
12

13
connection_name = "outlook"
14
identifier = "user_123"
15

16
# Generate an authorization link for the user
17
link_response = actions.get_authorization_link(
18
    connection_name=connection_name,
19
    identifier=identifier,
20
)
21
print("Authorize Outlook:", link_response.link)
22
input("Press Enter after authorizing...")
23

24
# Make your first call
25
result = actions.execute_tool(
26
    tool_input={},
27
    tool_name="outlook_list_calendar_events",
28
    connection_name=connection_name,
29
    identifier=identifier,
30
)
31
print(result)

What you can do

Connect this agent connector to let your agent:

Update shared calendar event, focused inbox override, contact folder — Update an existing event on another user’s calendar (shared or delegated access)
List shared todo tasks, shared todo lists, shared contacts — List tasks in a Microsoft To Do list belonging to another user (a colleague)
Get shared mailbox message, shared contact, free busy schedule — Get a single message from a shared mailbox by message ID
Create shared calendar event, upload session, focused inbox override — Create an event on another user’s calendar (shared or delegated access)
Send message from shared mailbox, message — Send an email message on behalf of a shared mailbox using Microsoft Graph API
Search shared mailbox messages, people, messages — Search messages across all folders in a shared mailbox by keyword

Common workflows

Proxy API call

Node.js
Python

1
const result = await actions.request({
2
  connectionName: 'outlook',
3
  identifier: 'user_123',
4
  path: '/v1.0/me/messages',
5
  method: 'GET',
6
});
7
console.log(result);

1
result = actions.request(
2
    connection_name='outlook',
3
    identifier='user_123',
4
    path="/v1.0/me/messages",
5
    method="GET"
6
)
7
print(result)

Execute a tool

Node.js
Python

1
const result = await actions.executeTool({
2
  connector: 'outlook',
3
  identifier: 'user_123',
4
  toolName: 'outlook_create_calendar_event',
5
  toolInput: {},
6
});
7
console.log(result);

1
result = actions.execute_tool(
2
    connection_name='outlook',
3
    identifier='user_123',
4
    tool_name='outlook_create_calendar_event',
5
    tool_input={},
6
)
7
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.

outlook_accept_event#Accept a calendar event invitation.5 params

Accept a calendar event invitation.

NameTypeRequiredDescription

event_idstringrequiredEvent ID.

commentstringoptionalResponse comment.

schema_versionstringoptionalSchema version

send_responsebooleanoptionalSend response.

tool_versionstringoptionalTool version

outlook_batch_move_messages#Move up to 20 Outlook messages to a destination folder in a single Microsoft Graph batch request. Builds a $batch envelope where each subrequest POSTs to /me/messages/{id}/move. Returns a 200 response with per-subrequest status codes inside the responses array.2 params

Move up to 20 Outlook messages to a destination folder in a single Microsoft Graph batch request. Builds a $batch envelope where each subrequest POSTs to /me/messages/{id}/move. Returns a 200 response with per-subrequest status codes inside the responses array.

NameTypeRequiredDescription

destination_folder_idstringrequiredThe ID or well-known name of the destination folder (e.g., 'inbox', 'deleteditems', 'drafts', or a specific folder ID like 'AAMkAGI2...').

message_idsarrayrequiredArray of message IDs to move (max 20). Each ID is an Outlook message ID string.

outlook_batch_update_messages#Update properties on up to 20 Outlook messages in a single Microsoft Graph batch request. Builds a $batch envelope where each subrequest PATCHes /me/messages/{id} with the provided updates object. Common use: mark messages as read by passing {"isRead": true}. Returns a 200 response with per-subrequest status codes inside the responses array.2 params

Update properties on up to 20 Outlook messages in a single Microsoft Graph batch request. Builds a $batch envelope where each subrequest PATCHes /me/messages/{id} with the provided updates object. Common use: mark messages as read by passing {"isRead": true}. Returns a 200 response with per-subrequest status codes inside the responses array.

NameTypeRequiredDescription

message_idsarrayrequiredArray of message IDs to update (max 20). Each ID is an Outlook message ID string.

updatesobjectrequiredFree-form object of message properties to update on all specified messages. Example: {"isRead": true} to mark as read, or {"isRead": false, "flag": {"flagStatus": "flagged"}} for multiple changes.

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.28 params

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

NameTypeRequiredDescription

end_datetimestringrequiredNo description.

end_timezonestringrequiredNo description.

start_datetimestringrequiredNo description.

start_timezonestringrequiredNo description.

subjectstringrequiredNo description.

attendees_optionalstringoptionalArray of email addresses for optional attendees

attendees_requiredstringoptionalArray of email addresses for required attendees

attendees_resourcestringoptionalArray of email addresses for resources (meeting rooms, equipment)

body_contentstringoptionalNo description.

body_contentTypestringoptionalNo description.

hideAttendeesbooleanoptionalWhen true, each attendee only sees themselves

importancestringoptionalEvent importance level

isAllDaybooleanoptionalMark as all-day event

isOnlineMeetingbooleanoptionalCreate an online meeting (Teams/Skype)

isReminderOnbooleanoptionalEnable or disable reminder

locationstringoptionalNo description.

locationsstringoptionalJSON array of location objects with displayName, address, coordinates

onlineMeetingProviderstringoptionalOnline meeting provider

recurrence_days_of_weekstringoptionalDays of week for weekly recurrence (comma-separated)

recurrence_end_datestringoptionalEnd date for recurrence (YYYY-MM-DD), required if range_type is endDate

recurrence_intervalintegeroptionalHow often the event recurs (e.g., every 2 weeks = 2)

recurrence_occurrencesintegeroptionalNumber of occurrences, required if range_type is numbered

recurrence_range_typestringoptionalHow the recurrence ends

recurrence_start_datestringoptionalStart date for recurrence (YYYY-MM-DD)

recurrence_typestringoptionalRecurrence pattern type

reminderMinutesBeforeStartintegeroptionalMinutes before event start to show reminder

sensitivitystringoptionalEvent sensitivity/privacy level

showAsstringoptionalFree/busy status

outlook_create_calendar_group#Create a new calendar group in the signed-in user's mailbox. Calendar groups organize multiple calendars together in Outlook.1 param

Create a new calendar group in the signed-in user's mailbox. Calendar groups organize multiple calendars together in Outlook.

NameTypeRequiredDescription

namestringrequiredThe name of the new calendar group (e.g., 'Work Calendars'). Must be unique among calendar groups for the user.

outlook_create_calendar_permission#Grant a user access to a specific Outlook calendar by creating a calendar permission entry. Specify the user's email address and the role level (e.g., freeBusyRead, read, write, delegate).4 params

Grant a user access to a specific Outlook calendar by creating a calendar permission entry. Specify the user's email address and the role level (e.g., freeBusyRead, read, write, delegate).

NameTypeRequiredDescription

calendar_idstringrequiredThe unique identifier of the calendar to share. Use a specific calendar ID from the list calendars endpoint.

email_addressstringrequiredThe email address of the user to grant calendar access to. Example: colleague@example.com

rolestringrequiredThe permission role to grant. Valid values: freeBusyRead (see free/busy only), limitedRead (see title and location), read (see all event details), write (create/edit/delete events), delegateWithoutPrivateEventAccess (delegate, no private events), delegateWithPrivateEventAccess (delegate including private events), custom (custom role).

namestringoptionalDisplay name of the user to grant access to. Optional; the Graph API will resolve it from the email if omitted.

outlook_create_category#Create a new Outlook master category for the signed-in user. Categories have a display name and a color preset (none or preset0–preset24). Once created, categories can be applied to messages, events, and contacts.2 params

Create a new Outlook master category for the signed-in user. Categories have a display name and a color preset (none or preset0–preset24). Once created, categories can be applied to messages, events, and contacts.

NameTypeRequiredDescription

display_namestringrequiredThe display name of the new category. Must be unique among the user's categories.

colorstringoptionalThe color assigned to the category. Use 'none' for no color, or 'preset0' through 'preset24' for a specific color slot. Defaults to preset0.

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

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

NameTypeRequiredDescription

givenNamestringrequiredFirst name of the contact

surnamestringrequiredLast name of the contact

businessPhonesarrayoptionalArray of business phone numbers

companyNamestringoptionalCompany name

emailAddressesarrayoptionalArray of email address objects with 'address' and optional 'name' fields

jobTitlestringoptionalJob title

mobilePhonestringoptionalMobile phone number

outlook_create_contact_folder#Create a new contact folder in the signed-in user's mailbox. Optionally nest it under an existing parent folder by providing a parent folder ID.2 params

Create a new contact folder in the signed-in user's mailbox. Optionally nest it under an existing parent folder by providing a parent folder ID.

NameTypeRequiredDescription

display_namestringrequiredThe display name for the new contact folder (e.g., 'Work Contacts').

parent_folder_idstringoptionalOptional ID of the parent contact folder under which to create this folder. If omitted, the folder is created at the top level.

outlook_create_draft_message#Create a new email draft in the mailbox.9 params

Create a new email draft in the mailbox.

NameTypeRequiredDescription

bcc_recipientsstringoptionalBCC recipients.

bodystringoptionalEmail body content.

body_typestringoptionalBody content type.

cc_recipientsstringoptionalCC recipients.

importancestringoptionalImportance.

schema_versionstringoptionalSchema version

subjectstringoptionalEmail subject.

to_recipientsstringoptionalTo recipients.

tool_versionstringoptionalTool version

outlook_create_focused_inbox_override#Create a Focused Inbox override that classifies all messages from a specific sender into either the Focused or Other inbox. This overrides the automatic machine learning classification for that sender.3 params

Create a Focused Inbox override that classifies all messages from a specific sender into either the Focused or Other inbox. This overrides the automatic machine learning classification for that sender.

NameTypeRequiredDescription

classify_asstringrequiredHow to classify messages from this sender: 'focused' to route to Focused inbox, 'other' to route to Other inbox.

sender_emailstringrequiredThe email address of the sender to create an override for (e.g., 'newsletter@example.com').

sender_namestringoptionalOptional display name for the sender (e.g., 'Weekly Newsletter'). Used for display purposes only.

outlook_create_forward_draft#Create a forward draft for a specific message.5 params

Create a forward draft for a specific message.

NameTypeRequiredDescription

message_idstringrequiredMessage ID.

commentstringoptionalForward comment.

schema_versionstringoptionalSchema version

to_recipientsstringoptionalTo recipients.

tool_versionstringoptionalTool version

outlook_create_mail_folder#Create a new mail folder in the mailbox.4 params

Create a new mail folder in the mailbox.

NameTypeRequiredDescription

display_namestringrequiredFolder name.

is_hiddenbooleanoptionalHidden folder.

schema_versionstringoptionalSchema version

tool_versionstringoptionalTool version

outlook_create_message_rule#Create a new inbox message rule.8 params

Create a new inbox message rule.

NameTypeRequiredDescription

display_namestringrequiredRule name.

actionsobjectoptionalRule actions.

conditionsobjectoptionalRule conditions.

exceptionsobjectoptionalException conditions for the rule.

is_enabledbooleanoptionalEnable rule.

schema_versionstringoptionalSchema version

sequenceintegeroptionalRule sequence.

tool_versionstringoptionalTool version

outlook_create_reply_all_draft#Create a reply-all draft for a specific message.4 params

Create a reply-all draft for a specific message.

NameTypeRequiredDescription

message_idstringrequiredMessage ID.

commentstringoptionalReply comment.

schema_versionstringoptionalSchema version

tool_versionstringoptionalTool version

outlook_create_reply_draft#Create a reply draft for a specific message.4 params

Create a reply draft for a specific message.

NameTypeRequiredDescription

message_idstringrequiredMessage ID.

commentstringoptionalReply comment.

schema_versionstringoptionalSchema version

tool_versionstringoptionalTool version

outlook_create_shared_calendar_event#Create an event on another user's calendar (shared or delegated access). Targets /users/{id}/events. Requires Calendars.ReadWrite application permission or delegated access granted by the target user.29 params

Create an event on another user's calendar (shared or delegated access). Targets /users/{id}/events. Requires Calendars.ReadWrite application permission or delegated access granted by the target user.

NameTypeRequiredDescription

end_datetimestringrequiredNo description.

end_timezonestringrequiredNo description.

start_datetimestringrequiredNo description.

start_timezonestringrequiredNo description.

subjectstringrequiredNo description.

user_idstringrequiredThe user ID or userPrincipalName (email) of the target user whose data you are accessing (e.g., colleague@company.com or an object ID). Access must be granted via application permissions or delegated sharing.