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
- The app registration. Microsoft Graph application permissions instead of EWS's
full_access_as_app:Mail.ReadWriteandMail.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) andTasks.ReadWrite.All(tasks) if you use them.ewsgraph doctor --tenant-id ... --client-id ... --mailbox ...signs in and says which ones are missing. - Username and password sign-in. Exchange Online turned basic auth off; use
OAuth2Credentials. - 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 raisesUnsupportedQuery), 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 withsync_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
HTMLBodyis refused), and Graph reads but cannot write Outlook's task fields (percent_completeother than 0 and 100,total_work,mileage...): setting one raisesUnsupportedFeature. 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 needssend_meeting_invitations=SEND_ONLY_TO_ALLorSEND_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.