Crate agentmail

Expand description

Unofficial typed Rust client for AgentMail, the email API for agents (official SDKs exist for Python and TypeScript; this fills the Rust gap).

Wire shapes follow AgentMail’s OpenAPI spec (docs.agentmail.to/openapi.json, API v0), with full coverage of the surface the official SDKs expose: inboxes, threads, messages, drafts, attachments, webhooks, domains, pods, allow/block lists, metrics, API keys, and agent onboarding. Everything deserializes permissively - unknown fields are ignored, optional fields default, so spec additions don’t break callers.

Resources that exist at more than one scope (threads, webhooks, lists, domains, …) are reached through a scope handle - Client::org, Client::inbox, or Client::pod - so the compiler rejects an operation the scope doesn’t support. Inbox-only resources (messages, drafts) live on Client::inbox.

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

client
    .inbox(&inbox.inbox_id)
    .send_text("someone@example.com", "Hello", "From an agent's own inbox.")
    .await?;

§Coverage

Inboxes, threads, messages (send/reply/forward/raw/batch), drafts, attachments, webhooks, domains, pods, allow/block lists, metrics, inbox events, API keys, organization, auth, and agent onboarding. Every list call is paginated (Page), and requests carry automatic retries with backoff.

§Features

retries (default): automatic retries with exponential backoff. Turn it off with default-features = false to drop the direct tokio dependency; 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.

Structs§

AgentSignup: Request body for agent_sign_up: start onboarding a new agent, which emails a one-time code to human_email.
AgentSignupResult: The response to agent_sign_up: the new organization, inbox, and its API key.
AgentVerifyResult: The result of agent_verify.
ApiKey: An API key’s metadata (never its secret material; see CreatedApiKey).
ApiKeyList: One page of API keys from list_api_keys_page.
Attachment: Attachment metadata as returned in message, thread, and draft responses. download_url (a short-lived presigned URL) is populated only by the attachment-download endpoints; the other fields describe the attachment in list and get responses.
BatchGetMessages: Request body for batch_get_messages.
BatchGetMessagesResponse: Response to batch_get_messages.
BatchUpdateMessages: Request body for batch_update_messages: apply the same label changes to many messages at once.
BatchUpdateMessagesResponse: Response to batch_update_messages.
Client: An authenticated handle on the AgentMail API. Cheap to clone-ish (it owns a pooled reqwest::Client); construct once and share by reference.
CreateApiKey: Request body for create_api_key.
CreateDomain: Request body for create_domain.
CreateDraft: Request body for create_draft. At least one recipient or a reply/forward-of reference and one of text/html are required by the API.
CreateInbox: Request body for create_inbox. All fields optional; the API generates a username when none is given.
CreateListEntry: Request body for create_list_entry.
CreatePod: Request body for create_pod. All fields optional.
CreateWebhook: Request body for create_webhook.
CreatedApiKey: The response to create_api_key. The full api_key secret is returned exactly once, here; store it now, as it cannot be retrieved again.
Domain: A sending domain, as the API returns it.
DomainList: One page of domains from list_domains_page.
Draft: A draft message, as the API returns it. List items are a subset of the full get-draft shape; every optional field defaults so both parse.
DraftList: One page of drafts from list_drafts_page.
Identity: Who the current API key authenticates as, from auth_me.
Inbox: An agent-owned inbox, as the API returns it.
InboxEvent: An entry in an inbox’s audit log (label changes, deliveries, etc.).
InboxEventList: One page of inbox events from list_inbox_events_page.
InboxList: One page of inboxes from list_inboxes_page.
InboxScope: A single inbox scope (/v0/inboxes/{inbox_id}/...).
ListEntries: One page of list entries from list_list_entries_page.
ListEntry: A single allow/block list entry.
Message: A message as the API returns it. List items are a subset of the full get-message shape; every non-id field defaults so both parse.
MessageList: One page of messages from list_messages_page.
MessageListFilters: Filters for list_messages_filtered and search_messages_page. Pagination fields (limit, page_token) live here because they share the same query-parameter namespace as the filter fields.
MetricBucket: One time-bucket of an event metric.
MetricsQuery: Query parameters for get_metrics_events and get_metrics_usage. types filters by event/usage type; leave it empty for all.
OrgScope: The organization scope (top-level, /v0/...), spanning every inbox.
Organization: The organization the current API key belongs to, from get_organization.
Page: Pagination controls for the list_*_page calls. Default is the API’s own defaults (first page, server-chosen page size).
Pod: A pod, a container that owns inboxes and other resources.
PodList: One page of pods from list_pods_page.
PodScope: A single pod scope (/v0/pods/{pod_id}/...).
RawMessage: The presigned download for a message’s raw RFC 822 source, from get_raw_message. Fetch the bytes with download_raw.
ReplyToMessage: Request body for reply_to_message and reply_all_to_message. The to field is derived from the parent message; at least one of text/html is required by the API.
RetryPolicyretries: How the client retries transient failures. Applied to every request at the one HTTP chokepoint. Default retries twice with exponential backoff.
Scoped: A Client bound to a Scope. Returned by Client::org, Client::inbox, and Client::pod; the resource methods it exposes depend on which capability traits the scope S implements.
SendAttachment: An attachment to include on an outgoing message or draft. Supply the bytes inline as base64 content, or a url for the API to fetch; set content_id to reference the attachment inline from the HTML body.
SendMessage: Request body for send_message. At least one recipient in to and one of text/html are required by the API.
SentMessage: The API’s acknowledgement of a send.
Thread: A conversation thread. List items omit messages; the get-thread shape includes them and search results carry highlights; every optional field defaults so all three parse into this one type.
ThreadList: One page of threads from a list or search call.
ThreadListFilters: Filters for list_threads_filtered and search_threads_page. Pagination fields (limit, page_token) share the same query-parameter namespace as the filters.
UpdateDomain: Request body for update_domain. Fields left None stay unchanged.
UpdateDraft: Request body for update_draft. Every field is optional; omitted fields are left unchanged on the server. Pass Some(vec![]) to clear a recipient field; pass None to leave it alone.
UpdateInbox: Request body for update_inbox. Fields left None are omitted and stay unchanged; set metadata to Some(Value::Null) to clear it.
UpdateMessage: Request body for update_message.
UpdateThread: Request body for update_thread: labels to add and/or remove.
UpdateWebhook: Request body for update_webhook. Every field is optional; leave a field empty to keep it unchanged. Inbox and pod targeting is edited by delta (add/remove lists) rather than by replacing the whole set.
UpdatedMessage: The API’s response to update_message: the message id and its labels after the update.
UpdatedThread: The API’s response to update_thread: the thread id and its labels after the update.
UsagePoint: One time-bucket of a usage metric.
VerificationRecord: A single DNS record to publish for a domain.
Webhook: A webhook subscription, as the API returns it.
WebhookList: One page of webhooks from list_webhooks_page.

