Struct Client 

pub struct Client { /* private fields */ }

An authenticated handle on the AgentMail API. Cheap to clone-ish (it owns a pooled reqwest::Client); construct once and share by reference.

Implementations

impl Client

pub async fn agent_sign_up( &self, signup: AgentSignup, ) -> Result<AgentSignupResult, Error>

POST /v0/agent/sign-up, start onboarding a new agent. Emails a one-time code to human_email; confirm it with Client::agent_verify. Runs before any credential exists, so the client’s bearer token (if any) is irrelevant.

pub async fn agent_verify( &self, otp_code: &str, ) -> Result<AgentVerifyResult, Error>

POST /v0/agent/verify, confirm the one-time code from Client::agent_sign_up.

impl Client

pub async fn create_api_key( &self, key: CreateApiKey, ) -> Result<CreatedApiKey, Error>

POST /v0/api-keys, mint a new API key. The full secret is in CreatedApiKey::api_key and is shown only here; store it now.

pub async fn list_api_keys(&self) -> Result<ApiKeyList, Error>

GET /v0/api-keys (first page; see Client::list_api_keys_page).

pub async fn list_api_keys_page(&self, page: Page) -> Result<ApiKeyList, Error>

GET /v0/api-keys with pagination. Feed ApiKeyList::next_page_token back in as Page::page_token until it comes back None.

pub async fn delete_api_key(&self, api_key_id: &str) -> Result<(), Error>

DELETE /v0/api-keys/{api_key_id}

impl Client

pub async fn get_message_attachment( &self, inbox_id: &str, message_id: &str, attachment_id: &str, ) -> Result<Attachment, Error>

GET /v0/inboxes/{inbox_id}/messages/{message_id}/attachments/{attachment_id}. The returned Attachment carries a short-lived download_url; pass it to Client::download_attachment to fetch the bytes.

pub async fn get_thread_attachment( &self, inbox_id: &str, thread_id: &str, attachment_id: &str, ) -> Result<Attachment, Error>

GET /v0/inboxes/{inbox_id}/threads/{thread_id}/attachments/{attachment_id}.

pub async fn get_draft_attachment( &self, inbox_id: &str, draft_id: &str, attachment_id: &str, ) -> Result<Attachment, Error>

GET /v0/inboxes/{inbox_id}/drafts/{draft_id}/attachments/{attachment_id}.

pub async fn download_attachment( &self, attachment: &Attachment, ) -> Result<Vec<u8>, Error>

Download an attachment’s bytes from its presigned download_url. The URL is a short-lived S3 link fetched without the API bearer token, so obtain the Attachment from one of the get_*_attachment calls first (a plain response attachment carries no download_url and yields Error::NoDownloadUrl).

impl Client

pub async fn auth_me(&self) -> Result<Identity, Error>

GET /v0/auth/me, the Identity the current API key authenticates as.

impl Client

pub async fn create_domain(&self, domain: CreateDomain) -> Result<Domain, Error>

POST /v0/domains, add a sending domain. The response carries the DNS VerificationRecords to publish.

pub async fn list_domains(&self) -> Result<DomainList, Error>

GET /v0/domains (first page; see Client::list_domains_page).

pub async fn list_domains_page(&self, page: Page) -> Result<DomainList, Error>

GET /v0/domains with pagination. Feed DomainList::next_page_token back in as Page::page_token until it comes back None.

pub async fn get_domain(&self, domain_id: &str) -> Result<Domain, Error>

GET /v0/domains/{domain_id}

pub async fn update_domain( &self, domain_id: &str, update: UpdateDomain, ) -> Result<Domain, Error>

PATCH /v0/domains/{domain_id}, toggle feedback and subdomain settings.

pub async fn delete_domain(&self, domain_id: &str) -> Result<(), Error>

DELETE /v0/domains/{domain_id}

pub async fn verify_domain(&self, domain_id: &str) -> Result<(), Error>

POST /v0/domains/{domain_id}/verify, ask the API to re-check the DNS records. Returns once the check is queued; poll Client::get_domain for the resulting status.

pub async fn get_domain_zone_file( &self, domain_id: &str, ) -> Result<String, Error>

GET /v0/domains/{domain_id}/zone-file, the DNS records as a ready-to-import zone file (plain text, not JSON).

impl Client

pub async fn create_draft( &self, inbox_id: &str, draft: CreateDraft, ) -> Result<Draft, Error>

