https://github.com/pimalaya/io-gmail
Gmail REST API client library for Rust
https://github.com/pimalaya/io-gmail
api client coroutine gmail io-free lib mail pim rest rust sans-io std v1
Last synced: about 5 hours ago
JSON representation
Gmail REST API client library for Rust
- Host: GitHub
- URL: https://github.com/pimalaya/io-gmail
- Owner: pimalaya
- License: apache-2.0
- Created: 2026-04-15T13:25:28.000Z (3 months ago)
- Default Branch: master
- Last Pushed: 2026-07-15T17:31:08.000Z (about 14 hours ago)
- Last Synced: 2026-07-15T19:19:15.612Z (about 12 hours ago)
- Topics: api, client, coroutine, gmail, io-free, lib, mail, pim, rest, rust, sans-io, std, v1
- Language: Rust
- Homepage: https://docs.rs/io-gmail/latest/io_gmail
- Size: 164 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# I/O Gmail [](https://docs.rs/io-gmail/latest/io_gmail) [](https://matrix.to/#/#pimalaya:matrix.org) [](https://fosstodon.org/@pimalaya)
Gmail REST 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 Gmail 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.
- **Full Gmail REST API v1 surface**: labels, messages, drafts, threads, history, settings and push notification management (see [API coverage](#api-coverage)).
- **Poll-based mailbox watching**: an infinite watch built on the history API, emitting one Gmail-native diff per tick and re-baselining itself on expired history cursors.
- **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 first-class verb 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 Gmail 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-gmail/latest/features).
## API coverage
The coroutines mirror the [Gmail REST API v1 reference](https://developers.google.com/gmail/api/reference/rest) one-to-one; every method below is an I/O-free coroutine:
| Resource | Methods |
|------------------------------------|-------------------------------------------------------------------------------------------|
| users | getProfile, watch, stop |
| users.labels | list, get, create, update, patch, delete |
| users.messages | list, get, send, insert, import, modify, batchModify, trash, untrash, delete, batchDelete |
| users.messages.attachments | get |
| users.drafts | list, get, create, update, send, delete |
| users.threads | list, get, modify, trash, untrash, delete |
| users.history | list |
| users.settings | get and update for imap, pop, vacation, language and autoForwarding |
| users.settings.delegates | list, get, create, delete |
| users.settings.filters | list, get, create, delete |
| users.settings.forwardingAddresses | list, get, create, delete |
| users.settings.sendAs | list, get, create, update, patch, delete, verify |
On top of the plain methods, a composed coroutine chains getProfile and history.list into an infinite poll-based mailbox watch, the polling alternative to the Pub/Sub push of watch and stop.
## Usage
The whole API is documented on [docs.rs](https://docs.rs/io-gmail/latest/io_gmail), including runnable snippets for every coroutine and client.
## Examples
The [./tests](./tests) folder demonstrates real usage: every coroutine runs against scripted in-memory HTTP responses, and an opt-in end-to-end test drives 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
- [Himalaya TUI](https://github.com/pimalaya/himalaya-tui): TUI to manage emails
## 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)