OutNote

Headless Microsoft 365 client - mail, calendar, Teams, OneDrive, SharePoint, OneNote, To Do, Planner and Assignments over Graph, without an app registration.

About The Project

Every "read my mailbox over Graph" tutorial makes you register an Azure app and get admin consent - which a locked-down tenant (a school, a company) simply refuses. OutNote sidesteps that entirely.

It signs in with entrance using the pre-consented OfficeHome first-party client, which hands back a FOCI family refresh token. A tiny broker then trades that token for whichever first-party client's token a given call needs - all without another sign-in. Each of those clients is already consented in the tenant, so there is nothing to register and nobody to ask.

The result: one headless login (password + TOTP MFA, no browser), then clean reads and writes across your whole Microsoft 365 account.

Features

• 🔓 No app registration, no admin consent - rides pre-consented Microsoft first-party clients
• 🤖 Fully headless - password + TOTP MFA over pure HTTP, no browser (via entrance)
• 🧩 One login, every service - a FOCI family token is brokered into the right client per call
• 💾 Log in once - the family refresh token is persisted atomically (0600) and reused, so later runs skip the sign-in entirely
• 📬 Broad coverage - mail, calendar, Teams chats & channels, OneDrive, SharePoint, OneNote, To Do, Planner, Teams Assignments
• ✉️ Writes too - send mail, Teams messages (with @mentions), events, uploads, OneNote pages, tasks
• 🧾 Text out - Teams/OneNote HTML to plain text, .docx/.pptx/.xlsx/.pdf text extraction
• ⚡ Robust - 429/5xx backoff with Retry-After, $batch, delta queries, nextLink paging
• 🖥️ CLI - outnote --text chats --unread for quick checks
• 📦 Tiny - stdlib urllib Graph client, one dependency (ms-entrance)

Installation

pip install outnote
# or
uv add outnote

Requires Python 3.10+; ms-entrance is pulled in automatically. pip install "outnote[pdf]" adds PDF text extraction.

Quickstart

from outnote import authenticate

note = authenticate(
    "you@school.ch",
    "your-password",
    totp_secret="JBSWY3DPEHPK3PXP",  # Base32 TOTP, if the account has MFA
)

# mail
note.emails(top=5, unread=True)
for a in note.attachments(msg_id):
    data = note.download_attachment(msg_id, a["id"])

# calendar
note.today()
note.free_busy(["you@school.ch", "friend@school.ch"], start, end)

# Teams chats - who it's with, last message, unread
for chat in note.chats():
    print(chat["members"], note.message_text(chat["lastMessagePreview"]))
note.unread_chats()
note.chat_messages(note.find_chat("friend@school.ch")["id"])

# Teams channels + files
for team in note.teams():
    for ch in note.channels(team["id"]):
        note.channel_messages(team["id"], ch["id"])
        note.channel_files(team["id"], ch["id"])

# OneDrive - bytes and text
data = note.download(item_id)
text = note.extract_text("notes.docx", data)

# OneNote - your notebooks or a class/team's
for nb in note.notebooks(group_id=team["id"]):
    for sec in note.sections(nb["id"], group_id=team["id"]):
        for page in note.pages(sec["id"], group_id=team["id"]):
            note.page_text(page["id"], group_id=team["id"])

# Teams Assignments
note.due_assignments(days=7)

# search across the account (each result carries a usable "id")
note.search_emails("invoice")
note.search_messages("standup")

note.get("me/drive/root/children")  # any Graph endpoint, raw

The first call saves .ms_frt (the family refresh token, 0600) and .ms_session.json (sign-in cookies); every run after that skips the password and MFA. Already have a refresh token? OutNote.from_refresh_token(frt).

Already have a Graph token (MSAL, a browser session, ...)? Skip auth entirely. A single static token only carries its own scopes, so OneNote/SharePoint/Assignments calls may fail:

from outnote import OutNote

OutNote(access_token).emails()

Writing

These act as the signed-in user - mail is really sent, messages really posted:

note.send_mail("friend@school.ch", "Hi", "Body", attachments=["report.pdf"])
note.send_to(
    "friend@school.ch", "hey @Friend", mentions=["friend@school.ch"]
)  # 1:1 chat, created if needed
msg = note.send_chat_message(chat_id, "hello")
note.edit_chat_message(chat_id, msg["id"], "hello!")
note.react(chat_id, msg["id"], "👍")
note.mark_chat_read(chat_id)
note.create_event("Study", start, end)  # attendees=[...] sends invitations
note.upload("notes.txt", "Documents/notes.txt")  # >4 MB goes through an upload session
note.create_page(section_id, title="Summary", body="<p>...</p>")
note.create_task(list_id, "Hand in essay", due=friday)

CLI

export OUTNOTE_USER=you@school.ch OUTNOTE_PASSWORD=... OUTNOTE_TOTP=BASE32   # first run only
outnote --text chats --unread
outnote --text mail --unread
outnote --text events
outnote send friend@school.ch "on my way"
outnote get me/drive/root/children

Credentials are read from the environment, never from argv; after the first sign-in the saved refresh token is enough.

What it does

Verified end-to-end against a live locked-down EDU tenant:

* needs OnlineMeetings.Read / transcript scopes, which no FOCI client carries on many tenants (403). The meeting chat works without them.

How It Works

authenticate runs a PKCE authorization-code sign-in for the OfficeHome client through entrance (which drives Microsoft's sign-in - including TOTP MFA - over pure HTTP and intercepts the code at the native-client redirect), then redeems it for a FOCI family refresh token and saves it. The OutNote client holds a broker that, per call, refreshes that token into the first-party client whose pre-consented scopes cover the request, caching each token until it expires:

Graph's own /education endpoints need EduAssignments.*, which no FOCI client carries. The Teams Assignments app instead talks to assignments.edu.cloud.microsoft (same object shapes, edu/... paths) - and the Office client can mint a token for that API, so OutNote does the same. See docs/clients.md for how this map was found and how to re-probe it on your tenant.

Caveats

• Works against managed Entra tenants (login.microsoftonline.com) with these first-party clients pre-consented - the common case for Microsoft 365 / EDU.
• Push / SMS MFA can't be done headless - only TOTP (authenticator app). Enroll one and pass its Base32 secret.
• Which scopes each client carries is tenant-dependent. Online-meeting lookup and transcripts 403 on the tested tenant.
• SharePoint-index search (search_files, sites(search), search(entity="site")) depends on the tenant's search service; when it errors, followed_sites(), files() and get("me/drive/recent") still work.
• Microsoft tweaks its login pages and client registrations; if a flow breaks, a user-agent, field name or client ID is usually the culprit.
• Treat .ms_frt and .ms_session.json like passwords (both are gitignored).

Disclaimer

OutNote is published for educational and research purposes only - to document how Microsoft 365's first-party OAuth2 clients and the Graph API behave for a browserless client.

Use it only against accounts you own, or with the explicit authorization of the account or tenant owner. You alone are responsible for your use of it and for complying with Microsoft's terms, your identity provider's terms, your institution's acceptable-use policy, and applicable law. The software is provided "as is", without warranty of any kind, and the author accepts no liability for misuse. Not affiliated with or endorsed by Microsoft.

License

MIT (c) PianoNic