POST /v0/inboxes/{inbox_id}/drafts – create a draft. Supply in_reply_to to create a reply draft (with reply_all to address the whole thread) or forward_of to create a forward draft.

pub async fn list_drafts(&self, inbox_id: &str) -> Result<DraftList, Error>

GET /v0/inboxes/{inbox_id}/drafts (first page; see Client::list_drafts_page).

pub async fn list_drafts_page( &self, inbox_id: &str, page: Page, ) -> Result<DraftList, Error>

GET /v0/inboxes/{inbox_id}/drafts with pagination. Feed DraftList::next_page_token back in as Page::page_token until it comes back None.

pub async fn get_draft( &self, inbox_id: &str, draft_id: &str, ) -> Result<Draft, Error>

GET /v0/inboxes/{inbox_id}/drafts/{draft_id}

pub async fn update_draft( &self, inbox_id: &str, draft_id: &str, update: UpdateDraft, ) -> Result<Draft, Error>

PATCH /v0/inboxes/{inbox_id}/drafts/{draft_id} – edit fields on an existing draft. Passing None for an Option field leaves it unchanged; the API expects the field to be omitted, not set to null, when unchanged.

pub async fn delete_draft( &self, inbox_id: &str, draft_id: &str, ) -> Result<(), Error>

DELETE /v0/inboxes/{inbox_id}/drafts/{draft_id}

pub async fn send_draft( &self, inbox_id: &str, draft_id: &str, ) -> Result<SentMessage, Error>

POST /v0/inboxes/{inbox_id}/drafts/{draft_id}/send – send a draft. The draft is deleted after a successful send.

impl Client

pub async fn list_inbox_events( &self, inbox_id: &str, ) -> Result<InboxEventList, Error>

GET /v0/inboxes/{inbox_id}/events (first page; see Client::list_inbox_events_page).

pub async fn list_inbox_events_page( &self, inbox_id: &str, page: Page, ) -> Result<InboxEventList, Error>

GET /v0/inboxes/{inbox_id}/events with pagination, the inbox’s audit log.

impl Client

pub async fn create_inbox(&self, inbox: CreateInbox) -> Result<Inbox, Error>

POST /v0/inboxes, a new agent-owned email address. Free plans get {username}@agentmail.to; custom domains must be verified first.

pub async fn list_inboxes(&self) -> Result<InboxList, Error>

GET /v0/inboxes (first page; see Client::list_inboxes_page).

pub async fn list_inboxes_page(&self, page: Page) -> Result<InboxList, Error>

GET /v0/inboxes with pagination. Feed InboxList::next_page_token back in as Page::page_token until it comes back None.

pub async fn get_inbox(&self, inbox_id: &str) -> Result<Inbox, Error>

GET /v0/inboxes/{inbox_id}

pub async fn update_inbox( &self, inbox_id: &str, update: UpdateInbox, ) -> Result<Inbox, Error>

PATCH /v0/inboxes/{inbox_id}, update the display name and/or metadata.

pub async fn delete_inbox(&self, inbox_id: &str) -> Result<(), Error>

DELETE /v0/inboxes/{inbox_id}

impl Client

pub async fn list_list_entries( &self, direction: ListDirection, kind: ListKind, ) -> Result<ListEntries, Error>

GET /v0/lists/{direction}/{kind} (first page; see Client::list_list_entries_page).

pub async fn list_list_entries_page( &self, direction: ListDirection, kind: ListKind, page: Page, ) -> Result<ListEntries, Error>

GET /v0/lists/{direction}/{kind} with pagination. Feed ListEntries::next_page_token back in as Page::page_token until it comes back None.

pub async fn create_list_entry( &self, direction: ListDirection, kind: ListKind, entry: CreateListEntry, ) -> Result<ListEntry, Error>

POST /v0/lists/{direction}/{kind}, add an address or domain to the list.

pub async fn get_list_entry( &self, direction: ListDirection, kind: ListKind, entry: &str, ) -> Result<ListEntry, Error>

GET /v0/lists/{direction}/{kind}/{entry}

pub async fn delete_list_entry( &self, direction: ListDirection, kind: ListKind, entry: &str, ) -> Result<(), Error>

DELETE /v0/lists/{direction}/{kind}/{entry}

impl Client

pub async fn send_message( &self, inbox_id: &str, message: SendMessage, ) -> Result<SentMessage, Error>

POST /v0/inboxes/{inbox_id}/messages/send

pub async fn send_text( &self, inbox_id: &str, to: &str, subject: &str, text: &str, ) -> Result<SentMessage, Error>

