DocsOutlook

Outlook

Give your agents full Outlook access via Microsoft Graph API. Read, search, send, and manage emails.

Usage

Option 1: Import directly

import.py
python
from connectonion import Outlook

agent = Agent("assistant", tools=[Outlook()])

Option 2: Copy and customize

Terminalbash

$co copy outlook

copy.py
python
from tools.outlook import Outlook  # Your local copy

Quick Start

quickstart.py
python
from connectonion import Agent, Outlook

outlook = Outlook()
agent = Agent("assistant", tools=[outlook])

agent.input("Show me my recent emails")
agent.input("Send an email to alice@example.com saying hello")

Setup

Authenticate with Microsoft:

Terminalbash

$co auth microsoft

Your agent can now read and manage Outlook emails.

Switch accounts? Run co auth microsoft again to connect a different Microsoft account.

CLI: co outlook

You don't need an agent to use your mailbox — the same Outlook connection powers a CLI. After co auth microsoft, work with your email directly from the terminal:

Show your inbox as a numbered table (● marks unread)bash

$co outlook

Only unread, or more emailsbash

$co outlook inbox --unread

$co outlook inbox --last 25

Read email #3 from the last listing (marks it read)bash

$co outlook read 3

Send an emailbash

$co outlook send alice@example.com "Quarterly report" "Draft attached, feedback welcome."

Reply to email #3 (threaded; --at schedules it)bash

$co outlook reply 3 "Sounds good, see you then."

Sent mail and searchbash

$co outlook sent

$co outlook search "invoice"

Send options

--cc, --bcc

CC / BCC recipients (comma-separated for multiple)

--attach, -a

Attach a local file — images, screenshots, PDFs. Repeat the flag for multiple files. Microsoft Graph caps the total at about 3 MB.

--at

Schedule delivery: +30m, +2h, or a UTC ISO time like 2026-07-06T15:30:00Z. Uses Exchange deferred delivery, so the email waits server-side even if your machine goes offline.

message = '-'

Read the email body from stdin — pipe in command output or a file.

Everything togetherbash

$co outlook send alice@example.com "Screenshots" "See attached" --cc bob@example.com --attach shot1.png --attach shot2.png --at +2h

Manage scheduled sends

Scheduled emails sit in Drafts until delivery time. See what's queued — and cancel before Exchange sends it:

What's queued, and when it sendsbash

$co outlook scheduled

Cancel #1 before it goes outbash

$co outlook cancel 1

cancel deletes the pending message so it never goes out. Some Exchange work/school tenants reject the delete with 403 — there, use Outlook's own "Cancel Send". On personal outlook.com accounts cancel works normally.

Agent Methods

Reading Emails

read_inbox(last=10, unread=False)

Read emails from inbox

last - Number of emails (default: 10)
unread - Only unread emails (default: False)

get_sent_emails(max_results=10)

Get emails you sent

get_email_body(email_id)

Get full email content with headers

Search

search_emails(query, max_results=10)

Search emails using Microsoft Graph search

Example queries:

"quarterly report"
"meeting notes"
"invoice"

Sending Emails

send(to, subject, body, cc=None, bcc=None)

Send email via Microsoft Graph API

to - Recipient email (comma-separated for multiple)
subject - Email subject
body - Email body (plain text)
cc - Optional CC recipients
bcc - Optional BCC recipients

reply(email_id, body)

Reply to an existing email

Actions

mark_read(email_id)

Mark email as read

mark_unread(email_id)

Mark email as unread

archive_email(email_id)

Move email to archive folder

Stats

count_unread()

Count unread emails in inbox

get_my_email()

Get connected Microsoft email address

Complete Example

complete_example.py
python
from connectonion import Agent, Outlook, Memory

outlook = Outlook()
memory = Memory()

agent = Agent(
    name="email-assistant",
    tools=[outlook, memory],
    system_prompt="You help manage Outlook emails and remember important info."
)

# Various tasks your agent can now do:
agent.input("Check unread emails and summarize them")
agent.input("Send an email to alice@example.com about the project update")
agent.input("Find all emails about the quarterly report")
agent.input("How many unread emails do I have?")

Customizing

Need to modify Outlook's behavior? Copy the source to your project:

Terminalbash

$co copy outlook

Then import from your local copy:

customize.py
python
# from connectonion import Outlook  # Before
from tools.outlook import Outlook    # After - customize freely!

Troubleshooting

Missing Microsoft Mail scopes

Run co auth microsoft

Credentials not found

Run co auth microsoft

Token expired

Tokens auto-refresh. If issues persist, run co auth microsoft again.

Microsoft Integration

Full OAuth setup and calendar integration

Gmail

Gmail integration for Google users

Outlook

Usage

Quick Start

Setup

CLI: co outlook

Send options

--cc, --bcc

--attach, -a

--at

message = '-'

Manage scheduled sends

Agent Methods

Reading Emails

read_inbox(last=10, unread=False)

get_sent_emails(max_results=10)

get_email_body(email_id)

Search

search_emails(query, max_results=10)

Sending Emails

send(to, subject, body, cc=None, bcc=None)

reply(email_id, body)

Actions

mark_read(email_id)

mark_unread(email_id)

archive_email(email_id)

Stats

count_unread()

get_my_email()

Complete Example

Customizing

Troubleshooting

Missing Microsoft Mail scopes

Credentials not found

Token expired

Related

Microsoft Integration

Gmail

Star us on GitHub