---
name: x402.api.agentmail.to
description: x402.api.agentmail.to exposes read-oriented AgentMail platform APIs covering inbox enumeration, thread and draft listing, domain and pod management, organization metadata retrieval, and historical email delivery metrics. All skills are query or list operations; no write, send, or delete capabilities are available through this host.
host: x402.api.agentmail.to
---

# x402.api.agentmail.to

This host surfaces the AgentMail platform's inspection and reporting surface for agents that need to audit account state, enumerate resources (inboxes, domains, pods, threads, drafts), or pull delivery statistics. It serves agents performing account discovery, pre-flight checks before downstream write operations, or monitoring workflows. It does not provide message creation, sending, inbox provisioning, or real-time event streaming.

## When to use this host

Use this host when an agent needs to inspect or enumerate AgentMail account resources (inboxes, domains, pods, threads, drafts) or pull historical delivery metrics. It is the right choice for read-only discovery, pre-flight checks, and reporting workflows. Do not use this host to send email, create or delete inboxes, provision domains, manage pods, or stream real-time events — those write and mutation operations require the AgentMail write API endpoints not exposed here. For fetching the full content of a specific thread or individual message body, this host also has no suitable skill; a message-detail endpoint on the AgentMail API would be needed instead.

## Capabilities

### Account and Organization Metadata

Retrieves top-level organization profile data including billing plan, rate limits, inbox and domain counts, and account identifiers — the foundational context for any downstream resource operation.

- **`fetch-org-directory`** — Returns organization profile data for the authenticated account on the AgentMail platform, including billing plan, inbox/domain counts, and rate limits.

### Resource Enumeration

Lists all major AgentMail resource types — inboxes, domains, and pods — returning IDs, names, and timestamps needed to reference specific resources in downstream operations.

- **`list-agentmail-inboxes`** — Returns a paginated list of AgentMail inbox records and a total count for the authenticated account.
- **`list-agentmail-domains`** — Returns a paginated list of domain records registered in the AgentMail account, including a total count and array of domain objects.
- **`list-agentmail-pods`** — Returns a paginated list of AgentMail pods belonging to the authenticated organization, including pod IDs, names, and timestamps.

### Message and Thread Inspection

Retrieves paginated lists of email conversation threads and unsent drafts from AgentMail inboxes, with filtering by label, date range, and folder type.

- **`list-agentmail-threads`** — Lists email threads from an AgentMail mailbox, with optional filtering by label, date range, spam/trash inclusion, and pagination.
- **`list-email-drafts`** — Returns a paginated list of email drafts from an AgentMail inbox, with optional filtering by label, date range, and sort order.

### Delivery and Usage Metrics

Queries historical email activity statistics — sent, delivered, bounced, complained, spam, and domain verification events — over a specified time window.

- **`fetch-agentmail-metrics`** — Queries AgentMail usage and delivery metrics for a given time range, returning per-event-type arrays covering message receipt, sending, delivery, bounces, complaints, rejections, spam, and domain verification.

## Workflows

### Account Capacity Pre-Flight Check

*Use when an agent needs to verify whether an AgentMail account has sufficient capacity (inbox slots, send limits, domain quota) before attempting to provision new resources.*

1. **`fetch-org-directory`** — Retrieve current billing plan, rate limits, and existing inbox and domain counts to establish baseline capacity.
2. **`list-agentmail-inboxes`** — Enumerate actual inboxes to confirm the live count matches org metadata and identify available slots.
3. **`list-agentmail-domains`** — Enumerate registered domains to verify domain quota usage before any new domain or inbox creation.

### Deliverability Audit

*Use when an agent needs to assess email deliverability health by correlating domain registration state with bounce, complaint, and spam metric trends.*

1. **`list-agentmail-domains`** — List all registered domains to identify which domains are active and subject to deliverability monitoring.
2. **`fetch-agentmail-metrics`** — Query bounce, complaint, spam, and domain verification event metrics for the relevant time window to surface deliverability issues.

### Inbox Thread and Draft Review

*Use when an agent needs to audit the current communication state of an inbox, reviewing both active conversation threads and pending unsent drafts together.*