Send a plain-text message to a single recipient: the common case, in one line. For anything richer (HTML, cc/bcc, attachments, labels), build a SendMessage and call Client::send_message.

pub async fn list_messages(&self, inbox_id: &str) -> Result<MessageList, Error>

GET /v0/inboxes/{inbox_id}/messages (first page; see Client::list_messages_page).

pub async fn list_messages_page( &self, inbox_id: &str, page: Page, ) -> Result<MessageList, Error>

GET /v0/inboxes/{inbox_id}/messages with pagination. Feed MessageList::next_page_token back in as Page::page_token until it comes back None.

pub async fn get_message( &self, inbox_id: &str, message_id: &str, ) -> Result<Message, Error>

GET /v0/inboxes/{inbox_id}/messages/{message_id}

pub async fn reply_to_message( &self, inbox_id: &str, message_id: &str, reply: ReplyToMessage, ) -> Result<SentMessage, Error>

POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply – reply to a message. The to field is derived from the parent message; only text/html/cc/bcc are caller-supplied.

pub async fn reply_all_to_message( &self, inbox_id: &str, message_id: &str, reply: ReplyToMessage, ) -> Result<SentMessage, Error>

POST /v0/inboxes/{inbox_id}/messages/{message_id}/reply-all – reply to all recipients of a message.

pub async fn update_message( &self, inbox_id: &str, message_id: &str, update: UpdateMessage, ) -> Result<UpdatedMessage, Error>

PATCH /v0/inboxes/{inbox_id}/messages/{message_id} – update a message’s labels (read state is a label, e.g. add/remove unread). Returns the message id and its labels after the change, not the full message body.

pub async fn delete_message( &self, inbox_id: &str, message_id: &str, ) -> Result<(), Error>

DELETE /v0/inboxes/{inbox_id}/messages/{message_id} – permanently deletes a message.

pub async fn list_messages_filtered( &self, inbox_id: &str, filters: MessageListFilters, ) -> Result<MessageList, Error>

GET /v0/inboxes/{inbox_id}/messages with filters and pagination. Pass MessageListFilters with any filter fields set to narrow results. Feed MessageList::next_page_token back in as MessageListFilters::page_token until it comes back None.

pub async fn search_messages( &self, inbox_id: &str, query: &str, ) -> Result<MessageList, Error>

GET /v0/inboxes/{inbox_id}/messages/search with filters. Feed MessageList::next_page_token back in as MessageListFilters::page_token until it comes back None.

pub async fn search_messages_page( &self, inbox_id: &str, query: &str, filters: MessageListFilters, ) -> Result<MessageList, Error>

GET /v0/inboxes/{inbox_id}/messages/search with pagination.

pub async fn forward_message( &self, inbox_id: &str, message_id: &str, message: SendMessage, ) -> Result<SentMessage, Error>

POST /v0/inboxes/{inbox_id}/messages/{message_id}/forward, forward a message. Reuses SendMessage for the new recipients and any added body.

pub async fn get_raw_message( &self, inbox_id: &str, message_id: &str, ) -> Result<RawMessage, Error>

GET /v0/inboxes/{inbox_id}/messages/{message_id}/raw, a presigned URL for the message’s raw RFC 822 (.eml) source. Fetch the bytes with Client::download_raw.

pub async fn download_raw(&self, raw: &RawMessage) -> Result<Vec<u8>, Error>

Download the raw .eml bytes from a RawMessage’s presigned URL, without the API bearer token (the URL is already authenticated).

pub async fn batch_get_messages( &self, inbox_id: &str, message_ids: Vec<String>, ) -> Result<BatchGetMessagesResponse, Error>

POST /v0/inboxes/{inbox_id}/messages/batch-get, fetch many messages by id in one call.

pub async fn batch_update_messages( &self, inbox_id: &str, update: BatchUpdateMessages, ) -> Result<BatchUpdateMessagesResponse, Error>

POST /v0/inboxes/{inbox_id}/messages/batch-update, apply the same label changes to many messages at once.

impl Client

pub async fn get_metrics_events( &self, query: MetricsQuery, ) -> Result<MetricsEvents, Error>

GET /v0/metrics/events, event counts bucketed over time, keyed by event type.

pub async fn get_metrics_usage( &self, query: MetricsQuery, ) -> Result<MetricsUsage, Error>

GET /v0/metrics/usage, usage values bucketed over time, keyed by usage type.

impl Client

pub async fn get_organization(&self) -> Result<Organization, Error>

