Skip to main content

ewsgraph

exchangelib's API on Microsoft Graph. Change the import, keep the code.

EWS in Exchange Online is off by default since October 2026. An administrator can still allow it for an app, but on 1 April 2027 Microsoft switches it off for good. ewsgraph runs exchangelib code on Microsoft Graph instead:

- from exchangelib import IMPERSONATION, OAUTH2, Account, Configuration, Identity, OAuth2Credentials, Q
+ from ewsgraph import IMPERSONATION, OAUTH2, Account, Configuration, Identity, OAuth2Credentials, Q
credentials = OAuth2Credentials(client_id=CLIENT_ID, client_secret=CLIENT_SECRET, tenant_id=TENANT_ID,
                                identity=Identity(primary_smtp_address=MAILBOX))
config = Configuration(server="outlook.office365.com", credentials=credentials, auth_type=OAUTH2)
account = Account(primary_smtp_address=MAILBOX, config=config, autodiscover=False, access_type=IMPERSONATION)

print("unread:", account.inbox.filter(is_read=False).count())
for msg in account.inbox.filter(Q(importance="High") | Q(is_read=False)).order_by("-datetime_received")[:5]:
    print(msg.datetime_received, msg.sender.email_address, msg.subject, [a.name for a in msg.attachments])

With either import line, this script prints the same report on our test tenant.

pip install ewsgraph

Python 3.10 to 3.13. Dependencies: httpx, msal, tzlocal.

What works

