Metadata-Version: 2.5
Name: ewsgraph
Version: 0.1.0
Summary: exchangelib-compatible API on Microsoft Graph
Project-URL: Homepage, https://sdsoftware.io/
Author: SD Software LLC
License-File: LICENSE-EXCEPTION.md
License-File: LICENSE.md
License-File: NOTICE
Keywords: calendar,email,ews,exchange online,exchangelib,microsoft graph,outlook
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Office/Business :: Groupware
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: msal>=1.28
Requires-Dist: tzlocal>=5.0
Provides-Extra: dev
Requires-Dist: cryptography>=42; extra == 'dev'
Requires-Dist: jsonschema>=4.21; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: live
Requires-Dist: exchangelib>=5.6; extra == 'live'
Description-Content-Type: text/markdown

# 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:

```diff
- from exchangelib import IMPERSONATION, OAUTH2, Account, Configuration, Identity, OAuth2Credentials, Q
+ from ewsgraph import IMPERSONATION, OAUTH2, Account, Configuration, Identity, OAuth2Credentials, Q
```

```python
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.
