agentmail-rs

Unofficial. This is a community Rust client, not affiliated with or endorsed by AgentMail. AgentMail ships official Python and TypeScript SDKs; this crate fills the Rust gap. Wire shapes track AgentMail's public OpenAPI spec (API v0), which may change; pin a version and read the changelog.

A typed, async client for AgentMail, the email API for agents, with full coverage of the AgentMail API v0 at every scope:

Inboxes: create / list / get / update / delete
Threads: list / filter / search / get / update / delete
Messages: send / list / filter / search / get / update / delete, reply, reply-all, forward, raw source, batch get / update
Drafts: create / list / get / update / delete / send
Attachments: fetch metadata and download bytes (presigned)
Webhooks: create / list / get / update / delete, plus optional Svix signature verification
Domains: create / list / get / update / delete, verify, zone file
Pods, allow/block lists, metrics (events + usage), inbox events, API keys, organization, and agent sign-up / verify
Pagination on every list call, list_all_* helpers that drain it, and automatic retries with exponential backoff

Scopes

Resources that AgentMail exposes at more than one scope (threads, webhooks, lists, domains, metrics, API keys, drafts, inboxes) are reached through a typed scope handle so the compiler rejects an operation a scope doesn't support:

# async fn demo(client: agentmail::Client) -> Result<(), agentmail::Error> {
client.org().list_threads(Default::default()).await?;          // all inboxes
client.inbox("ib_1").list_threads(Default::default()).await?;  // one inbox
client.pod("pod_1").list_threads(Default::default()).await?;   // one pod
client.pod("pod_1").create_inbox(Default::default()).await?;   // inbox inside a pod
// client.inbox("ib_1").list_domains(..)  // compile error: inboxes have no domains
# Ok(()) }

Inbox-only resources (messages, drafts, inbox events) live on client.inbox(id); account-global ones (pods, organization, auth, agent) are flat on Client.

Deliberately small: reqwest + serde + thiserror (plus tokio for retry backoff), 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.

Features

retries (default): automatic retries with backoff. Turn it off with default-features = false to drop the direct tokio dependency and make every request a single attempt; tune it with Client::with_retry_policy.
webhook-verify (off by default): verify_webhook_signature for Svix-signed webhook deliveries. Adds ring (already the rustls provider) and base64.

Install

cargo add agentmail-rs

The crate publishes as agentmail-rs (the bare agentmail name was taken) but imports as agentmail. MSRV is Rust 1.86.

Usage

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

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

// The common case, in one line:
client
    .inbox(&inbox.inbox_id)
    .send_text("someone@example.com", "Hello", "Sent from an agent's own inbox.")
    .await?;

// Or build the full message for HTML, cc/bcc, attachments, labels:
client
    .inbox(&inbox.inbox_id)
    .send_message(agentmail::SendMessage {
        to: vec!["someone@example.com".into()],
        subject: Some("Hello".into()),
        html: Some("<p>Rich body.</p>".into()),
        ..Default::default()
    })
    .await?;

// Drain every page with a `list_all_*` helper:
for m in client.inbox(&inbox.inbox_id).list_all_messages(Default::default()).await? {
    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:

AGENTMAIL_API_KEY=... cargo run --example smoke

Receiving mail? The webhook example verifies a Svix-signed delivery end to end:

cargo run --example webhook --features webhook-verify

Parity

This crate binds the entire AgentMail API v0 surface the official Python/TypeScript SDKs expose, at all three scopes (organization, inbox, pod) via the typed scope handles above.

Two things the official SDKs also lack and this crate treats as extras: there is no WebSocket / realtime API to bind (AgentMail exposes none), and the Svix webhook signature verification helper here goes slightly beyond the SDKs (behind the webhook-verify feature). Beyond the SDKs, the list_all_* helpers drain pagination for you.

Changes land in the changelog.

Contributing

Issues and PRs are welcome. Wire shapes track AgentMail's OpenAPI spec, so when adding or changing an endpoint, match the spec and add a wiremock test under tests/http/ (the suite runs offline: cargo test --all-features). If you need a scope-mirrored endpoint variant that isn't bound yet, open an issue.

License

Licensed under either of MIT or Apache-2.0 at your option.

agentmail-rs 0.3.0