Enums§

EntryType: Whether a list entry is an address or a whole domain.
Error: Everything that can go wrong talking to AgentMail.
ListDirection: Which traffic direction a list governs. A path input only (there is no wire value to decode), so it has no unknown variant.
ListKind: Whether a list allows or blocks its entries. A path input only, so it has no unknown variant.
ScopeType: What an API key is scoped to.
SignatureErrorwebhook-verify: Why webhook verification failed. Verification never “passes open”: a missing or malformed secret, header, or signature is always an error.

Constants§

DEFAULT_BASE_URL: The production API host. Override with Client::new(key, base_url) for the EU region (https://api.agentmail.eu) or a mock server.
DEFAULT_TIMEOUT: The per-request timeout applied by Client::new (connect + response).
DEFAULT_WEBHOOK_TOLERANCEwebhook-verify: The Svix-recommended timestamp tolerance (5 minutes).

Traits§

ApiKeys: Scopes with API keys (org / inbox / pod).
Domains: Scopes with domains (org / pod). Inboxes have no domains.
Drafts: Scopes with readable drafts (org / inbox / pod). Draft writes (create, update, delete, send) are inbox-only and live on Scoped<InboxScope>.
Inboxes: Scopes that contain inboxes (org / pod): list, create, get, update, delete inboxes within the scope. A pod owns its inboxes; the org owns all of them.
Lists: Scopes with allow/block lists (org / inbox / pod).
Metrics: Scopes with metrics (org / inbox / pod).
Scope: A scope’s URL prefix. Implemented by OrgScope, InboxScope, and PodScope.
Threads: Scopes with threads (org / inbox / pod).
Webhooks: Scopes with webhooks (org / inbox / pod).

Functions§

verify_webhook_signaturewebhook-verify: Verify a webhook delivery’s signature.
verify_webhook_timestampwebhook-verify: Reject deliveries whose svix-timestamp is more than tolerance away from now (in either direction), the standard defense against replayed payloads. See DEFAULT_WEBHOOK_TOLERANCE.

Type Aliases§

MetricsEvents: Event metrics keyed by event type (e.g. message.received).
MetricsUsage: Usage metrics keyed by usage type.

Crate agentmail

Crate agentmail Copy item path

§Coverage

§Features

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate agentmail