1. **`list-agentmail-inboxes`** — Enumerate inboxes to obtain the target inbox identifier.
2. **`list-agentmail-threads`** — List conversation threads for the target inbox, applying label or date filters as needed.
3. **`list-email-drafts`** — List unsent drafts for the same inbox to identify messages awaiting review or sending.

## Skill reference

### `list-agentmail-threads`

**AgentMail List Threads** — Lists email threads from an AgentMail mailbox, with optional filtering by label, date range, spam/trash inclusion, and pagination.

*Use when:* Use when an agent needs to retrieve a paginated list of email conversation threads from an AgentMail inbox, optionally filtered by labels, date bounds, or folder type (spam, trash, blocked).

*Not for:* Do not use to fetch the full content of a specific thread or individual messages; use a thread detail or message endpoint instead.

**Inputs:**

- `Authorization` (string, required) — Bearer token for authentication. Must be passed as an HTTP header in the format 'Bearer <token>'.
- `limit` (integer) — Maximum number of threads to return in a single response.
- `page_token` (string) — Opaque token for fetching the next page of results, obtained from a prior response.
- `labels` (string) — Filter threads by one or more labels.
- `before` (string) — Return only threads with activity before this timestamp or date value.
- `after` (string) — Return only threads with activity after this timestamp or date value.
- `ascending` (boolean) — If true, return threads in ascending chronological order. Defaults to descending.
- `include_spam` (boolean) — If true, include threads marked as spam in the results.
- `include_blocked` (boolean) — If true, include threads from blocked senders in the results.
- `include_trash` (boolean) — If true, include threads in the trash in the results.

**Returns:** Returns a JSON object with a count integer and a threads array; both fields are present even when no threads match (count=0, threads=[]).

**Example:** `GET https://x402.api.agentmail.to/v0/threads?limit=20&labels=INBOX&ascending=false`

---

### `list-agentmail-pods`

**AgentMail List Pods** — Returns a paginated list of AgentMail pods belonging to the authenticated organization, including pod IDs, names, and timestamps.

*Use when:* Use when an agent needs to enumerate all pods in an AgentMail organization, retrieve pod IDs for downstream operations, or check pod creation and update times.

*Not for:* Do not use to create a new pod; use the POST /v0/pods endpoint instead. Not suitable for fetching individual pod details by ID.

**Inputs:**

- `Authorization` (string, required) — Bearer token for authentication. Must be provided as a header value in the format 'Bearer <token>'.
- `limit` (integer) — Maximum number of pods to return in a single page of results.
- `page_token` (string) — Opaque token used to fetch the next page of results from a previous response.
- `ascending` (boolean) — If true, results are returned in ascending order by creation time; otherwise descending.

**Returns:** Returns a count integer and a pods array, each entry containing organization_id, pod_id, name, created_at, and updated_at fields.

**Example:** `GET https://x402.api.agentmail.to/v0/pods?limit=20&ascending=true
Authorization: Bearer <your_token>`

---

### `fetch-agentmail-metrics`

**AgentMail Metrics** — Queries AgentMail usage and delivery metrics for a given time range, returning per-event-type arrays covering message receipt, sending, delivery, bounces, complaints, rejections, spam, and domain verification.

*Use when:* Use when an agent needs to retrieve email activity statistics from AgentMail, such as counts of sent, delivered, bounced, or complained messages, or to audit domain verification events over a specified time window.

*Not for:* Do not use for real-time streaming of email events; this is a single-shot query returning historical metric snapshots. Not suitable for retrieving message content or managing inboxes.

**Inputs:**

- `Authorization` (string, required) — Bearer authentication token for the AgentMail API. Pass as an HTTP header in the format 'Bearer <token>'.
- `event_types` (string) — Comma-separated list of metric event types to filter results (e.g. message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified).
- `start` (string) — Start of the time range for the metrics query (ISO 8601 datetime or similar timestamp format).
- `end` (string) — End of the time range for the metrics query (ISO 8601 datetime or similar timestamp format).
- `period` (string) — Aggregation period for bucketing metric data points (e.g. day, hour).
- `limit` (integer) — Maximum number of metric data points to return.
- `descending` (boolean) — If true, returns results in descending chronological order.

**Returns:** Returns a JSON object with one array per event type (message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified, etc.), each containing metric data points for the queried period.

