# I/O Microsoft Graph [](https://docs.rs/io-msgraph/latest/io_msgraph) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya)
Microsoft Graph API client library for Rust
This library is composed of 3 feature-gated layers:
- Low-level **I/O-free** coroutines: no_std-compatible state machines containing the whole Microsoft Graph REST logic, usable anywhere
- Mid-level **light client**: a standard, blocking client wrapping a stream you opened yourself
- High-level **full client**: the light client plus TCP connections and TLS negotiations handled for you
## Table of contents
- [Features](#features)
- [API coverage](#api-coverage)
- [Usage](#usage)
- [Examples](#examples)
- [AI disclosure](#ai-disclosure)
- [License](#license)
- [Social](#social)
- [Contributing](#contributing)
- [Sponsoring](#sponsoring)
## Features
- **I/O-free coroutines**: state machines with no socket, no async runtime and no forced I/O model; run them from any blocking, async or test harness.
- **Mail surface**: manage mail folders, messages and attachments, download raw MIME content, create drafts from JSON or MIME and send them (see [API coverage](#api-coverage)).
- **Contacts surface**: manage contact folders and contacts, with three-state update fields distinguishing a cleared field from a preserved one, and incremental change tracking through delta queries.
- **Bearer-token authentication**: requests carry the OAuth 2.0 access token you provide; minting and refreshing it stays under your control.
- **Light client**: a standard, blocking client exposing one method per operation over a stream you opened yourself (requires `client` feature).
- Full standard, blocking client with **TLS** support:
- [Rustls](https://crates.io/crates/rustls) with ring crypto (requires `rustls-ring` feature, enabled by default)
- [Rustls](https://crates.io/crates/rustls) with aws crypto (requires `rustls-aws` feature)
- [Native TLS](https://crates.io/crates/native-tls) (requires `native-tls` feature)
> [!TIP]
> I/O Microsoft Graph is written in [Rust](https://www.rust-lang.org/) and uses [cargo features](https://doc.rust-lang.org/cargo/reference/features.html) to gate the client layers. The default feature set is declared in [Cargo.toml](./Cargo.toml) or on [docs.rs](https://docs.rs/crate/io-msgraph/latest/features).
## API coverage
Microsoft Graph is a single API spanning many domains; io-msgraph covers it incrementally, mirroring the [Microsoft Graph v1.0 reference](https://learn.microsoft.com/en-us/graph/api/overview). Every operation below is an I/O-free coroutine; the calendar domain is planned next.
| Resource | Operations |
|----------------------------|----------------------------------------------------------------------------------------|
| users | get the signed-in user profile; sendMail action (JSON and MIME form) |
| users.mailFolders | list, get, create, update, delete, move, copy, list child folders |
| users.messages | list, get, get raw MIME, create draft from JSON or MIME, update, delete, move, copy, send |
| users.messages.attachments | list, create, get raw content, delete |
| users.contactFolders | list, get, create, update, delete, list child folders |
| users.contacts | list, get, create, update, delete, track changes with delta |
## Usage
The whole API is documented on [docs.rs](https://docs.rs/io-msgraph/latest/io_msgraph), including runnable snippets for the coroutines and the client.
## Examples
The [./tests](./tests) folder demonstrates real usage: every coroutine runs against scripted in-memory HTTP responses, and opt-in end-to-end tests run the full client against the live API.
Have also a look at real-world projects built on top of this library:
- [Himalaya CLI](https://github.com/pimalaya/himalaya): CLI to manage emails
- [Cardamum CLI](https://github.com/pimalaya/cardamum): CLI to manage contacts
## AI disclosure
This project is developed with AI assistance. This section documents how, so users and downstream packagers can make informed decisions.
- **Tools**: Claude Code (Anthropic), invoked locally with a persistent project-scoped memory and a small set of repo-specific rules.
- **Used for**: Refactors, mechanical multi-file edits, boilerplate (feature gates, error enums, derive macros, trait impls), test scaffolding, doc polish, exploratory design conversations.
- **Not used for**: Engineering, critical code, git manipulation (commit, merge, rebase…), real-world tests.
- **Verification**: Every AI-assisted change is read, compiled, tested, and formatted before commit. Behavioural correctness is verified against the relevant RFC or upstream spec, not assumed from the model output. Tests are never adjusted to fit AI-generated code; the code is adjusted to fit correct behaviour.
- **Limitations**: AI models occasionally produce code that compiles and passes tests but is subtly wrong. The verification workflow catches most of this; it does not catch all of it. Bug reports are welcome and taken seriously.
- **Last reviewed**: 15/07/2026
## License
This project is licensed under either of:
- [MIT license](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
at your option.
## Social
- Chat on [Matrix](https://matrix.to/#/#pimalaya:matrix.org)
- News on [Mastodon](https://fosstodon.org/@pimalaya) or [RSS](https://fosstodon.org/@pimalaya.rss)
- Mail at [pimalaya.org@posteo.net](mailto:pimalaya.org@posteo.net)
## Contributing
Contributions are welcome: start with [CONTRIBUTING.md](./CONTRIBUTING.md), which opens with the Pimalaya-wide guides to read first.
## Sponsoring
[](https://nlnet.nl/)
Special thanks to the [NLnet foundation](https://nlnet.nl/) and the [European Commission](https://www.ngi.eu/) that have been financially supporting the project for years:
- 2022 → 2023: [NGI Assure](https://nlnet.nl/project/Himalaya/)
- 2023 → 2024: [NGI Zero Entrust](https://nlnet.nl/project/Pimalaya/)
- 2024 → 2026: [NGI Zero Core](https://nlnet.nl/project/Pimalaya-PIM/)
- *2027 in preparation…*
If you appreciate the project, feel free to donate using one of the following providers:
[](https://github.com/sponsors/soywod)
[](https://ko-fi.com/soywod)
[](https://www.buymeacoffee.com/soywod)
[](https://liberapay.com/soywod)
[](https://thanks.dev/soywod)
[](https://www.paypal.com/paypalme/soywod)