GET /v0/organizations, the organization the current key belongs to, including its resource counts and plan limits.

impl Client

pub async fn create_pod(&self, pod: CreatePod) -> Result<Pod, Error>

POST /v0/pods, create a pod.

pub async fn list_pods(&self) -> Result<PodList, Error>

GET /v0/pods (first page; see Client::list_pods_page).

pub async fn list_pods_page(&self, page: Page) -> Result<PodList, Error>

GET /v0/pods with pagination. Feed PodList::next_page_token back in as Page::page_token until it comes back None.

pub async fn get_pod(&self, pod_id: &str) -> Result<Pod, Error>

GET /v0/pods/{pod_id}

pub async fn delete_pod(&self, pod_id: &str) -> Result<(), Error>

DELETE /v0/pods/{pod_id}

impl Client

pub async fn list_threads(&self, inbox_id: &str) -> Result<ThreadList, Error>

GET /v0/inboxes/{inbox_id}/threads (first page; see Client::list_threads_page).

pub async fn list_threads_page( &self, inbox_id: &str, page: Page, ) -> Result<ThreadList, Error>

GET /v0/inboxes/{inbox_id}/threads with pagination. Feed ThreadList::next_page_token back in as Page::page_token until it comes back None.

pub async fn list_threads_filtered( &self, inbox_id: &str, filters: ThreadListFilters, ) -> Result<ThreadList, Error>

GET /v0/inboxes/{inbox_id}/threads with filters and pagination. Pass ThreadListFilters with any fields set to narrow results.

pub async fn search_threads( &self, inbox_id: &str, query: &str, ) -> Result<ThreadList, Error>

GET /v0/inboxes/{inbox_id}/threads/search, full-text search over the inbox’s threads. The matched fragments come back in Thread::highlights.

pub async fn search_threads_page( &self, inbox_id: &str, query: &str, filters: ThreadListFilters, ) -> Result<ThreadList, Error>

GET /v0/inboxes/{inbox_id}/threads/search with filters and pagination.

pub async fn get_thread( &self, inbox_id: &str, thread_id: &str, ) -> Result<Thread, Error>

GET /v0/inboxes/{inbox_id}/threads/{thread_id}, the full thread with its messages.

pub async fn update_thread( &self, inbox_id: &str, thread_id: &str, update: UpdateThread, ) -> Result<UpdatedThread, Error>

PATCH /v0/inboxes/{inbox_id}/threads/{thread_id}, add and/or remove labels across the thread. Returns the thread id and its labels after the change.

pub async fn delete_thread( &self, inbox_id: &str, thread_id: &str, ) -> Result<(), Error>

DELETE /v0/inboxes/{inbox_id}/threads/{thread_id}.

impl Client

pub async fn create_webhook( &self, webhook: CreateWebhook, ) -> Result<Webhook, Error>

POST /v0/webhooks, subscribe an HTTPS endpoint to events (e.g. message.received). The response carries the signing secret exactly once; store it.

pub async fn list_webhooks(&self) -> Result<WebhookList, Error>

GET /v0/webhooks (first page; see Client::list_webhooks_page).

pub async fn list_webhooks_page(&self, page: Page) -> Result<WebhookList, Error>

GET /v0/webhooks with pagination. Feed WebhookList::next_page_token back in as Page::page_token until it comes back None.

pub async fn get_webhook(&self, webhook_id: &str) -> Result<Webhook, Error>

GET /v0/webhooks/{webhook_id}

pub async fn update_webhook( &self, webhook_id: &str, update: UpdateWebhook, ) -> Result<Webhook, Error>

PATCH /v0/webhooks/{webhook_id}, edit event types and inbox/pod targeting. Inbox and pod sets change by delta (see UpdateWebhook).

pub async fn delete_webhook(&self, webhook_id: &str) -> Result<(), Error>

DELETE /v0/webhooks/{webhook_id}

impl Client

pub fn new(api_key: impl Into<String>, base_url: impl Into<String>) -> Self

A client against base_url (see DEFAULT_BASE_URL), with a DEFAULT_TIMEOUT on every request.

pub fn from_env() -> Result<Self, Error>

From AGENTMAIL_API_KEY (+ optional AGENTMAIL_BASE_URL).

pub fn with_retry_policy(self, policy: RetryPolicy) -> Self

Available on crate feature retries only.

Replace the RetryPolicy. Set max_retries to 0 to disable retries.

Requires the retries feature (on by default).

Trait Implementations

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.