agentmail-rs 0.1.0

Unofficial typed Rust client for AgentMail (agentmail.to), the email API for agents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# agentmail

[![crates.io](https://img.shields.io/crates/v/agentmail.svg)](https://crates.io/crates/agentmail)
[![docs.rs](https://img.shields.io/docsrs/agentmail)](https://docs.rs/agentmail)

> **Unofficial.** This is a community Rust client, **not affiliated with or
> endorsed by AgentMail**. AgentMail ships official
> [Python](https://github.com/agentmail-to/agentmail-python) and
> [TypeScript](https://github.com/agentmail-to/agentmail-toolkit) SDKs; this
> crate fills the Rust gap. Wire shapes track AgentMail's public
> [OpenAPI spec](https://docs.agentmail.to/openapi.json) (API v0), which may
> change; pin a version and read the changelog.

A typed, `async` client for [AgentMail](https://agentmail.to), the email API
for agents. Coverage is the transactional core:

- **Inboxes**: create / list / get / delete (free plan: 3 inboxes,
  3k emails/month, `@agentmail.to` addresses)
- **Messages**: send / list / get
- **Webhooks**: create / list / delete (e.g. `message.received`)
- **Pagination** on every list call (`Page { limit, page_token }`)

Deliberately small: `reqwest` + `serde` + `thiserror`, with permissive
deserialization (unknown fields are ignored) so API additions don't break you.
Requests carry a 30-second default timeout. TLS is **rustls with the ring
provider** (no OpenSSL, no aws-lc-rs, no C toolchain). The client installs ring
as the process default at construction; if your application already installs a
crypto provider, that choice is respected.

## Install

```sh
cargo add agentmail
```

## Usage

```rust,no_run
# async fn demo() -> Result<(), agentmail::Error> {
let client = agentmail::Client::from_env()?; // AGENTMAIL_API_KEY

let inbox = client
    .create_inbox(agentmail::CreateInbox {
        username: Some("my-agent".into()),
        ..Default::default()
    })
    .await?; // my-agent@agentmail.to

client
    .send_message(&inbox.inbox_id, agentmail::SendMessage {
        to: vec!["someone@example.com".into()],
        subject: Some("Hello".into()),
        text: Some("Sent from an agent's own inbox.".into()),
        ..Default::default()
    })
    .await?;

for m in client.list_messages(&inbox.inbox_id).await?.messages {
    println!("{:?}: {:?}", m.from, m.subject);
}
# Ok(()) }
```

`Client::from_env()` reads `AGENTMAIL_API_KEY` (and optional `AGENTMAIL_BASE_URL`
for the EU region or a mock server). For explicit config, use `Client::new(key,
base_url)`.

### Testing

The unit and mock-server tests (`cargo test`) run offline. For a live smoke
test that creates, exercises, and lists real inboxes against the API:

```sh
AGENTMAIL_API_KEY=... cargo run --example smoke
```

## Parity roadmap

Where this crate stands against the official Python/TypeScript SDKs
(API v0). Covered now:

- [x] Inboxes: create / list / get / delete
- [x] Messages: send / list / get
- [x] Webhooks: create / list / delete
- [x] Pagination (`limit` / `page_token` cursors)

Not covered yet, roughly in the order we'd like to add them (PRs welcome):

- [ ] Threads (list / get)
- [ ] Attachments (send and fetch)
- [ ] Message updates (labels, read state) and reply-to threading
- [ ] Drafts (create / send)
- [ ] Message list filters (labels, before/after, from/to/subject)
- [ ] Webhook update / get; signature verification helper (Svix)
- [ ] Domains and pods
- [ ] WebSocket / real-time events
- [ ] Automatic retries with backoff

Changes land in the [changelog](CHANGELOG.md).

## License

Licensed under either of [MIT](LICENSE-MIT) or
[Apache-2.0](LICENSE-APACHE) at your option.