**Example:** `GET https://x402.api.agentmail.to/v0/metrics?event_types=message.sent,message.delivered&start=2024-01-01T00:00:00Z&end=2024-01-31T23:59:59Z`

---

### `list-agentmail-inboxes`

**AgentMail Inbox List** — Returns a paginated list of AgentMail inbox records and a total count for the authenticated account.

*Use when:* Use when an agent needs to enumerate existing AgentMail inboxes, check how many inboxes exist, or retrieve inbox identifiers before performing inbox-specific operations.

*Not for:* Do not use to read messages inside an inbox; use a message-listing endpoint instead. Not suitable for creating or deleting inboxes.

**Inputs:**

- `Authorization` (string, required) — Bearer token for authentication. Pass as HTTP header in the format 'Bearer <token>'.
- `limit` (integer) — Maximum number of inbox records to return in a single response.
- `page_token` (string) — Opaque pagination cursor returned from a previous response; pass to retrieve the next page of results.
- `ascending` (boolean) — If true, returns inboxes in ascending order; if false or omitted, returns in descending order.

**Returns:** Returns a JSON object with a count integer and an inboxes array; both fields are present even when the account has no inboxes.

**Example:** `GET https://x402.api.agentmail.to/v0/inboxes?limit=20&ascending=true`

---

### `list-email-drafts`

**List Email Drafts** — Returns a paginated list of email drafts from an AgentMail inbox, with optional filtering by label, date range, and sort order.

*Use when:* Use when an agent needs to retrieve existing email drafts from an AgentMail account, such as to review unsent messages, resume a draft, or audit draft state before sending.

*Not for:* Do not use to list sent or received emails; use the messages/inbox endpoint instead. Not for creating or updating drafts.

**Inputs:**

- `Authorization` (string, required) — Bearer token for authenticating the request. Format: 'Bearer <token>'.
- `limit` (integer) — Maximum number of drafts to return in a single response.
- `page_token` (string) — Pagination cursor returned from a previous response to fetch the next page of results.
- `labels` (string) — Filter drafts by label(s).
- `before` (string) — Return only drafts created before this timestamp or date value.
- `after` (string) — Return only drafts created after this timestamp or date value.
- `ascending` (boolean) — If true, return drafts in ascending chronological order. Defaults to descending.

**Returns:** Returns a JSON object with a count integer and a drafts array; both fields are present even when no drafts exist (count=0, drafts=[]).

**Example:** `GET https://x402.api.agentmail.to/v0/drafts?limit=20&ascending=false`

---

### `list-agentmail-domains`

**AgentMail List Domains** — Returns a paginated list of domain records registered in the AgentMail account, including a total count and array of domain objects.

*Use when:* Use when an agent needs to enumerate all domains associated with an AgentMail account, check whether a specific domain exists, or retrieve domain records for downstream inbox or routing operations.

*Not for:* Do not use to create, update, or delete domains; use the AgentMail Create Domain or domain management endpoints instead. Not suitable for listing inboxes or messages.

**Inputs:**

- `Authorization` (string, required) — Bearer token for AgentMail authentication. Must be provided as an HTTP header in the format 'Bearer <token>'.
- `limit` (integer) — Maximum number of domain records to return per page.
- `page_token` (string) — Opaque pagination cursor returned from a previous response; pass to retrieve the next page of results.
- `ascending` (boolean) — If true, returns results in ascending order; if false or omitted, returns in descending order.

**Returns:** Returns a JSON object with a count integer and a domains array; both fields are present even when the account has no domains registered.

**Example:** `GET https://x402.api.agentmail.to/v0/domains?limit=20&ascending=true
Authorization: Bearer <your_token>`

---

### `fetch-org-directory`

**Org Directory API** — Returns organization profile data for the authenticated account on the AgentMail platform, including billing plan, inbox/domain counts, and rate limits.

*Use when:* Use when an agent needs to retrieve the current organization's metadata such as billing plan, send limits, inbox count, domain count, or account identifiers from AgentMail.

*Not for:* Do not use for listing multiple organizations or searching across accounts; this endpoint returns data for the single authenticated organization only.

**Returns:** Returns a single organization object with organization_id, authentication/billing identifiers, billing plan, five-minute send limit, inbox count, domain count, and created/updated timestamps.

**Example:** `GET https://x402.api.agentmail.to/v0/organizations`

---