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.

let client = agentmail::Client::from_env()?; // AGENTMAIL_API_KEY
let inbox = client
    .create_inbox(agentmail::CreateInbox {
        username: Some("my-agent".into()),
        display_name: Some("My Agent".into()),
        ..Default::default()
    })
    .await?;
client
    .send_message(
        &inbox.inbox_id,
        agentmail::SendMessage {
            to: vec!["someone@example.com".into()],
            subject: Some("Hello".into()),
            text: Some("From an agent's own inbox.".into()),
            ..Default::default()
        },
    )
    .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 Client::agent_sign_up: start onboarding a new agent, which emails a one-time code to human_email.
AgentSignupResult: The response to Client::agent_sign_up: the new organization, inbox, and its API key.
AgentVerifyResult: The result of Client::agent_verify.
ApiKey: An API key’s metadata (never its secret material; see CreatedApiKey).
ApiKeyList: One page of API keys from Client::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 Client::batch_get_messages.
BatchGetMessagesResponse: Response to Client::batch_get_messages.
BatchUpdateMessages: Request body for Client::batch_update_messages: apply the same label changes to many messages at once.
BatchUpdateMessagesResponse: Response to Client::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 Client::create_api_key.
CreateDomain: Request body for Client::create_domain.
CreateDraft: Request body for Client::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 Client::create_inbox. All fields optional; the API generates a username when none is given.
CreateListEntry: Request body for Client::create_list_entry.
CreatePod: Request body for Client::create_pod. All fields optional.
CreateWebhook: Request body for Client::create_webhook.
CreatedApiKey: The response to Client::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 Client::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 Client::list_drafts_page.
Identity: Who the current API key authenticates as, from Client::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 Client::list_inbox_events_page.
InboxList: One page of inboxes from Client::list_inboxes_page.
ListEntries: One page of list entries from Client::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 Client::list_messages_page.
MessageListFilters: Filters for Client::list_messages_filtered and Client::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 Client::get_metrics_events and Client::get_metrics_usage. types filters by event/usage type; leave it empty for all.
Organization: The organization the current API key belongs to, from Client::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 Client::list_pods_page.
RawMessage: The presigned download for a message’s raw RFC 822 source, from Client::get_raw_message. Fetch the bytes with Client::download_raw.
ReplyToMessage: Request body for Client::reply_to_message and Client::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.
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 Client::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 Client::list_threads_filtered and Client::search_threads_page. Pagination fields (limit, page_token) share the same query-parameter namespace as the filters.
UpdateDomain: Request body for Client::update_domain. Fields left None stay unchanged.
UpdateDraft: Request body for Client::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 Client::update_inbox. Fields left None are omitted and stay unchanged; set metadata to Some(Value::Null) to clear it.
UpdateMessage: Request body for Client::update_message.
UpdateThread: Request body for Client::update_thread: labels to add and/or remove.
UpdateWebhook: Request body for Client::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 Client::update_message: the message id and its labels after the update.
UpdatedThread: The API’s response to Client::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 Client::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.
ListKind: Whether a list allows or blocks its entries.
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).

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§

Functions§

Type Aliases§

Crate agentmail