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?;

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.
RetryPolicy: 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.
SignatureError: 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_TOLERANCE: The Svix-recommended timestamp tolerance (5 minutes).

Functions§

verify_webhook_signature: Verify a webhook delivery’s signature.
verify_webhook_timestamp: 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

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate agentmail