Area exchangelib API
Sign-in OAuth2Credentials (client secret or certificate), OAuth2AuthorizationCodeCredentials, OAuth2LegacyCredentials, O365InteractiveConfiguration; DELEGATE / IMPERSONATION
Folders account.inbox, .sent, .drafts, .trash, .junk, .root, .msg_folder_root; folder / "Name", .children, .walk(), .glob(), .tree(), .absolute; Folder(...).save(), .move(), .delete(); SingleFolderQuerySet, FolderCollection.find_folders(); isinstance(folder, Inbox) and the other folder classes
Queries filter() with every lookup (exact, iexact, contains, icontains, startswith, in, range, gt..., not, exists), exclude(), Q with & | ~, order_by(), only(), values(), values_list(), slices, count(), exists(), get(), query strings (filter("subject:report"))
Messages send(), send_and_save(), drafts, reply(), reply_all(), forward(), move(), copy(), delete(), soft_delete(), move_to_trash(), refresh(); HTMLBody; FileAttachment (large files through upload sessions) and ItemAttachment; mime_content, text_body, unique_body, headers, received_by, in_reply_to, references, conversation_id
Calendar CalendarItem create, read, update, delete; calendar.view(); recurring series with modified and deleted occurrences; accept / decline / tentative; other calendars; attachments; uid, sensitivity, resources; account.protocol.get_free_busy_info(); rooms (get_roomlists(), get_rooms())
Contacts Contact, account.contacts and contact folders, e-mail / phone / postal / IM entries
Tasks Task, account.tasks (Microsoft To Do: the default list is EWS's Tasks folder) and the other To Do lists; save, query, complete(), delete, recurrence
Directory account.protocol.resolve_names() (directory users, groups and the mailbox's contacts; return_full_contact_data), expand_dl()
Sync folder.sync_items() (create / update / delete / read_flag_change, as EWS tells them) and sync_hierarchy(), on Graph delta queries
Rules account.rules, create_rule(), set_rule(), delete_rule(); Rule, Conditions, Exceptions, Actions
More account.oof_settings; ExtendedProperty with Item.register(); bulk_create/update/delete/move/copy/send, account.fetch(), QuerySet.delete()/move()/copy()/send() (Graph $batch); account.protocol.close()
Names every name exchangelib exports, from the same modules (exchangelib.errors, .properties, .folders, .items, .queryset, .credentials, .ewsdatetime, .winzone...), and all 407 exception classes with their bases

Ids come in exchangelib's form: Graph's ids of messages, events, contacts, mail folders and attachments are EWS's ids in another base64 alphabet, so ids a program stored with exchangelib keep working without any conversion. Calendars are the exception: their ids are Graph's.

A field or call Graph has no answer for raises UnsupportedFeature or UnsupportedField before any request, with the reason and what to use instead, never a silent None.

Later: account.protocol.convert_ids() (Graph's translateExchangeIds), task attachments.

Never, because Microsoft Graph has no API for it: public folders, the archive mailbox, export() / upload() of items, pull and streaming subscriptions, personal distribution lists, Exchange servers on premises (NTLM, basic auth, client certificates).

What you still change

  1. The app registration. Microsoft Graph application permissions instead of EWS's full_access_as_app: Mail.ReadWrite and Mail.Send; Calendars.ReadWrite, Contacts.ReadWrite, MailboxSettings.ReadWrite (automatic replies, inbox rules), Place.Read.All (rooms), User.Read.All (resolve_names), GroupMember.Read.All (expand_dl) and Tasks.ReadWrite.All (tasks) if you use them. ewsgraph doctor --tenant-id ... --client-id ... --mailbox ... signs in and says which ones are missing.
  2. Username and password sign-in. Exchange Online turned basic auth off; use OAuth2Credentials.
  3. Access limited to some mailboxes. Application Access Policies are replaced by RBAC for Applications in Exchange Online, and a tenant-wide Graph permission next to it would undo the limit.

How it is checked

  • A Microsoft 365 test tenant, with EWS still allowed: the same reads through exchangelib over EWS and through ewsgraph over Graph, compared field by field: messages, bodies (HTML and text), attachments by SHA-256, headers, ids, calendar events with every occurrence, free/busy, contacts, folders, query strings, automatic replies, rooms, name resolution and distribution lists, inbox rules, tasks (64 steps). Live tests write, send, move and delete on the tenant and clean up after themselves.
  • A corpus of 46 public projects that use exchangelib with OAuth (GitHub search, November 2026): 35 of 45 use only what ewsgraph has, with the import changed. The check reads their code; it does not run it (tools/corpus/README.md).
  • 1390+ offline tests on Python 3.10 to 3.13.

Differences you may notice

  • Text filters: Graph compares without case. ewsgraph checks case itself where exchangelib does (__exact, __contains, __startswith), so the results are exchangelib's.
  • Query strings (filter("subject:...")) use Graph's $search: at most 1,000 results (more raises UnsupportedQuery), and no other filter next to them, as in exchangelib; order_by() is applied by ewsgraph.
  • Extended properties filter on String properties only (and a message's flag status): Graph refuses value filters on other types.
  • sync_items() keeps exchangelib's create / update / delete / read_flag_change. Graph's delta query does not tell a new item from a changed one, so ewsgraph's sync state remembers the ids it reported (about 5 characters per item in the folder). A sync state made by exchangelib cannot continue on Graph: start with sync_state=None. Calendars cannot be synced (Graph v1.0 has no delta query for a calendar's items).
  • Tasks: To Do keeps plain-text bodies (an HTMLBody is refused), and Graph reads but cannot write Outlook's task fields (percent_complete other than 0 and 100, total_work, mileage...): setting one raises UnsupportedFeature.
  • resolve_names(): a room list is not in Graph's directory, so it is not found; a contact matches by the start of its names or a whole address, not the start of an address.
  • Creating an event with attendees mails them at once in Graph, so save() with attendees needs send_meeting_invitations=SEND_ONLY_TO_ALL or SEND_TO_ALL_AND_SAVE_COPY (the default raises before anything is written).

License

ewsgraph is source-available, not open source: it is licensed under the PolyForm Noncommercial License 1.0.0 (LICENSE.md), with an additional permission for work on open-source projects that depend on it (LICENSE-EXCEPTION.md). So it is free for personal and noncommercial use, for noncommercial organizations, and for developing, testing and distributing such a project, a company's work included. Business use outside those permitted purposes, such as running it for your company's own mail, needs a commercial license: https://sdsoftware.lemonsqueezy.com/checkout/buy/01420851-1e1f-4c83-b703-cec4cc6942d1 (Single App: one application, one Microsoft 365 tenant; Organization: every application in one tenant). People who get an open-source project built on ewsgraph get these same rights, not more. The library never stops for lack of a license: it works the same and says once per process what to do. Copyright SD Software LLC (https://sdsoftware.io/).

ewsgraph activate --personal                 # personal, noncommercial or open-source-project use: no key, no request
ewsgraph activate KEY --tenant TENANT        # a bought key, for the tenant your app works in
ewsgraph activate --status                   # what is recorded
ewsgraph activate --deactivate               # free the activation for another tenant or machine

The record lives in the user's config folder, or where EWSGRAPH_LICENSE_FILE points (a container can mount it). What reaches Lemon Squeezy (the store that sells the license): at activation, the key and the tenant you give to ewsgraph activate; every 30 days after, the key and its activation id; with each request, what any HTTPS request carries, such as your IP address. Nothing about mailboxes, messages or people. The record keeps the key, the activation id, the tenant and the product's name, not the buyer's name or e-mail. To silence the check: warnings.filterwarnings("ignore", category=ewsgraph.LicenseWarning).

ewsgraph follows exchangelib's API and keeps exchangelib's names; exchangelib is BSD-licensed, see NOTICE. ewsgraph is not affiliated with or endorsed by Microsoft or the exchangelib project. Microsoft, Exchange and Microsoft Graph are trademarks of Microsoft Corporation; they name the services ewsgraph works with.

Metadata

Release files for ewsgraph 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ewsgraph 0.1.0
File Size Uploaded Provenance Actions
ewsgraph-0.1.0.tar.gz 232.9 kB Without provenance Details for ewsgraph-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ewsgraph 0.1.0
File Interpreter ABI Platform Actions
ewsgraph-0.1.0-py3-none-any.whl Python 3 none any Details for ewsgraph-0.1.0-py3-none-any.whl

Total release size: 526.4 kB

Release files / ewsgraph-0.1.0.tar.gz

Download URL ewsgraph-0.1.0.tar.gz
Size 232.9 kB
Tags Source
SHA-256 checksum
How to use checksums
5ff27d2663ac41aa066552483f366850aee86d560947d2bf6686f1341ba7cacd
BLAKE2b-256 checksum
How to use checksums
cf95ef3927391569a66cee10ecc1eddf2b74f29736562caff99653e5568e9829
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / ewsgraph-0.1.0-py3-none-any.whl

Download URL ewsgraph-0.1.0-py3-none-any.whl
Size 293.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d1e42c364d83cf0bb737c1d0a363ef818632f99d5d26fb4485e8770f04ac7f1b
BLAKE2b-256 checksum
How to use checksums
aea98bcc0512ee1ef12cf02ae40c8af9b71dd0ecee63e491e0313e9291102a25
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for ewsgraph 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page