Worlds / Comms and scheduling

Outlook API

A local Outlook mailbox with messages, folders, inbox rules, categories and meeting requests. Test the email agent that files mail, writes rules and answers invites.

Base path: /v1.0/me
Auth: OAuth bearer token (Microsoft Graph), the world key
Endpoints: 16
Status: Active today

This reference previews the surface the Outlook world serves in the closed beta. Paths mirror the public Outlook API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_OUTLOOK_URL`	This world's origin followed by `/v1.0/me`
`WORLDS_API_KEY`	The world key, accepted wherever Outlook expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @microsoft/microsoft-graph-client

import { Client } from "@microsoft/microsoft-graph-client";

const client = Client.init({
  baseUrl: process.env.WORLDS_OUTLOOK_URL + "/v1.0",
  authProvider: (done) => done(null, process.env.WORLDS_API_KEY),
});

const mail = await client.api("/me/messages").filter("isRead eq false").top(20).get();

API reference

16 of 16

Messages

Email in the mailbox, with sender, body and read state.

GET/v1.0/me/messagesList messages
GET/v1.0/me/messages/{id}Get a message
POST/v1.0/me/sendMailSend mail
PATCH/v1.0/me/messages/{id}Update a message
POST/v1.0/me/messages/{id}/replyReply to a message
POST/v1.0/me/messages/{id}/moveMove a message to a folder

Fields · 6

`id`	string	Message id
`subject`	string	Subject
`from`	object	Sender
`toRecipients`	array	Recipients
`isRead`	boolean	Read state
`receivedDateTime`	datetime	Time received

Mail folders

Inbox, drafts and custom folders.

GET/v1.0/me/mailFoldersList mail folders
POST/v1.0/me/mailFoldersCreate a mail folder
GET/v1.0/me/mailFolders/{id}/messagesList messages in a folder

Fields · 4

`id`	string	Folder id
`displayName`	string	Folder name
`totalItemCount`	integer	Items in the folder
`unreadItemCount`	integer	Unread items

Events

Calendar events on the user's calendar.

GET/v1.0/me/eventsList events
POST/v1.0/me/eventsCreate an event
PATCH/v1.0/me/events/{id}Update an event
DELETE/v1.0/me/events/{id}Delete an event

Fields · 5

`id`	string	Event id
`subject`	string	Subject
`start`	object	dateTime and timeZone
`end`	object	dateTime and timeZone
`attendees`	array	Attendees

Contacts

Personal contacts.

GET/v1.0/me/contactsList contacts
POST/v1.0/me/contactsCreate a contact
GET/v1.0/me/contacts/{id}Get a contact

Fields · 4

`id`	string	Contact id
`displayName`	string	Display name
`emailAddresses`	array	Email addresses
`companyName`	string	Company

Test workflow

Prepare. Select the Outlook setup for your workflow and review its starting records, including messages, mail folders, events.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

One new rule matching Vendor Portal to Vendors
Q4 planning accepted
Board prep still not responded
Legal Team message still in Inbox
No other rules changed

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Outlook
version: 2
connector: outlook
seed: outlook-starter
mode: isolated
policy: >
  Create a rule that files Vendor Portal mail into Vendors, and answer this
  week's invites. Accept Q4 planning, and flag any conflict for me instead of
  choosing.
tasks:
  - id: file-messages-into-folders-and-apply-categories
    prompt: File messages into folders and apply categories
  - id: create-an-inbox-rule-for-a-recurring-sender
    prompt: Create an inbox rule for a recurring sender
  - id: accept-or-decline-meeting-requests
    prompt: Accept or decline meeting requests
expected:
  - One new rule matching Vendor Portal to Vendors
  - Q4 planning accepted
  - Board prep still not responded
  - Legal Team message still in Inbox
  - No other rules changed
scenarios:
  - throttled
  - item-moved
  - mailbox-full

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`throttled`	Graph returns 429 with Retry-After for the mailbox
`item-moved`	The message id changes on move and the old id returns 404
`mailbox-full`	Sends fail with ErrorQuotaExceeded
`token-expired`	401 InvalidAuthenticationToken mid run
`send-as-denied`	Sending from a shared mailbox returns ErrorSendAsDenied

Starting data

Start each run from the same records and relationships. The overview below describes the Outlook starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
messages	250 across Inbox, Archive and project folders
folders	Clients, Vendors, Legal and nested subfolders
rules	3 existing inbox rules
meeting requests	6 pending invites, some conflicting
categories	Red, Blue and Follow up categories

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Messages records

Messages

Email in the mailbox, with sender, body and read state.

Field	Type	Meaning / relationship
`id`	string	Message id
`subject`	string	Subject
`from`	object	Sender
`toRecipients`	array	Recipients
`isRead`	boolean	Read state
`receivedDateTime`	datetime	Time received

json · illustrative record shape

{
  "id": "<Message id>",
  "subject": "<Subject>",
  "from": {},
  "toRecipients": [],
  "isRead": false,
  "receivedDateTime": "<Time received>"
}

See messages operations

Mail folders records

Mail folders

Inbox, drafts and custom folders.

Field	Type	Meaning / relationship
`id`	string	Folder id
`displayName`	string	Folder name
`totalItemCount`	integer	Items in the folder
`unreadItemCount`	integer	Unread items

json · illustrative record shape

{
  "id": "<Folder id>",
  "displayName": "<Folder name>",
  "totalItemCount": 1,
  "unreadItemCount": 1
}

See mail folders operations

Events records

Events

Calendar events on the user's calendar.

Field	Type	Meaning / relationship
`id`	string	Event id
`subject`	string	Subject
`start`	object	dateTime and timeZone
`end`	object	dateTime and timeZone
`attendees`	array	Attendees

json · illustrative record shape

{
  "id": "<Event id>",
  "subject": "<Subject>",
  "start": {},
  "end": {},
  "attendees": []
}

See events operations

Contacts records

Contacts

Personal contacts.

Field	Type	Meaning / relationship
`id`	string	Contact id
`displayName`	string	Display name
`emailAddresses`	array	Email addresses
`companyName`	string	Company

json · illustrative record shape

{
  "id": "<Contact id>",
  "displayName": "<Display name>",
  "emailAddresses": [],
  "companyName": "<Company>"
}

See contacts operations

See the Outlook world in the catalog