diff --git a/bin/check-seo-metadata.mjs b/bin/check-seo-metadata.mjs new file mode 100644 index 00000000..25ecfd19 --- /dev/null +++ b/bin/check-seo-metadata.mjs @@ -0,0 +1,143 @@ +import { readFileSync, readdirSync, statSync } from "node:fs"; +import { dirname, join, relative } from "node:path"; +import { fileURLToPath } from "node:url"; + +const MIN_DESCRIPTION_LENGTH = 150; +const MAX_DESCRIPTION_LENGTH = 160; +const root = join(dirname(fileURLToPath(import.meta.url)), ".."); +const fern = join(root, "fern"); +const errors = []; +const descriptions = new Map(); + +function checkDescription(label, value) { + if (value == null || value === "") { + errors.push(`${label}: missing description`); + return; + } + + const length = [...value].length; + if (length < MIN_DESCRIPTION_LENGTH || length > MAX_DESCRIPTION_LENGTH) { + errors.push( + `${label}: description is ${length} characters; expected ${MIN_DESCRIPTION_LENGTH}-${MAX_DESCRIPTION_LENGTH}`, + ); + } + + const matches = descriptions.get(value) ?? []; + matches.push(label); + descriptions.set(value, matches); +} + +function frontmatterDescription(file) { + const source = readFileSync(file, "utf8"); + if (!source.startsWith("---\n")) return undefined; + const end = source.indexOf("\n---\n", 4); + if (end === -1) return undefined; + const match = source.slice(4, end).match(/^description:\s*(.+)$/m); + if (!match) return undefined; + const raw = match[1].trim(); + if (raw.startsWith('"')) { + try { + return JSON.parse(raw); + } catch { + return undefined; + } + } + return raw.replace(/^['"]|['"]$/g, ""); +} + +function walkYaml(directory) { + return readdirSync(directory).flatMap((entry) => { + const file = join(directory, entry); + return statSync(file).isDirectory() + ? walkYaml(file) + : file.endsWith(".yml") + ? [file] + : []; + }); +} + +function followingDocs(lines, start, itemIndent) { + const nextItem = new RegExp(`^ {${itemIndent}}[A-Za-z0-9_-]+:$`); + const docs = new RegExp(`^ {${itemIndent + 2}}docs:(?:\\s+(.*))?$`); + for (let index = start + 1; index < lines.length; index += 1) { + if (nextItem.test(lines[index])) return undefined; + const match = lines[index].match(docs); + if (!match) continue; + if (match[1] && match[1] !== "|") return match[1].trim(); + for (let content = index + 1; content < lines.length; content += 1) { + const value = lines[content].trim(); + if (value) return value; + } + return undefined; + } + return undefined; +} + +const docsPath = join(fern, "docs.yml"); +const docsSource = readFileSync(docsPath, "utf8"); +const activeMdx = [ + ...docsSource.matchAll(/^\s+(?:path|summary): (.+\.mdx)$/gm), +].map((match) => match[1]); + +for (const mdx of activeMdx) { + checkDescription(mdx, frontmatterDescription(join(fern, mdx))); +} + +const globalDescription = docsSource.match( + /^\s+og:description:\s*"([^"]+)"$/m, +)?.[1]; +checkDescription("docs.yml metadata.og:description", globalDescription); +checkDescription( + "changelog/overview.mdx", + frontmatterDescription(join(fern, "changelog", "overview.mdx")), +); + +for (const file of walkYaml(join(fern, "definition"))) { + const lines = readFileSync(file, "utf8").split("\n"); + const label = relative(root, file); + for (let index = 0; index < lines.length; index += 1) { + const endpoint = lines[index].match(/^ {6}display-name:\s*(.+)$/); + if (endpoint) { + checkDescription( + `${label}: ${endpoint[1]}`, + followingDocs(lines, index, 4), + ); + continue; + } + + const webhook = lines[index].match(/^ {4}display-name:\s*(.+)$/); + if (file.endsWith("/webhooks/events.yml") && webhook) { + checkDescription( + `${label}: ${webhook[1]}`, + followingDocs(lines, index, 2), + ); + } + } +} + +const channelSource = readFileSync( + join(fern, "definition", "websockets.yml"), + "utf8", +); +checkDescription( + "fern/definition/websockets.yml: Connect", + channelSource.match(/^\s{2}docs:\s*(.+)$/m)?.[1], +); + +for (const [description, labels] of descriptions) { + if (labels.length > 1) { + errors.push( + `duplicate description for ${labels.join(", ")}: ${description}`, + ); + } +} + +if (errors.length > 0) { + console.error(errors.join("\n")); + process.exit(1); +} + +console.log( + `SEO metadata check passed: ${activeMdx.length} MDX pages, ` + + `${descriptions.size - activeMdx.length - 2} generated API pages, and site defaults.`, +); diff --git a/fern/changelog/overview.mdx b/fern/changelog/overview.mdx index 0c6af249..0b085d3e 100644 --- a/fern/changelog/overview.mdx +++ b/fern/changelog/overview.mdx @@ -1,3 +1,7 @@ +--- +description: "Follow AgentMail API, SDK, webhook, WebSocket, and platform updates, including new capabilities, behavior changes, bug fixes, and clear migration guidance." +--- + # AgentMail Changelog Latest API and SDK updates. [Subscribe via RSS](https://docs.agentmail.to/changelog.rss) · [Discord](https://discord.gg/hTYatWYWBc) diff --git a/fern/definition/agent.yml b/fern/definition/agent.yml index 9aeac29d..2dd1639b 100644 --- a/fern/definition/agent.yml +++ b/fern/definition/agent.yml @@ -64,6 +64,8 @@ service: path: /sign-up display-name: Sign Up docs: | + Use the AgentMail API to create an agent organization, inbox, and API key. Review authentication, parameters, response fields, errors, and usage details. + Create a new agent organization with an inbox and API key. This endpoint is for signing up for the first time. If you've already signed up, you're all set — just use your existing API key. A 6-digit OTP is sent to the human's email for verification. @@ -87,6 +89,8 @@ service: display-name: Verify auth: true docs: | + Use the AgentMail API to verify a new agent organization with its one-time passcode. Review authentication, parameters, responses, errors, and usage details. + Verify an agent organization using the 6-digit OTP sent to the human's email during sign-up. On success, the organization is upgraded from `agent_unverified` to `agent_verified`, the send allowlist is removed, and free plan entitlements are applied. diff --git a/fern/definition/api-keys.yml b/fern/definition/api-keys.yml index b7586920..2cf04b8a 100644 --- a/fern/definition/api-keys.yml +++ b/fern/definition/api-keys.yml @@ -332,6 +332,8 @@ service: path: "" display-name: List API Keys docs: | + Use the AgentMail API to list API keys for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail api-keys list @@ -349,6 +351,8 @@ service: path: "" display-name: Create API Key docs: | + Use the AgentMail API to create an API key for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail api-keys create --name "My Key" @@ -363,6 +367,8 @@ service: path: /{api_key_id} display-name: Delete API Key docs: | + Use the AgentMail API to delete an API key for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail api-keys delete --api-key-id @@ -377,7 +383,9 @@ service: path: /public-keys display-name: List Public-Key Credentials docs: | - List only public-key credentials visible to the bearer caller's scope. + List public-key credentials visible to the bearer API key scope, with pagination details, while excluding bearer credentials from every returned result. + + Only public-key credentials visible to the bearer caller's scope are returned. Bearer credentials are never returned, even though both credential types share storage and pagination indexes. Requires `api_key_read`. request: @@ -393,7 +401,9 @@ service: path: /public-keys display-name: Register Public-Key Credential docs: | - Register a public P-256 JWK using an existing AgentMail bearer API key + Register a scoped P-256 public JWK for AgentID sign-in using an authorized bearer API key, while keeping all private key material entirely outside AgentMail. + + Register the JWK using an existing AgentMail bearer API key with `api_key_create`. Re-registering the same JWK creates a new credential ID; it does not replace or recover an earlier credential. The private key must never be sent to AgentMail. @@ -408,7 +418,9 @@ service: path: /public-keys/{api_key_id} display-name: Rename Public-Key Credential docs: | - Rename the credential. All security-relevant fields are immutable. + Rename an existing public-key credential while preserving its immutable key material, identifier, scope, permissions, generation, and expiration settings. + + All security-relevant fields are immutable. Requires `api_key_update`. path-parameters: api_key_id: @@ -425,7 +437,9 @@ service: path: /public-keys/{api_key_id} display-name: Revoke Public-Key Credential docs: | - Permanently revoke one public-key credential. This hard-deletes the + Permanently revoke and delete one public-key credential by its ID, requiring API key deletion permission and returning not found if the request repeats. + + This hard-deletes the credential; repeating the request returns not found. Requires `api_key_delete`. path-parameters: @@ -442,6 +456,8 @@ service: path: /public-keys/agentid-sign-in/revoke-all display-name: Revoke All AgentID Sign-In Keys docs: | + Revoke every current AgentID public-key sign-in credential in an organization with a required idempotency key and a permanent generation-change receipt. + Invalidate every current public-key credential in the caller's organization by advancing its AgentID key generation. The caller must be organization-scoped and either have `api_key_delete` or, for a verified diff --git a/fern/definition/auth.yml b/fern/definition/auth.yml index 1431b494..9d588368 100644 --- a/fern/definition/auth.yml +++ b/fern/definition/auth.yml @@ -42,6 +42,8 @@ service: path: /me display-name: Who Am I docs: | + Use the AgentMail API to inspect the identity and scope of the current credential. Review authentication, parameters, responses, errors, and usage details. + Returns the identity and scope of the authenticated credential. Useful when a client holds a pod-scoped or inbox-scoped API key and needs to discover the parent organization, pod, or inbox without prior knowledge. **CLI:** diff --git a/fern/definition/domains.yml b/fern/definition/domains.yml index 0b721038..fcc94613 100644 --- a/fern/definition/domains.yml +++ b/fern/definition/domains.yml @@ -142,6 +142,8 @@ service: path: "" display-name: List Domains docs: | + Use the AgentMail API to list domains for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail domains list @@ -159,6 +161,8 @@ service: path: /{domain_id} display-name: Get Domain docs: | + Use the AgentMail API to get a domain for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail domains get --domain-id @@ -174,6 +178,8 @@ service: path: /{domain_id}/zone-file display-name: Get Zone File docs: | + Use the AgentMail API to get a zone file for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail domains get-zone-file --domain-id @@ -189,6 +195,8 @@ service: path: "" display-name: Create Domain docs: | + Use the AgentMail API to create a domain for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail domains create --domain example.com @@ -203,6 +211,8 @@ service: path: /{domain_id} display-name: Update Domain docs: | + Use the AgentMail API to update a domain for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail domains update --domain-id @@ -219,6 +229,8 @@ service: path: /{domain_id} display-name: Delete Domain docs: | + Use the AgentMail API to delete a domain for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail domains delete --domain-id @@ -233,6 +245,8 @@ service: path: /{domain_id}/verify display-name: Verify Domain docs: | + Use the AgentMail API to verify a domain for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail domains verify --domain-id diff --git a/fern/definition/drafts.yml b/fern/definition/drafts.yml index f13371e8..84b77911 100644 --- a/fern/definition/drafts.yml +++ b/fern/definition/drafts.yml @@ -208,6 +208,8 @@ service: path: "" display-name: List Drafts docs: | + Use the AgentMail API to list drafts for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail drafts list @@ -230,6 +232,8 @@ service: path: /{draft_id} display-name: Get Draft docs: | + Use the AgentMail API to get a draft for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail drafts get --draft-id @@ -245,6 +249,8 @@ service: path: /{draft_id}/attachments/{attachment_id} display-name: Get Attachment docs: | + Use the AgentMail API to get an attachment from a draft for the authenticated organization. Review authentication, parameters, responses, and error behavior. + **CLI:** ```bash agentmail drafts get-attachment --draft-id --attachment-id diff --git a/fern/definition/inboxes/__package__.yml b/fern/definition/inboxes/__package__.yml index 7a89332f..0c3ab29a 100644 --- a/fern/definition/inboxes/__package__.yml +++ b/fern/definition/inboxes/__package__.yml @@ -121,6 +121,8 @@ service: path: "" display-name: List Inboxes docs: | + Use the AgentMail API to list inboxes for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail inboxes list @@ -138,6 +140,8 @@ service: path: /{inbox_id} display-name: Get Inbox docs: | + Use the AgentMail API to get an inbox for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail inboxes get --inbox-id @@ -153,6 +157,8 @@ service: path: "" display-name: Create Inbox docs: | + Use the AgentMail API to create an inbox for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail inboxes create --display-name "My Agent" --username myagent --domain agentmail.to @@ -168,6 +174,8 @@ service: path: /{inbox_id} display-name: Update Inbox docs: | + Use the AgentMail API to update an inbox for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail inboxes update --inbox-id --display-name "Updated Name" @@ -188,6 +196,8 @@ service: path: /{inbox_id} display-name: Delete Inbox docs: | + Use the AgentMail API to delete an inbox for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail inboxes delete --inbox-id diff --git a/fern/definition/inboxes/api-keys.yml b/fern/definition/inboxes/api-keys.yml index 83f75449..7cbd5285 100644 --- a/fern/definition/inboxes/api-keys.yml +++ b/fern/definition/inboxes/api-keys.yml @@ -18,6 +18,8 @@ service: path: "" display-name: List API Keys docs: | + Use the AgentMail API to list API keys within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:api-keys list --inbox-id @@ -36,6 +38,8 @@ service: path: "" display-name: Create API Key docs: | + Use the AgentMail API to create an API key within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail inboxes:api-keys create --inbox-id --name "My Key" @@ -51,6 +55,8 @@ service: path: /{api_key_id} display-name: Delete API Key docs: | + Use the AgentMail API to delete an API key within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail inboxes:api-keys delete --inbox-id --api-key-id diff --git a/fern/definition/inboxes/drafts.yml b/fern/definition/inboxes/drafts.yml index 09d1bad4..fabe32e5 100644 --- a/fern/definition/inboxes/drafts.yml +++ b/fern/definition/inboxes/drafts.yml @@ -20,6 +20,8 @@ service: path: "" display-name: List Drafts docs: | + Use the AgentMail API to list drafts within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:drafts list --inbox-id @@ -42,6 +44,8 @@ service: path: /{draft_id} display-name: Get Draft docs: | + Use the AgentMail API to get a draft within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:drafts get --inbox-id --draft-id @@ -57,6 +61,8 @@ service: path: /{draft_id}/attachments/{attachment_id} display-name: Get Attachment docs: | + Use the AgentMail API to get an attachment from a draft within a specific inbox. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail inboxes:drafts get-attachment --inbox-id --draft-id --attachment-id @@ -73,7 +79,9 @@ service: path: "" display-name: Create Draft docs: | - Create a draft. Supply `in_reply_to` to create a reply draft (with + Create inbox drafts for replies, reply-all, or forwards, deriving recipients and threading for replies while keeping forward recipients caller-supplied. + + Supply `in_reply_to` to create a reply draft (with `reply_all` to address the whole thread), whose recipients, subject, and threading are derived from the referenced message, or `forward_of` to create a forward draft, which derives the subject, threading, and @@ -94,7 +102,9 @@ service: path: /{draft_id} display-name: Update Draft docs: | - Edit fields on an existing draft. Passing `null` clears a field (or `[]` + Update an inbox draft, clear fields with null values or empty recipient lists, reschedule or cancel scheduled sending, and handle editing conflicts safely. + + Passing `null` clears a field (or `[]` for a recipient field); `send_at: null` un-schedules a scheduled draft. A draft that is already being sent cannot be edited. @@ -116,6 +126,8 @@ service: path: /{draft_id} display-name: Delete Draft docs: | + Use the AgentMail API to delete a draft within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:drafts delete --inbox-id --draft-id @@ -131,6 +143,8 @@ service: display-name: Send Draft idempotent: true docs: | + Use the AgentMail API to send a draft within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:drafts send --inbox-id --draft-id diff --git a/fern/definition/inboxes/events.yml b/fern/definition/inboxes/events.yml index 7962ba9c..7a5f2edb 100644 --- a/fern/definition/inboxes/events.yml +++ b/fern/definition/inboxes/events.yml @@ -18,6 +18,8 @@ service: path: "" display-name: List Inbox Events docs: | + Use the AgentMail API to list inbox events within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + List label change events for an inbox. Returns events in reverse chronological order by default. Use for IMAP UID projection or audit logging. **CLI:** diff --git a/fern/definition/inboxes/lists.yml b/fern/definition/inboxes/lists.yml index 2172ea57..2dbf60c4 100644 --- a/fern/definition/inboxes/lists.yml +++ b/fern/definition/inboxes/lists.yml @@ -20,6 +20,8 @@ service: path: "" display-name: List Entries docs: | + Use the AgentMail API to list entries within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:lists list --inbox-id --direction --type @@ -36,6 +38,8 @@ service: path: /{entry} display-name: Get List Entry docs: | + Use the AgentMail API to get a list entry within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail inboxes:lists get --inbox-id --direction --type --entry @@ -53,6 +57,8 @@ service: path: "" display-name: Create List Entry docs: | + Use the AgentMail API to create a list entry within a specific inbox. Review authentication, parameters, responses, and errors. Review the endpoint schema. + **CLI:** ```bash agentmail inboxes:lists create --inbox-id --direction --type --entry user@example.com @@ -67,6 +73,8 @@ service: path: /{entry} display-name: Delete List Entry docs: | + Use the AgentMail API to delete a list entry within a specific inbox. Review authentication, parameters, responses, and errors. Review the endpoint schema. + **CLI:** ```bash agentmail inboxes:lists delete --inbox-id --direction --type --entry diff --git a/fern/definition/inboxes/messages.yml b/fern/definition/inboxes/messages.yml index 294344b3..2c6fff08 100644 --- a/fern/definition/inboxes/messages.yml +++ b/fern/definition/inboxes/messages.yml @@ -19,6 +19,8 @@ service: path: "" display-name: List Messages docs: | + Use the AgentMail API to list messages within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + Lists messages in the inbox, most recent first. Pass `from`, `to`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked full-text @@ -60,6 +62,8 @@ service: path: /search display-name: Search Messages docs: | + Use the AgentMail API to search messages within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + Full-text search across messages in the inbox, ranked by relevance. The query is matched against the sender, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and @@ -82,6 +86,8 @@ service: path: /{message_id} display-name: Get Message docs: | + Use the AgentMail API to get a message within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:messages get --inbox-id --message-id @@ -97,6 +103,8 @@ service: path: /batch-get display-name: Batch Get Messages docs: | + Use the AgentMail API to retrieve multiple messages within a specific inbox. Review authentication, parameters, response fields, errors, and usage details. + Fetch metadata for up to 500 messages in one request. Missing or restricted IDs are silently omitted; compare `count` against `limit` to detect misses. @@ -115,6 +123,8 @@ service: path: /batch-update display-name: Batch Update Messages docs: | + Use the AgentMail API to update multiple messages within a specific inbox. Review authentication, parameters, response fields, errors, and usage details. + Apply one label change to up to 50 messages in a single request. The same add_labels and remove_labels apply to every message id, and at least one of them must be provided. The update is atomic: either all @@ -136,6 +146,8 @@ service: path: /{message_id}/attachments/{attachment_id} display-name: Get Attachment docs: | + Use the AgentMail API to get an attachment from a message within a specific inbox. Review authentication, parameters, responses, errors, and usage details. + **CLI:** ```bash agentmail inboxes:messages get-attachment --inbox-id --message-id --attachment-id @@ -152,6 +164,8 @@ service: path: /{message_id}/raw display-name: Get Raw Message docs: | + Use the AgentMail API to get a raw message within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail inboxes:messages get-raw --inbox-id --message-id @@ -167,6 +181,8 @@ service: path: /{message_id} display-name: Update Message docs: | + Use the AgentMail API to update a message within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail inboxes:messages update --inbox-id --message-id --add-label read --remove-label unread @@ -184,6 +200,8 @@ service: path: /{message_id} display-name: Delete Message docs: | + Use the AgentMail API to delete a message within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + Permanently deletes a message. **CLI:** @@ -201,6 +219,8 @@ service: display-name: Send Message idempotent: true docs: | + Use the AgentMail API to send a message within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:messages send --inbox-id --to recipient@example.com --subject "Hello" --text "Body" @@ -219,6 +239,8 @@ service: display-name: Reply To Message idempotent: true docs: | + Use the AgentMail API to reply to a message within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail inboxes:messages reply --inbox-id --message-id --text "Reply text" @@ -239,6 +261,8 @@ service: display-name: Reply All Message idempotent: true docs: | + Use the AgentMail API to reply to every recipient of a message within a specific inbox. Review authentication, parameters, responses, errors, and usage details. + **CLI:** ```bash agentmail inboxes:messages reply-all --inbox-id --message-id --text "Reply text" @@ -259,6 +283,8 @@ service: display-name: Forward Message idempotent: true docs: | + Use the AgentMail API to forward a message within a specific inbox. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail inboxes:messages forward --inbox-id --message-id --to recipient@example.com diff --git a/fern/definition/inboxes/metrics.yml b/fern/definition/inboxes/metrics.yml index 3d10d572..beecb5dd 100644 --- a/fern/definition/inboxes/metrics.yml +++ b/fern/definition/inboxes/metrics.yml @@ -18,6 +18,8 @@ service: path: /events display-name: Query Events docs: | + Use the AgentMail API to query event metrics within a specific inbox. Review authentication, parameters, responses, and errors. Review the endpoint schema. + Counts of email events (sent, delivered, bounced, etc.) over time for the inbox. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. Omit `period` for @@ -46,6 +48,8 @@ service: path: /usage display-name: Query Usage docs: | + Use the AgentMail API to query usage metrics within a specific inbox. Review authentication, parameters, responses, and errors. Review the endpoint schema. + Cumulative usage series for the inbox. Each point is the running total of the usage type at that timestamp, not the change within the bucket. Inbox-scoped queries carry `storage_bytes`, `message_count`, and diff --git a/fern/definition/inboxes/threads.yml b/fern/definition/inboxes/threads.yml index 352f76b1..4b5832c7 100644 --- a/fern/definition/inboxes/threads.yml +++ b/fern/definition/inboxes/threads.yml @@ -19,6 +19,8 @@ service: path: "" display-name: List Threads docs: | + Use the AgentMail API to list threads within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + Lists threads in the inbox, most recent first. Pass `senders`, `recipients`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked @@ -59,6 +61,8 @@ service: path: /search display-name: Search Threads docs: | + Use the AgentMail API to search threads within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + Full-text search across threads in the inbox, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and @@ -81,6 +85,8 @@ service: path: /{thread_id} display-name: Get Thread docs: | + Use the AgentMail API to get a thread within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail inboxes:threads get --inbox-id --thread-id @@ -96,6 +102,8 @@ service: path: /{thread_id}/attachments/{attachment_id} display-name: Get Attachment docs: | + Use the AgentMail API to get an attachment from a thread within a specific inbox. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail inboxes:threads get-attachment --inbox-id --thread-id --attachment-id @@ -111,7 +119,10 @@ service: method: PATCH path: /{thread_id} display-name: Update Thread - docs: Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages. + docs: | + Use the AgentMail API to update a thread within a specific inbox. Review authentication, request parameters, response fields, error behavior, and usage details. + + Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages. path-parameters: thread_id: threads.ThreadId request: threads.UpdateThreadRequest @@ -126,7 +137,7 @@ service: path: /{thread_id} display-name: Delete Thread docs: | - Permanently deletes a thread and all of its messages. + Permanently delete a thread and every message it contains from a specific AgentMail inbox, including the required authentication, parameters, and errors. **CLI:** ```bash diff --git a/fern/definition/inboxes/webhooks.yml b/fern/definition/inboxes/webhooks.yml index 05e519e2..a0527b5d 100644 --- a/fern/definition/inboxes/webhooks.yml +++ b/fern/definition/inboxes/webhooks.yml @@ -18,6 +18,8 @@ service: path: "" display-name: List Webhooks docs: | + List webhooks scoped to a specific AgentMail inbox, including pagination controls, delivery configuration, event subscriptions, and webhook identifiers. + **CLI:** ```bash agentmail inboxes:webhooks list --inbox-id @@ -35,6 +37,8 @@ service: path: /{webhook_id} display-name: Get Webhook docs: | + Get the delivery URL, event subscriptions, scope, timestamps, and configuration for a webhook attached to a specific AgentMail inbox by its unique identifier. + **CLI:** ```bash agentmail inboxes:webhooks get --inbox-id --webhook-id @@ -50,8 +54,7 @@ service: path: /{webhook_id}/headers display-name: Get Webhook Headers docs: | - List the names of custom HTTP headers included with deliveries to this inbox-scoped webhook. - Header values are write-only and are never returned. + List the names of custom HTTP headers sent with deliveries to an inbox-scoped webhook while ensuring all sensitive header values always remain write-only. path-parameters: webhook_id: webhooks.WebhookId response: webhooks.WebhookHeaderNamesResponse @@ -63,7 +66,7 @@ service: path: "" display-name: Create Webhook docs: | - Create a webhook scoped to this inbox. + Create a webhook scoped to one AgentMail inbox, configure its delivery URL and event subscriptions, and receive the resulting webhook configuration details. **CLI:** ```bash @@ -79,6 +82,8 @@ service: path: /{webhook_id} display-name: Update Webhook docs: | + Update an inbox-scoped webhook URL or event subscriptions while preserving its fixed inbox scope and returning the current webhook configuration details. + **CLI:** ```bash agentmail inboxes:webhooks update --inbox-id --webhook-id --event-type message.received @@ -96,8 +101,7 @@ service: path: /{webhook_id}/headers display-name: Update Webhook Headers docs: | - Atomically set, replace, or remove custom HTTP headers included with deliveries to this - inbox-scoped webhook. Header values remain write-only. + Set, replace, or remove custom HTTP headers atomically for an inbox-scoped webhook while ensuring sensitive header values remain write-only during updates. path-parameters: webhook_id: webhooks.WebhookId request: webhooks.UpdateWebhookHeadersRequest @@ -112,6 +116,8 @@ service: path: /{webhook_id} display-name: Delete Webhook docs: | + Permanently delete a webhook scoped to one AgentMail inbox by its identifier and review the required authentication, path parameters, and possible errors. + **CLI:** ```bash agentmail inboxes:webhooks delete --inbox-id --webhook-id diff --git a/fern/definition/lists.yml b/fern/definition/lists.yml index f8d957e4..d1f3bd8d 100644 --- a/fern/definition/lists.yml +++ b/fern/definition/lists.yml @@ -96,6 +96,8 @@ service: path: "" display-name: List Entries docs: | + Use the AgentMail API to list entries for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail lists list --direction --type @@ -112,6 +114,8 @@ service: path: /{entry} display-name: Get List Entry docs: | + Use the AgentMail API to get a list entry for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail lists get --direction --type --entry @@ -129,6 +133,8 @@ service: path: "" display-name: Create List Entry docs: | + Use the AgentMail API to create a list entry for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail lists create --direction --type --entry user@example.com @@ -143,6 +149,8 @@ service: path: /{entry} display-name: Delete List Entry docs: | + Use the AgentMail API to delete a list entry for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail lists delete --direction --type --entry diff --git a/fern/definition/metrics.yml b/fern/definition/metrics.yml index bae72ff9..1269662b 100644 --- a/fern/definition/metrics.yml +++ b/fern/definition/metrics.yml @@ -115,6 +115,8 @@ service: path: /events display-name: Query Events docs: | + Use the AgentMail API to query event metrics for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + Counts of email events (sent, delivered, bounced, etc.) over time for the organization. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. Omit `period` @@ -143,6 +145,8 @@ service: path: /usage display-name: Query Usage docs: | + Use the AgentMail API to query usage metrics for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + Cumulative usage series for the organization. Each point is the running total of the usage type at that timestamp, not the change within the bucket. Defaults to the last 24 hours; `start` must be within the last diff --git a/fern/definition/organizations.yml b/fern/definition/organizations.yml index 562cbda6..5dce0eca 100644 --- a/fern/definition/organizations.yml +++ b/fern/definition/organizations.yml @@ -53,6 +53,8 @@ service: path: "" display-name: Get Organization docs: | + Use the AgentMail API to retrieve details about the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + Returns the organization for the authenticated API key (usage limits, counts, and billing metadata). **CLI:** diff --git a/fern/definition/pods/__package__.yml b/fern/definition/pods/__package__.yml index 9f796edd..bd506b5d 100644 --- a/fern/definition/pods/__package__.yml +++ b/fern/definition/pods/__package__.yml @@ -63,6 +63,8 @@ service: path: "" display-name: List Pods docs: | + Use the AgentMail API to list pods for the authenticated organization. Review authentication, parameters, responses, and errors. Review the endpoint schema. + **CLI:** ```bash agentmail pods list @@ -80,6 +82,8 @@ service: path: /{pod_id} display-name: Get Pod docs: | + Use the AgentMail API to get a pod for the authenticated organization. Review authentication, parameters, responses, and errors. Review the endpoint schema. + **CLI:** ```bash agentmail pods get --pod-id @@ -95,6 +99,8 @@ service: path: "" display-name: Create Pod docs: | + Use the AgentMail API to create a pod for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail pods create --client-id my-pod @@ -109,6 +115,8 @@ service: path: /{pod_id} display-name: Delete Pod docs: | + Use the AgentMail API to delete a pod for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail pods delete --pod-id diff --git a/fern/definition/pods/api-keys.yml b/fern/definition/pods/api-keys.yml index 5307c713..dde1c8bd 100644 --- a/fern/definition/pods/api-keys.yml +++ b/fern/definition/pods/api-keys.yml @@ -18,6 +18,8 @@ service: path: "" display-name: List API Keys docs: | + Use the AgentMail API to list API keys within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:api-keys list --pod-id @@ -36,6 +38,8 @@ service: path: "" display-name: Create API Key docs: | + Use the AgentMail API to create an API key within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:api-keys create --pod-id --name "My Key" @@ -51,6 +55,8 @@ service: path: /{api_key_id} display-name: Delete API Key docs: | + Use the AgentMail API to delete an API key within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:api-keys delete --pod-id --api-key-id diff --git a/fern/definition/pods/domains.yml b/fern/definition/pods/domains.yml index 4303d779..0d9e913f 100644 --- a/fern/definition/pods/domains.yml +++ b/fern/definition/pods/domains.yml @@ -18,6 +18,8 @@ service: path: "" display-name: List Domains docs: | + Use the AgentMail API to list domains within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:domains list --pod-id @@ -37,6 +39,8 @@ service: path: /{domain_id} display-name: Get Domain docs: | + Use the AgentMail API to get a domain within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:domains get --pod-id --domain-id @@ -52,6 +56,8 @@ service: path: /{domain_id}/zone-file display-name: Get Zone File docs: | + Use the AgentMail API to get a zone file within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:domains get-zone-file --pod-id --domain-id @@ -67,6 +73,8 @@ service: path: "" display-name: Create Domain docs: | + Use the AgentMail API to create a domain within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:domains create --pod-id --domain example.com @@ -81,6 +89,8 @@ service: path: /{domain_id} display-name: Update Domain docs: | + Use the AgentMail API to update a domain within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:domains update --pod-id --domain-id @@ -97,6 +107,8 @@ service: path: /{domain_id} display-name: Delete Domain docs: | + Use the AgentMail API to delete a domain within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:domains delete --pod-id --domain-id @@ -111,6 +123,8 @@ service: path: /{domain_id}/verify display-name: Verify Domain docs: | + Use the AgentMail API to verify a domain within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:domains verify --pod-id --domain-id diff --git a/fern/definition/pods/drafts.yml b/fern/definition/pods/drafts.yml index 9ec7feb0..ccb825e8 100644 --- a/fern/definition/pods/drafts.yml +++ b/fern/definition/pods/drafts.yml @@ -19,6 +19,8 @@ service: path: "" display-name: List Drafts docs: | + Use the AgentMail API to list drafts within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:drafts list --pod-id @@ -41,6 +43,8 @@ service: path: /{draft_id} display-name: Get Draft docs: | + Use the AgentMail API to get a draft within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:drafts get --pod-id --draft-id @@ -56,6 +60,8 @@ service: path: /{draft_id}/attachments/{attachment_id} display-name: Get Attachment docs: | + Use the AgentMail API to get an attachment from a draft within a specific Pod. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail pods:drafts get-attachment --pod-id --draft-id --attachment-id diff --git a/fern/definition/pods/inboxes.yml b/fern/definition/pods/inboxes.yml index ddc02c23..f34aafde 100644 --- a/fern/definition/pods/inboxes.yml +++ b/fern/definition/pods/inboxes.yml @@ -18,6 +18,8 @@ service: path: "" display-name: List Inboxes docs: | + Use the AgentMail API to list inboxes within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:inboxes list --pod-id @@ -37,6 +39,8 @@ service: path: /{inbox_id} display-name: Get Inbox docs: | + Use the AgentMail API to get an inbox within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:inboxes get --pod-id --inbox-id @@ -52,6 +56,8 @@ service: path: "" display-name: Create Inbox docs: | + Use the AgentMail API to create an inbox within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:inboxes create --pod-id --username myagent --domain example.com @@ -67,6 +73,8 @@ service: path: /{inbox_id} display-name: Update Inbox docs: | + Use the AgentMail API to update an inbox within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:inboxes update --pod-id --inbox-id @@ -83,6 +91,8 @@ service: path: /{inbox_id} display-name: Delete Inbox docs: | + Use the AgentMail API to delete an inbox within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:inboxes delete --pod-id --inbox-id diff --git a/fern/definition/pods/lists.yml b/fern/definition/pods/lists.yml index ba364ee2..357251c5 100644 --- a/fern/definition/pods/lists.yml +++ b/fern/definition/pods/lists.yml @@ -20,6 +20,8 @@ service: path: "" display-name: List Entries docs: | + Use the AgentMail API to list entries within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:lists list --pod-id --direction --type @@ -36,6 +38,8 @@ service: path: /{entry} display-name: Get List Entry docs: | + Use the AgentMail API to get a list entry within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:lists get --pod-id --direction --type --entry @@ -53,6 +57,8 @@ service: path: "" display-name: Create List Entry docs: | + Use the AgentMail API to create a list entry within a specific Pod. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail pods:lists create --pod-id --direction --type --entry user@example.com @@ -67,6 +73,8 @@ service: path: /{entry} display-name: Delete List Entry docs: | + Use the AgentMail API to delete a list entry within a specific Pod. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + **CLI:** ```bash agentmail pods:lists delete --pod-id --direction --type --entry diff --git a/fern/definition/pods/metrics.yml b/fern/definition/pods/metrics.yml index 5fe79bfb..19de0d68 100644 --- a/fern/definition/pods/metrics.yml +++ b/fern/definition/pods/metrics.yml @@ -18,6 +18,8 @@ service: path: /events display-name: Query Events docs: | + Use the AgentMail API to query event metrics within a specific Pod. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + Counts of email events (sent, delivered, bounced, etc.) over time for the pod. Defaults to the last 24 hours; `start` must be within the last 90 days, and a future `end` is clamped to now. Omit `period` for @@ -46,6 +48,8 @@ service: path: /usage display-name: Query Usage docs: | + Use the AgentMail API to query usage metrics within a specific Pod. Review authentication, parameters, responses, and errors. See the complete endpoint schema. + Cumulative usage series for the pod. Each point is the running total of the usage type at that timestamp, not the change within the bucket. Pod-scoped queries carry every usage type except `pod_count`; requested diff --git a/fern/definition/pods/threads.yml b/fern/definition/pods/threads.yml index 1f3654d3..e6146d53 100644 --- a/fern/definition/pods/threads.yml +++ b/fern/definition/pods/threads.yml @@ -19,6 +19,8 @@ service: path: "" display-name: List Threads docs: | + Use the AgentMail API to list threads within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + Lists threads in the pod, most recent first. Pass `senders`, `recipients`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked @@ -59,6 +61,8 @@ service: path: /search display-name: Search Threads docs: | + Use the AgentMail API to search threads within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + Full-text search across threads in the pod, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, trash, blocked, and @@ -81,6 +85,8 @@ service: path: /{thread_id} display-name: Get Thread docs: | + Use the AgentMail API to get a thread within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + **CLI:** ```bash agentmail pods:threads get --pod-id --thread-id @@ -96,6 +102,8 @@ service: path: /{thread_id}/attachments/{attachment_id} display-name: Get Attachment docs: | + Use the AgentMail API to get an attachment from a thread within a specific Pod. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail pods:threads get-attachment --pod-id --thread-id --attachment-id @@ -111,7 +119,10 @@ service: method: PATCH path: /{thread_id} display-name: Update Thread - docs: Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages. + docs: | + Use the AgentMail API to update a thread within a specific Pod. Review authentication, request parameters, response fields, error behavior, and usage details. + + Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages. path-parameters: thread_id: threads.ThreadId request: threads.UpdateThreadRequest @@ -126,7 +137,7 @@ service: path: /{thread_id} display-name: Delete Thread docs: | - Permanently deletes a thread and all of its messages. + Permanently delete a thread and every message it contains from a specific AgentMail Pod, including the required authentication, parameters, and errors. **CLI:** ```bash diff --git a/fern/definition/pods/webhooks.yml b/fern/definition/pods/webhooks.yml index dab2af8f..012ec2a8 100644 --- a/fern/definition/pods/webhooks.yml +++ b/fern/definition/pods/webhooks.yml @@ -18,6 +18,8 @@ service: path: "" display-name: List Webhooks docs: | + List webhooks scoped to a specific AgentMail Pod, including pagination controls, delivery configuration, event subscriptions, and webhook identifiers. + **CLI:** ```bash agentmail pods:webhooks list --pod-id @@ -35,6 +37,8 @@ service: path: /{webhook_id} display-name: Get Webhook docs: | + Get the delivery URL, event subscriptions, inbox filters, timestamps, and configuration for a webhook attached to a specific AgentMail Pod by identifier. + **CLI:** ```bash agentmail pods:webhooks get --pod-id --webhook-id @@ -50,8 +54,7 @@ service: path: /{webhook_id}/headers display-name: Get Webhook Headers docs: | - List the names of custom HTTP headers included with deliveries to this pod-scoped webhook. - Header values are write-only and are never returned. + List the names of custom HTTP headers sent with deliveries to a pod-scoped webhook while keeping every sensitive header value strictly write-only by design. path-parameters: webhook_id: webhooks.WebhookId response: webhooks.WebhookHeaderNamesResponse @@ -63,7 +66,7 @@ service: path: "" display-name: Create Webhook docs: | - Create a webhook scoped to this pod. + Create a webhook scoped to one AgentMail Pod, configure its delivery URL, event subscriptions, and inbox filters, and return the resulting configuration. **CLI:** ```bash @@ -79,6 +82,8 @@ service: path: /{webhook_id} display-name: Update Webhook docs: | + Update a pod-scoped webhook URL, event subscriptions, or inbox filters while preserving its fixed Pod scope and returning the current configuration details. + **CLI:** ```bash agentmail pods:webhooks update --pod-id --webhook-id --add-inbox-id @@ -96,8 +101,7 @@ service: path: /{webhook_id}/headers display-name: Update Webhook Headers docs: | - Atomically set, replace, or remove custom HTTP headers included with deliveries to this - pod-scoped webhook. Header values remain write-only. + Set, replace, or remove custom HTTP headers atomically for a pod-scoped webhook while ensuring every sensitive header value remains write-only during updates. path-parameters: webhook_id: webhooks.WebhookId request: webhooks.UpdateWebhookHeadersRequest @@ -112,6 +116,8 @@ service: path: /{webhook_id} display-name: Delete Webhook docs: | + Permanently delete a webhook scoped to one AgentMail Pod by its identifier and review the required authentication, path parameters, and possible errors. + **CLI:** ```bash agentmail pods:webhooks delete --pod-id --webhook-id diff --git a/fern/definition/threads.yml b/fern/definition/threads.yml index 1efc8c79..f3d769d3 100644 --- a/fern/definition/threads.yml +++ b/fern/definition/threads.yml @@ -177,6 +177,8 @@ service: path: "" display-name: List Threads docs: | + Use the AgentMail API to list threads for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + Lists threads, most recent first. Pass `senders`, `recipients`, or `subject` to filter by substring. Filtered requests are served by search, which caps `limit` at 100. For relevance-ranked full-text @@ -218,6 +220,8 @@ service: path: /search display-name: Search Threads docs: | + Use the AgentMail API to search threads for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + Full-text search across threads in the organization, ranked by relevance. The query is matched against senders, recipients, and subject (substring) and the message body (tokenized full text). Spam, @@ -241,6 +245,8 @@ service: path: /{thread_id} display-name: Get Thread docs: | + Use the AgentMail API to get a thread for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail threads get --thread-id @@ -256,6 +262,8 @@ service: path: /{thread_id}/attachments/{attachment_id} display-name: Get Attachment docs: | + Use the AgentMail API to get an attachment from a thread for the authenticated organization. Review authentication, parameters, responses, and error behavior. + **CLI:** ```bash agentmail threads get-attachment --thread-id --attachment-id @@ -271,7 +279,10 @@ service: method: PATCH path: /{thread_id} display-name: Update Thread - docs: Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages. + docs: | + Use the AgentMail API to update a thread for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + + Updates thread labels. Cannot add or remove system labels (sent, received, bounced, etc.). Rejects requests with a `422` for threads with 100 or more messages. path-parameters: thread_id: ThreadId request: UpdateThreadRequest @@ -286,7 +297,7 @@ service: path: /{thread_id} display-name: Delete Thread docs: | - Permanently deletes a thread and all of its messages. + Permanently delete a thread and every message it contains for the authenticated AgentMail organization, including required parameters and possible errors. **CLI:** ```bash diff --git a/fern/definition/webhooks/__package__.yml b/fern/definition/webhooks/__package__.yml index 19eb3343..1d410f42 100644 --- a/fern/definition/webhooks/__package__.yml +++ b/fern/definition/webhooks/__package__.yml @@ -158,6 +158,8 @@ service: path: "" display-name: List Webhooks docs: | + Use the AgentMail API to list webhooks for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail webhooks list @@ -175,6 +177,8 @@ service: path: /{webhook_id} display-name: Get Webhook docs: | + Use the AgentMail API to get a webhook for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail webhooks get --webhook-id @@ -190,8 +194,7 @@ service: path: /{webhook_id}/headers display-name: Get Webhook Headers docs: | - List the names of custom HTTP headers included with deliveries to this webhook. Header values are - write-only and are never returned. + List the names of custom HTTP headers sent with deliveries to an organization-level webhook while ensuring every sensitive header value remains write-only. path-parameters: webhook_id: WebhookId response: WebhookHeaderNamesResponse @@ -203,6 +206,8 @@ service: path: "" display-name: Create Webhook docs: | + Use the AgentMail API to create a webhook for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail webhooks create --url https://example.com/webhook --event-type message.received @@ -217,6 +222,8 @@ service: path: /{webhook_id} display-name: Update Webhook docs: | + Use the AgentMail API to update a webhook for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + Update inbox or pod subscriptions, or replace the webhook's `event_types` in full when you pass a non-empty `event_types` array (see request field docs). Inbox and pod changes use add/remove lists. @@ -237,8 +244,7 @@ service: path: /{webhook_id}/headers display-name: Update Webhook Headers docs: | - Atomically set, replace, or remove custom HTTP headers included with deliveries to this webhook. - Header values remain write-only. + Set, replace, or remove custom HTTP headers atomically for an organization-level webhook while ensuring all sensitive header values remain write-only. path-parameters: webhook_id: WebhookId request: UpdateWebhookHeadersRequest @@ -253,6 +259,8 @@ service: path: /{webhook_id} display-name: Delete Webhook docs: | + Use the AgentMail API to delete a webhook for the authenticated organization. Review authentication, parameters, response fields, errors, and usage details. + **CLI:** ```bash agentmail webhooks delete --webhook-id diff --git a/fern/definition/webhooks/events.yml b/fern/definition/webhooks/events.yml index 569466c5..d0d537d4 100644 --- a/fern/definition/webhooks/events.yml +++ b/fern/definition/webhooks/events.yml @@ -19,6 +19,7 @@ types: webhooks: messageReceived: display-name: Message Received + docs: Sent when AgentMail receives an email message. Inspect the message and thread, identify the inbox, and trigger real-time processing in your agent workflow. method: POST headers: svix-id: SvixId @@ -28,6 +29,7 @@ webhooks: messageSent: display-name: Message Sent + docs: Sent after AgentMail accepts an outbound email. Inspect message identifiers, recipients, inbox context, and timestamps to track your agent send workflow. method: POST headers: svix-id: SvixId @@ -37,6 +39,7 @@ webhooks: messageDelivered: display-name: Message Delivered + docs: Sent when a recipient mail server accepts an AgentMail message. Inspect delivery details, recipients, inbox context, and timestamps for reliable tracking. method: POST headers: svix-id: SvixId @@ -46,6 +49,7 @@ webhooks: messageBounced: display-name: Message Bounced + docs: Sent when an AgentMail message bounces. Inspect bounce type, subtype, affected recipients, message identifiers, and timestamps to protect deliverability. method: POST headers: svix-id: SvixId @@ -55,6 +59,7 @@ webhooks: messageComplained: display-name: Message Complained + docs: Sent when a recipient reports an AgentMail message as spam. Inspect complaint details, affected recipients, message identifiers, and timestamps for action. method: POST headers: svix-id: SvixId @@ -64,6 +69,7 @@ webhooks: messageRejected: display-name: Message Rejected + docs: Sent when AgentMail rejects an outbound message before delivery. Inspect the rejection reason, message and thread identifiers, inbox context, and timestamp. method: POST headers: svix-id: SvixId @@ -73,6 +79,7 @@ webhooks: domainVerified: display-name: Domain Verified + docs: Sent when AgentMail verifies a custom domain. Inspect the domain record and event identifier, then continue setup or enable sending from the verified domain. method: POST headers: svix-id: SvixId diff --git a/fern/definition/websockets.yml b/fern/definition/websockets.yml index 69efe0a0..5e555621 100644 --- a/fern/definition/websockets.yml +++ b/fern/definition/websockets.yml @@ -29,6 +29,7 @@ channel: url: Websockets path: /v0 display-name: Connect + docs: Connect to AgentMail WebSockets, authenticate a client, subscribe to inbox or Pod events, and receive typed email lifecycle messages for agents in real time. auth: true query-parameters: api_key: diff --git a/fern/docs.yml b/fern/docs.yml index 477add69..bffbc321 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -22,7 +22,7 @@ title: AgentMail | Documentation favicon: assets/agentmail-favicon.ico metadata: - og:description: "AgentMail is an email API built for AI agents. Create inboxes, send and receive messages, manage threads, and handle webhooks programmatically." + og:description: "AgentMail is the email API for AI agents. Create inboxes, exchange messages, manage threads and attachments, and automate reliable email workflows at scale." canonical-host: agentmail.to/docs agents: diff --git a/fern/pages/apiwelcome.mdx b/fern/pages/apiwelcome.mdx index 73471edf..18aea6c5 100644 --- a/fern/pages/apiwelcome.mdx +++ b/fern/pages/apiwelcome.mdx @@ -2,7 +2,7 @@ title: API Welcome subtitle: Getting Started with AgentMail slug: api-reference -description: Quick overview of the AgentMail SDK +description: "Explore the AgentMail API and SDKs for creating agent inboxes, sending and receiving email, managing threads and drafts, and building automated workflows." --- ## Introduction diff --git a/fern/pages/best-practices/email-deliverability.mdx b/fern/pages/best-practices/email-deliverability.mdx index b5674dcb..b81439c1 100644 --- a/fern/pages/best-practices/email-deliverability.mdx +++ b/fern/pages/best-practices/email-deliverability.mdx @@ -2,7 +2,7 @@ title: Email Deliverability subtitle: Best practices for landing your emails in the inbox, not the spam folder. slug: email-deliverability -description: Learn the strategies and best practices for maximizing your email deliverability with AgentMail. +description: "Improve AgentMail deliverability with domain authentication, warmup, sending patterns, content practices, bounce handling, and reputation monitoring at scale." --- ## What is Email Deliverability? diff --git a/fern/pages/best-practices/idempotency.mdx b/fern/pages/best-practices/idempotency.mdx index 3c87056b..1638a8f3 100644 --- a/fern/pages/best-practices/idempotency.mdx +++ b/fern/pages/best-practices/idempotency.mdx @@ -2,7 +2,7 @@ title: "Idempotent Requests" subtitle: "Learn how to use idempotency keys to build safe and reliable API integrations." slug: idempotency -description: "A guide to preventing duplicate resources with client_id and preventing duplicate email sends with the Idempotency-Key header." +description: "Prevent duplicate AgentMail resources and email sends by using client IDs and Idempotency-Key headers to make retries safe across reliable API workflows." --- ## What is Idempotency? diff --git a/fern/pages/core-concepts/attachments.mdx b/fern/pages/core-concepts/attachments.mdx index b055fe58..70ed4144 100644 --- a/fern/pages/core-concepts/attachments.mdx +++ b/fern/pages/core-concepts/attachments.mdx @@ -2,7 +2,7 @@ title: Attachments subtitle: Sending and receiving files with your agents. slug: attachments -description: Learn how to send files as attachments, and download incoming attachments from both messages and threads. +description: "Learn how AI agents send Base64 encoded files with AgentMail and retrieve attachments from incoming messages or complete conversation threads programmatically." --- ## What are `Attachments`? @@ -230,4 +230,3 @@ Copy one of the blocks below into Cursor or Claude for complete Attachments usag const data = await client.inboxes.messages.get_attachment("inbox@am.to", "", "att_456"); ``` - diff --git a/fern/pages/core-concepts/drafts.mdx b/fern/pages/core-concepts/drafts.mdx index 5b836036..209472aa 100644 --- a/fern/pages/core-concepts/drafts.mdx +++ b/fern/pages/core-concepts/drafts.mdx @@ -2,7 +2,7 @@ title: Drafts subtitle: Preparing and scheduling Messages for your agents. slug: drafts -description: Learn how to create, manage, and send Drafts to enable advanced agent workflows like human-in-the-loop review and scheduled sending. +description: "Learn how agents can create, review, update, and send AgentMail drafts for approval flows, scheduled delivery, and human-in-the-loop email workflows at scale." --- ## What is a Draft? diff --git a/fern/pages/core-concepts/inboxes.mdx b/fern/pages/core-concepts/inboxes.mdx index 6c5ce624..b0ca18e9 100644 --- a/fern/pages/core-concepts/inboxes.mdx +++ b/fern/pages/core-concepts/inboxes.mdx @@ -2,7 +2,7 @@ title: Inboxes subtitle: The foundation of your agent's identity and communication. slug: inboxes -description: Learn how AgentMail Inboxes act as scalable, API-first email accounts for your agents. +description: "Learn how AgentMail inboxes give AI agents scalable email identities, including creation, metadata, custom domains, scoped API keys, and management at scale." --- ## What is an Inbox? diff --git a/fern/pages/core-concepts/labels.mdx b/fern/pages/core-concepts/labels.mdx index 317087b1..211b83f2 100644 --- a/fern/pages/core-concepts/labels.mdx +++ b/fern/pages/core-concepts/labels.mdx @@ -2,7 +2,7 @@ title: Labels subtitle: Organizing and categorizing your agent's conversations at scale. slug: labels -description: Learn how to use Labels to manage state, track campaigns, and filter messages for powerful agentic workflows. +description: "Use AgentMail labels to classify messages and threads, track workflow state, segment conversations, and filter email for reliable agent automation at scale." --- ## What are `Labels`? diff --git a/fern/pages/core-concepts/lists.mdx b/fern/pages/core-concepts/lists.mdx index 35d1f112..3ab67aa8 100644 --- a/fern/pages/core-concepts/lists.mdx +++ b/fern/pages/core-concepts/lists.mdx @@ -2,7 +2,7 @@ title: Lists subtitle: Filter emails by allowing or blocking specific addresses and domains. slug: lists -description: Learn how to use Lists to control which email addresses and domains your agents can send to or receive from. +description: "Use AgentMail allowlists and blocklists to control which addresses and domains an agent can send to, receive from, or reply to through the API safely at scale." --- ## What are Lists? diff --git a/fern/pages/core-concepts/messages.mdx b/fern/pages/core-concepts/messages.mdx index 90659064..9ca24435 100644 --- a/fern/pages/core-concepts/messages.mdx +++ b/fern/pages/core-concepts/messages.mdx @@ -2,7 +2,7 @@ title: Messages subtitle: The fundamental unit of communication for your agents. slug: messages -description: Learn how to send, receive, and manage emails as Message objects with the AgentMail API. +description: "Learn how to send, receive, search, reply to, forward, label, and delete AgentMail messages, including attachments and extracted reply content reliably." --- ## What is a Message? diff --git a/fern/pages/core-concepts/permissions.mdx b/fern/pages/core-concepts/permissions.mdx index 3c828a7d..d8e31e54 100644 --- a/fern/pages/core-concepts/permissions.mdx +++ b/fern/pages/core-concepts/permissions.mdx @@ -2,7 +2,7 @@ title: Permissions subtitle: Control what your API keys can access with granular permissions. slug: permissions -description: Learn how to configure fine-grained permissions on API keys to restrict access to specific resources and operations. +description: "Configure AgentMail API key permissions with a whitelist model that limits access by resource and operation across organization, Pod, or inbox scopes." --- ## What are Permissions? diff --git a/fern/pages/core-concepts/pods.mdx b/fern/pages/core-concepts/pods.mdx index 3b07228d..f5425d7d 100644 --- a/fern/pages/core-concepts/pods.mdx +++ b/fern/pages/core-concepts/pods.mdx @@ -1,6 +1,6 @@ --- title: Pods -description: Learn how to use pods for multi-tenant email management +description: "Learn how AgentMail Pods isolate inboxes, domains, threads, drafts, and API keys for secure multi-tenant applications and customer-specific agents at scale." --- ## What are Pods? diff --git a/fern/pages/core-concepts/threads.mdx b/fern/pages/core-concepts/threads.mdx index c04c683c..04036668 100644 --- a/fern/pages/core-concepts/threads.mdx +++ b/fern/pages/core-concepts/threads.mdx @@ -2,7 +2,7 @@ title: Threads subtitle: Organizing conversations across your Inboxes. slug: threads -description: Learn how AgentMail Threads group messages into conversations and how to query them across your entire organization. +description: "Learn how AgentMail groups related messages into threads so agents can preserve conversation context, search email history, and manage labels at scale." --- ## What is a Thread? diff --git a/fern/pages/examples/auto-reply-agent.mdx b/fern/pages/examples/auto-reply-agent.mdx index 0b16c5de..536ff462 100644 --- a/fern/pages/examples/auto-reply-agent.mdx +++ b/fern/pages/examples/auto-reply-agent.mdx @@ -1,6 +1,6 @@ --- title: "Auto-Reply Email Agent" -description: "Build a simple agent that automatically responds to incoming emails with personalized messages" +description: "Build an AgentMail auto-reply agent that receives webhook events, reads incoming email, generates a response, and replies in the original thread in real time." --- ## Overview diff --git a/fern/pages/examples/github-star-agent.mdx b/fern/pages/examples/github-star-agent.mdx index 7170a111..e722c690 100644 --- a/fern/pages/examples/github-star-agent.mdx +++ b/fern/pages/examples/github-star-agent.mdx @@ -2,7 +2,7 @@ title: "Example: Event-Driven Agent" subtitle: "Build a proactive, event-driven GitHub agent that uses Webhooks to handle replies in real time." slug: webhook-agent -description: "A step-by-step guide to building a sophisticated agent that performs proactive outreach and uses webhooks for inbound message processing." +description: "Build an event-driven agent that uses AgentMail to react to GitHub activity, send personalized emails, process replies, and continue threaded conversations." --- This tutorial walks you through building a sophisticated, dual-mode agent. It will: diff --git a/fern/pages/examples/live-emails.mdx b/fern/pages/examples/live-emails.mdx index 46ebe356..7ad151d0 100644 --- a/fern/pages/examples/live-emails.mdx +++ b/fern/pages/examples/live-emails.mdx @@ -1,3 +1,6 @@ +--- +description: "Explore production email agents built with AgentMail, including networking and recruiting workflows that process messages and manage follow-up automatically." +--- # Live Email Agents We have several deployed agents running in production that demonstrate the power of AgentMail. These agents showcase different use cases and capabilities of our platform. diff --git a/fern/pages/examples/sales-agent-websocket.mdx b/fern/pages/examples/sales-agent-websocket.mdx index 0416439d..50d69bdc 100644 --- a/fern/pages/examples/sales-agent-websocket.mdx +++ b/fern/pages/examples/sales-agent-websocket.mdx @@ -1,7 +1,7 @@ --- title: "Sales Agent with WebSocket" slug: sales-agent-websocket -description: "A step-by-step guide to building an AI-powered sales agent that uses WebSocket for real-time email processing without polling or webhooks." +description: "Build a real-time sales email agent with AgentMail WebSockets that receives leads, understands replies, updates context, and responds without polling." --- ## Overview diff --git a/fern/pages/examples/smart-labeling-agent.mdx b/fern/pages/examples/smart-labeling-agent.mdx index 6bdd45d3..a43e026b 100644 --- a/fern/pages/examples/smart-labeling-agent.mdx +++ b/fern/pages/examples/smart-labeling-agent.mdx @@ -1,6 +1,6 @@ --- title: "Smart Email Labeling Agent" -description: "Build an AI-powered agent that automatically classifies and labels incoming emails across multiple dimensions" +description: "Build an AI email labeling agent with AgentMail that classifies incoming messages across multiple dimensions and applies labels for routing and analytics." --- ## Overview diff --git a/fern/pages/get-started/introduction.mdx b/fern/pages/get-started/introduction.mdx index 73b5b4c9..6f7093a4 100644 --- a/fern/pages/get-started/introduction.mdx +++ b/fern/pages/get-started/introduction.mdx @@ -2,6 +2,7 @@ title: Introduction subtitle: Give AI agents email inboxes slug: introduction +description: "Learn how AgentMail gives AI agents programmable inboxes for sending, receiving, and managing email, threads, attachments, and real-time events at scale." --- ## What is AgentMail? diff --git a/fern/pages/get-started/quickstart.mdx b/fern/pages/get-started/quickstart.mdx index d6b89569..61180387 100644 --- a/fern/pages/get-started/quickstart.mdx +++ b/fern/pages/get-started/quickstart.mdx @@ -2,7 +2,7 @@ title: Quickstart subtitle: Create your first inbox with the AgentMail API slug: quickstart -description: Follow this guide to make your first AgentMail API request and create a new email inbox. +description: "Create your first AgentMail inbox, install the Python or TypeScript SDK, protect your API key, and send and receive email with a working example step by step." --- ## For Agents diff --git a/fern/pages/get-started/welcome.mdx b/fern/pages/get-started/welcome.mdx index 3ab8243d..1b137542 100644 --- a/fern/pages/get-started/welcome.mdx +++ b/fern/pages/get-started/welcome.mdx @@ -1,7 +1,7 @@ --- title: Welcome slug: welcome -description: Your starting point for building with the AgentMail API. +description: "Start building with AgentMail, the email API for AI agents. Learn how to create inboxes, exchange messages, and connect email to autonomous workflows." --- diff --git a/fern/pages/guides/agentid-public-key-authentication.mdx b/fern/pages/guides/agentid-public-key-authentication.mdx index 562058d0..d2924bc2 100644 --- a/fern/pages/guides/agentid-public-key-authentication.mdx +++ b/fern/pages/guides/agentid-public-key-authentication.mdx @@ -2,7 +2,7 @@ title: AgentID Public-Key Authentication subtitle: Register a scoped P-256 key and sign one AgentID approval without exposing the private key. slug: agentid-public-key-authentication -description: Generate and store a P-256 key, register its public JWK, and submit a strict signed AgentID approval. +description: "Register scoped P-256 public keys for AgentID sign-in, keep private keys in secure storage, and submit signed approval assertions without exposing secrets." --- AgentID public-key credentials let an agent prove possession of a P-256 private diff --git a/fern/pages/guides/domains/custom-domains.mdx b/fern/pages/guides/domains/custom-domains.mdx index 1771581a..03ab1056 100644 --- a/fern/pages/guides/domains/custom-domains.mdx +++ b/fern/pages/guides/domains/custom-domains.mdx @@ -2,7 +2,7 @@ title: Using Custom Domains subtitle: Strengthen your agent's identity and improve deliverability with your own domain. slug: custom-domains -description: A step-by-step guide to configuring your custom domain with AgentMail for enhanced branding and trust. +description: "Configure a custom sending domain in AgentMail, add the required DNS records, verify ownership, and improve the identity and deliverability of agent email." --- ## Why Use a Custom Domain? diff --git a/fern/pages/guides/domains/managing-domains.mdx b/fern/pages/guides/domains/managing-domains.mdx index bf2ab451..8a064d89 100644 --- a/fern/pages/guides/domains/managing-domains.mdx +++ b/fern/pages/guides/domains/managing-domains.mdx @@ -2,7 +2,7 @@ title: Managing Your Domains subtitle: Best practices for monitoring, scaling, and optimizing your domain strategy for agent fleets. slug: managing-domains -description: Learn how to manage your custom domains effectively using AgentMail's API for enhanced deliverability and reputation management. +description: "Manage AgentMail custom domains through the API, monitor verification and reputation, scale agent inboxes, and maintain reliable email deliverability." --- ## From Setup to Strategy diff --git a/fern/pages/guides/google-workspace.mdx b/fern/pages/guides/google-workspace.mdx index 64f23a9a..44fcc3b1 100644 --- a/fern/pages/guides/google-workspace.mdx +++ b/fern/pages/guides/google-workspace.mdx @@ -2,7 +2,7 @@ title: "Google Workspace" subtitle: "Route unrecognized addresses from Google Workspace to AgentMail" slug: google-workspace -description: "Configure your Google Workspace domain to route emails for unrecognized addresses to AgentMail." +description: "Route unrecognized Google Workspace addresses to AgentMail while keeping existing mailboxes intact, using split delivery, DNS records, and Gmail routing." --- ## Shared domains diff --git a/fern/pages/guides/imap-smtp.mdx b/fern/pages/guides/imap-smtp.mdx index b84f759a..9ed7a93f 100644 --- a/fern/pages/guides/imap-smtp.mdx +++ b/fern/pages/guides/imap-smtp.mdx @@ -2,7 +2,7 @@ title: "IMAP & SMTP" subtitle: "Connect to AgentMail with standard email protocols" slug: imap-smtp -description: "Configure IMAP and SMTP to access your AgentMail inboxes using email clients or programmatic access." +description: "Connect AgentMail inboxes to email clients and third-party tools through standard IMAP and SMTP, with credentials, ports, security, and setup examples." --- AgentMail supports standard IMAP and SMTP protocols, allowing you to connect using traditional email clients or integrate with existing systems that rely on these protocols. diff --git a/fern/pages/guides/multi-tenancy.mdx b/fern/pages/guides/multi-tenancy.mdx index 0dd24ea2..8cbeb570 100644 --- a/fern/pages/guides/multi-tenancy.mdx +++ b/fern/pages/guides/multi-tenancy.mdx @@ -2,7 +2,7 @@ title: "Guide: Multi-Tenancy" subtitle: "Pods, scoped keys, and event routing for your customers." slug: multi-tenancy -description: "How to use pods, scoped API keys, and webhook filtering to build multi-tenant email on AgentMail." +description: "Design multi-tenant email infrastructure with AgentMail using Pods, scoped API keys, isolated inboxes, custom domains, permissions, and resource boundaries." --- If you're building a platform where each of your customers needs their own email infrastructure, this is how you set it up. The basic idea: create a `Pod` per customer, give them a scoped API key, and route webhook events to the right place. diff --git a/fern/pages/guides/sending-receiving-email.mdx b/fern/pages/guides/sending-receiving-email.mdx index 66b28d42..56b8d485 100644 --- a/fern/pages/guides/sending-receiving-email.mdx +++ b/fern/pages/guides/sending-receiving-email.mdx @@ -2,7 +2,7 @@ title: "Guide: Sending & Receiving Email" subtitle: "Building your first conversational agent workflow." slug: sending-receiving-email -description: "A step-by-step guide to the practical workflow of sending initial emails and handling replies to have a full conversation." +description: "Build a conversational email agent with AgentMail by creating an inbox, sending a message, receiving events, preserving threads, and replying in context." --- This guide walks you through the complete, practical workflow of an agent having a conversation. While the `Core Concepts` pages detail the individual API calls, this guide shows you how to stitch them together to create a functional conversational loop. diff --git a/fern/pages/integrations/agent-onboarding.mdx b/fern/pages/integrations/agent-onboarding.mdx index 46c23692..bd1e2d77 100644 --- a/fern/pages/integrations/agent-onboarding.mdx +++ b/fern/pages/integrations/agent-onboarding.mdx @@ -2,8 +2,7 @@ title: Agent Onboarding subtitle: Everything you need to onboard your AI agent to AgentMail slug: agent-onboarding -description: >- - Resources for AI coding assistants, MCP servers, skills, and agent-friendly documentation. +description: "Onboard AI agents to AgentMail with programmatic signup, agent-friendly documentation, MCP, official skills, and resources for popular coding assistants." --- diff --git a/fern/pages/integrations/cli.mdx b/fern/pages/integrations/cli.mdx index 4a6e8f3d..160a5c1d 100644 --- a/fern/pages/integrations/cli.mdx +++ b/fern/pages/integrations/cli.mdx @@ -2,7 +2,7 @@ title: CLI subtitle: Manage AgentMail resources from the command line slug: integrations/cli -description: AgentMail's official command-line interface +description: "Install and use the AgentMail CLI to create inboxes, send and receive email, manage threads, configure resources, and automate workflows from a terminal." --- ## Getting started diff --git a/fern/pages/integrations/google-adk.mdx b/fern/pages/integrations/google-adk.mdx index 3f0f3099..609b74b2 100644 --- a/fern/pages/integrations/google-adk.mdx +++ b/fern/pages/integrations/google-adk.mdx @@ -2,7 +2,7 @@ title: Google ADK subtitle: Give your Google ADK agent its own email inbox slug: integrations/google-adk -description: AgentMail's Google Agent Development Kit (ADK) integration +description: "Connect AgentMail to Google Agent Development Kit through MCP so ADK agents can create inboxes, exchange email, manage threads, and handle attachments." --- ## Getting started diff --git a/fern/pages/integrations/integrate-livekit-agents.mdx b/fern/pages/integrations/integrate-livekit-agents.mdx index a8072428..8e69e497 100644 --- a/fern/pages/integrations/integrate-livekit-agents.mdx +++ b/fern/pages/integrations/integrate-livekit-agents.mdx @@ -2,7 +2,7 @@ title: "Integrate LiveKit Agents" subtitle: "Build a voice assistant with real time email capabilities." slug: integrate-livekit-agents -description: "A step-by-step guide to integrate with the LiveKit Agents SDK." +description: "Build a LiveKit voice assistant with AgentMail tools so it can send email during conversations, using a practical Python integration guide and example." --- ## Overview diff --git a/fern/pages/integrations/langchain.mdx b/fern/pages/integrations/langchain.mdx index 10db0b37..89a11618 100644 --- a/fern/pages/integrations/langchain.mdx +++ b/fern/pages/integrations/langchain.mdx @@ -2,7 +2,7 @@ title: LangChain subtitle: Give your LangChain agent its own email inbox slug: integrations/langchain -description: AgentMail's LangChain integration +description: "Use the LangChain AgentMail integration to give LangGraph agents real inboxes plus tools for sending, replying, drafting, labeling, and searching email." --- ## Getting started diff --git a/fern/pages/integrations/mcp.mdx b/fern/pages/integrations/mcp.mdx index 613d8cdf..5c36eea1 100644 --- a/fern/pages/integrations/mcp.mdx +++ b/fern/pages/integrations/mcp.mdx @@ -2,7 +2,7 @@ title: MCP subtitle: Connect AgentMail to Claude, Cursor, and other MCP clients slug: integrations/mcp -description: Connect AgentMail to Claude, Cursor, and other MCP clients +description: "Connect Claude, Cursor, and other MCP clients to AgentMail with OAuth or an API key so agents can manage inboxes, messages, threads, and attachments securely." --- ## Overview diff --git a/fern/pages/integrations/mpp.mdx b/fern/pages/integrations/mpp.mdx index 26913cdd..71f05eb6 100644 --- a/fern/pages/integrations/mpp.mdx +++ b/fern/pages/integrations/mpp.mdx @@ -2,7 +2,7 @@ title: MPP subtitle: Pay-per-use AgentMail with Stripe's Machine Payments Protocol slug: integrations/mpp -description: AgentMail's MPP integration for machine-to-machine payments via Stripe +description: "Use AgentMail with Stripe's Machine Payments Protocol so agents can pay per request, access MPP endpoints, and use email APIs without subscriptions at runtime." --- ## Getting started diff --git a/fern/pages/integrations/openclaw.mdx b/fern/pages/integrations/openclaw.mdx index 5e96b09f..4fb4f005 100644 --- a/fern/pages/integrations/openclaw.mdx +++ b/fern/pages/integrations/openclaw.mdx @@ -2,7 +2,7 @@ title: OpenClaw subtitle: Give your OpenClaw agent its own email inbox slug: integrations/openclaw -description: AgentMail's OpenClaw integration +description: "Give an OpenClaw agent a real email inbox with the official AgentMail skill or a custom integration for sending, receiving, and managing conversations." --- ## Getting started diff --git a/fern/pages/integrations/replit.mdx b/fern/pages/integrations/replit.mdx index 8a2b7d0d..e07f2b73 100644 --- a/fern/pages/integrations/replit.mdx +++ b/fern/pages/integrations/replit.mdx @@ -2,7 +2,7 @@ title: Replit subtitle: Integrate AgentMail with your Replit apps and agents slug: integrations/replit -description: AgentMail's Replit integration +description: "Connect AgentMail to Replit apps and agents, authenticate with an API key, and add programmable inbox, message, and email workflow capabilities through APIs." --- ## Getting started diff --git a/fern/pages/integrations/sim.mdx b/fern/pages/integrations/sim.mdx index fec5f3a1..d9bca4ce 100644 --- a/fern/pages/integrations/sim.mdx +++ b/fern/pages/integrations/sim.mdx @@ -2,7 +2,7 @@ title: Sim.ai subtitle: Connect AgentMail to your Sim.ai workflows slug: integrations/sim -description: AgentMail's Sim.ai integration +description: "Connect AgentMail to Sim.ai workflows so agents can create inboxes, process email, manage conversations, handle drafts, and organize messages with labels." --- ## Getting started diff --git a/fern/pages/integrations/skills.mdx b/fern/pages/integrations/skills.mdx index 8c42133a..06b96305 100644 --- a/fern/pages/integrations/skills.mdx +++ b/fern/pages/integrations/skills.mdx @@ -2,7 +2,7 @@ title: Skills subtitle: Add AgentMail to AI coding assistants with the official skill slug: integrations/skills -description: AgentMail's official skill for OpenClaw, Claude Code, Cursor, and other AI assistants +description: "Install the official AgentMail skill in Claude Code, Cursor, Codex, OpenClaw, and compatible assistants to add inbox and email tools to AI agents quickly." --- ## Getting started diff --git a/fern/pages/integrations/x402.mdx b/fern/pages/integrations/x402.mdx index cd706dde..aa6a06dc 100644 --- a/fern/pages/integrations/x402.mdx +++ b/fern/pages/integrations/x402.mdx @@ -2,7 +2,7 @@ title: x402 subtitle: Pay-per-use AgentMail with the x402 payment protocol slug: integrations/x402 -description: AgentMail's x402 integration for HTTP-native payments +description: "Use AgentMail through the x402 payment protocol so autonomous agents can pay for email API usage over HTTP on supported blockchain networks at runtime." --- ## Getting started diff --git a/fern/pages/knowledge-base/allowlists-blocklists.mdx b/fern/pages/knowledge-base/allowlists-blocklists.mdx index c79a9f9f..7f139b73 100644 --- a/fern/pages/knowledge-base/allowlists-blocklists.mdx +++ b/fern/pages/knowledge-base/allowlists-blocklists.mdx @@ -2,6 +2,7 @@ title: "How do I set up allowlists and blocklists?" subtitle: Control who your AI agent can send to and receive from. slug: knowledge-base/allowlists-blocklists +description: "Configure AgentMail allowlists and blocklists to control which email addresses or domains an AI agent can send to, receive from, and reply to safely at scale." --- Allowlists and blocklists let you control who your AI agent can communicate with. This is a critical safety feature for autonomous agents running in production with minimal human oversight. diff --git a/fern/pages/knowledge-base/api-403-error.mdx b/fern/pages/knowledge-base/api-403-error.mdx index a47c6921..0cf287fa 100644 --- a/fern/pages/knowledge-base/api-403-error.mdx +++ b/fern/pages/knowledge-base/api-403-error.mdx @@ -2,6 +2,7 @@ title: "What does a 403 error mean?" subtitle: Common causes of API 403 Forbidden errors and how to fix them. slug: knowledge-base/api-403-error +description: "Diagnose AgentMail API 403 Forbidden errors caused by invalid keys, insufficient permissions, scope restrictions, unverified accounts, or resource access." --- A `403 Forbidden` response from the AgentMail API means your request was rejected. This can happen for several reasons, and the fix depends on the cause. diff --git a/fern/pages/knowledge-base/creating-first-inbox.mdx b/fern/pages/knowledge-base/creating-first-inbox.mdx index c384b3e4..1c075c55 100644 --- a/fern/pages/knowledge-base/creating-first-inbox.mdx +++ b/fern/pages/knowledge-base/creating-first-inbox.mdx @@ -2,6 +2,7 @@ title: "How do I create my first inbox?" subtitle: Get up and running with your first AgentMail inbox. slug: knowledge-base/creating-first-inbox +description: "Create your first AgentMail inbox with the Python or TypeScript SDK, choose a default or custom domain, authenticate requests, and send a test email safely." --- Creating an inbox gives your AI agent its own email address. You can create inboxes on the default `@agentmail.to` domain or on your own custom domain. diff --git a/fern/pages/knowledge-base/custom-domain-setup.mdx b/fern/pages/knowledge-base/custom-domain-setup.mdx index a8cdcb39..50225070 100644 --- a/fern/pages/knowledge-base/custom-domain-setup.mdx +++ b/fern/pages/knowledge-base/custom-domain-setup.mdx @@ -2,6 +2,7 @@ title: "How do I set up a custom domain?" subtitle: Send emails from your own domain instead of @agentmail.to. slug: knowledge-base/custom-domain-setup +description: "Set up an AgentMail custom domain, add and verify DNS records, send from your brand, avoid provider conflicts, and improve trust and deliverability for agents." --- Custom domains let your agent send emails from your brand (e.g., `agent@yourcompany.com`) instead of the default `@agentmail.to`. This improves deliverability and builds trust with recipients. diff --git a/fern/pages/knowledge-base/dns-cloudflare.mdx b/fern/pages/knowledge-base/dns-cloudflare.mdx index 22797e2e..54bb011d 100644 --- a/fern/pages/knowledge-base/dns-cloudflare.mdx +++ b/fern/pages/knowledge-base/dns-cloudflare.mdx @@ -2,6 +2,7 @@ title: "DNS Guide: Cloudflare" subtitle: Step-by-step instructions for adding AgentMail DNS records in Cloudflare. slug: knowledge-base/dns-cloudflare +description: "Add AgentMail SPF, DKIM, DMARC, MX, and tracking records in Cloudflare DNS, disable proxying where required, verify values, and troubleshoot setup issues." --- ## Steps diff --git a/fern/pages/knowledge-base/dns-godaddy.mdx b/fern/pages/knowledge-base/dns-godaddy.mdx index 31c927f4..ceb0078e 100644 --- a/fern/pages/knowledge-base/dns-godaddy.mdx +++ b/fern/pages/knowledge-base/dns-godaddy.mdx @@ -2,6 +2,7 @@ title: "DNS Guide: GoDaddy" subtitle: Step-by-step instructions for adding AgentMail DNS records in GoDaddy. slug: knowledge-base/dns-godaddy +description: "Add AgentMail SPF, DKIM, DMARC, MX, and tracking records in GoDaddy DNS, enter host values correctly, verify the domain, and troubleshoot setup issues." --- ## Steps diff --git a/fern/pages/knowledge-base/dns-namecheap.mdx b/fern/pages/knowledge-base/dns-namecheap.mdx index d5354985..9e207a1c 100644 --- a/fern/pages/knowledge-base/dns-namecheap.mdx +++ b/fern/pages/knowledge-base/dns-namecheap.mdx @@ -2,6 +2,7 @@ title: "DNS Guide: Namecheap" subtitle: Step-by-step instructions for adding AgentMail DNS records in Namecheap. slug: knowledge-base/dns-namecheap +description: "Add AgentMail SPF, DKIM, DMARC, MX, and tracking records in Namecheap Advanced DNS, enter hosts correctly, verify the domain, and safely fix common issues." --- ## Steps diff --git a/fern/pages/knowledge-base/dns-route53.mdx b/fern/pages/knowledge-base/dns-route53.mdx index 8ab56c77..7c5868e3 100644 --- a/fern/pages/knowledge-base/dns-route53.mdx +++ b/fern/pages/knowledge-base/dns-route53.mdx @@ -2,6 +2,7 @@ title: "DNS Guide: Route 53 (AWS)" subtitle: Step-by-step instructions for adding AgentMail DNS records in AWS Route 53. slug: knowledge-base/dns-route53 +description: "Add AgentMail SPF, DKIM, DMARC, MX, and tracking records in AWS Route 53, configure record names and values, verify DNS, and troubleshoot setup issues." --- ## Steps diff --git a/fern/pages/knowledge-base/domain-not-verifying.mdx b/fern/pages/knowledge-base/domain-not-verifying.mdx index 5f7f0eb2..97ece497 100644 --- a/fern/pages/knowledge-base/domain-not-verifying.mdx +++ b/fern/pages/knowledge-base/domain-not-verifying.mdx @@ -2,6 +2,7 @@ title: "Why is my domain not verifying?" subtitle: What to do when your domain verification is stuck. slug: knowledge-base/domain-not-verifying +description: "Fix an AgentMail domain stuck in pending or failed verification by checking DNS values, propagation, proxy settings, record conflicts, and retry timing." --- If your domain is stuck in a pending or failed verification state, work through these common causes. diff --git a/fern/pages/knowledge-base/domain-warming.mdx b/fern/pages/knowledge-base/domain-warming.mdx index cc6b9958..2ac3c10a 100644 --- a/fern/pages/knowledge-base/domain-warming.mdx +++ b/fern/pages/knowledge-base/domain-warming.mdx @@ -2,6 +2,7 @@ title: "Warming Up" subtitle: Gradually build sending reputation on a new domain or inbox. slug: knowledge-base/domain-warming +description: "Warm up a new AgentMail domain or inbox by increasing volume gradually, protecting sender reputation, monitoring engagement, and using SMTP warmup tools." --- Warming up is the process of gradually increasing your email volume on a new domain to build sender reputation with mailbox providers like Gmail, Outlook, and Yahoo. diff --git a/fern/pages/knowledge-base/emails-bouncing.mdx b/fern/pages/knowledge-base/emails-bouncing.mdx index 2629f1be..ed87b449 100644 --- a/fern/pages/knowledge-base/emails-bouncing.mdx +++ b/fern/pages/knowledge-base/emails-bouncing.mdx @@ -2,6 +2,7 @@ title: "Why are my emails bouncing?" subtitle: Diagnose and resolve email bounce issues. slug: knowledge-base/emails-bouncing +description: "Diagnose AgentMail email bounces, distinguish permanent and temporary failures, inspect bounce events, clean invalid addresses, and protect sender reputation." --- A bounced email means the recipient's mail server rejected your message. Understanding the bounce type helps you take the right action. diff --git a/fern/pages/knowledge-base/emails-going-to-spam.mdx b/fern/pages/knowledge-base/emails-going-to-spam.mdx index 730c0950..3f9aa4dd 100644 --- a/fern/pages/knowledge-base/emails-going-to-spam.mdx +++ b/fern/pages/knowledge-base/emails-going-to-spam.mdx @@ -2,6 +2,7 @@ title: "Why are my emails going to spam?" subtitle: Troubleshoot and fix spam folder placement issues. slug: knowledge-base/emails-going-to-spam +description: "Troubleshoot AgentMail messages landing in spam by checking DNS authentication, domain warmup, sender reputation, email content, volume, and engagement." --- If your agent's emails are landing in spam instead of the inbox, work through these common causes in order. The most frequent issues are at the top. diff --git a/fern/pages/knowledge-base/getting-api-key.mdx b/fern/pages/knowledge-base/getting-api-key.mdx index 270b6b9e..6c5bdc1c 100644 --- a/fern/pages/knowledge-base/getting-api-key.mdx +++ b/fern/pages/knowledge-base/getting-api-key.mdx @@ -2,6 +2,7 @@ title: "How do I get my API key?" subtitle: Create and manage your AgentMail API keys. slug: knowledge-base/getting-api-key +description: "Create an AgentMail API key in the Console, store it securely, authenticate SDK requests, and understand organization, Pod, and inbox-scoped access boundaries." --- You need an API key to authenticate requests to the AgentMail API. API keys start with `am_` and are created in the AgentMail Console. diff --git a/fern/pages/knowledge-base/handling-inbound-emails.mdx b/fern/pages/knowledge-base/handling-inbound-emails.mdx index 869518ad..0f051f46 100644 --- a/fern/pages/knowledge-base/handling-inbound-emails.mdx +++ b/fern/pages/knowledge-base/handling-inbound-emails.mdx @@ -2,6 +2,7 @@ title: "How do I handle inbound emails with my agent?" subtitle: Compare Webhooks and WebSockets for processing incoming emails. slug: knowledge-base/handling-inbound-emails +description: "Compare AgentMail webhooks and WebSockets for handling inbound email, then choose the right real-time event delivery method for your agent workflow reliably." --- AgentMail offers two ways to process incoming emails, each suited to different use cases. diff --git a/fern/pages/knowledge-base/human-in-the-loop.mdx b/fern/pages/knowledge-base/human-in-the-loop.mdx index 50822437..43be4fcc 100644 --- a/fern/pages/knowledge-base/human-in-the-loop.mdx +++ b/fern/pages/knowledge-base/human-in-the-loop.mdx @@ -2,6 +2,7 @@ title: "How do I build a human-in-the-loop workflow?" subtitle: Keep humans in control of your agent's email communications. slug: knowledge-base/human-in-the-loop +description: "Build human-in-the-loop AgentMail workflows with CC and BCC visibility, draft review, approval gates, permissions, audit labels, and escalation patterns." --- AgentMail provides several mechanisms for keeping humans involved when agents send emails. You can combine these approaches to match the level of oversight your workflow requires. diff --git a/fern/pages/knowledge-base/inbound-emails-missing.mdx b/fern/pages/knowledge-base/inbound-emails-missing.mdx index 6a58804c..5ccb3852 100644 --- a/fern/pages/knowledge-base/inbound-emails-missing.mdx +++ b/fern/pages/knowledge-base/inbound-emails-missing.mdx @@ -2,6 +2,7 @@ title: "Why are my emails not showing up?" subtitle: The most common reason inbound emails go missing is that the sender's domain failed authentication. slug: knowledge-base/inbound-emails-missing +description: "Troubleshoot missing inbound AgentMail messages by checking SPF, DKIM, and DMARC authentication, spam labels, blocklists, DNS routing, and event delivery." --- diff --git a/fern/pages/knowledge-base/inbox-capabilities.mdx b/fern/pages/knowledge-base/inbox-capabilities.mdx index 0649ffe6..b8e2fc4d 100644 --- a/fern/pages/knowledge-base/inbox-capabilities.mdx +++ b/fern/pages/knowledge-base/inbox-capabilities.mdx @@ -2,6 +2,7 @@ title: "What can I do with an AgentMail inbox?" subtitle: A complete overview of inbox capabilities for AI agents. slug: knowledge-base/inbox-capabilities +description: "Explore what an AgentMail inbox can do, including sending, receiving, replying, forwarding, drafting, labeling, attaching files, and managing conversations." --- An AgentMail inbox is a full email account for your AI agent. Each inbox gets a unique email address and can send, receive, reply, forward, and manage emails entirely through the API. diff --git a/fern/pages/knowledge-base/introduction.mdx b/fern/pages/knowledge-base/introduction.mdx index 1282360a..94ba458e 100644 --- a/fern/pages/knowledge-base/introduction.mdx +++ b/fern/pages/knowledge-base/introduction.mdx @@ -2,6 +2,7 @@ title: Knowledge Base subtitle: A collection of answers to frequently asked questions. slug: knowledge-base +description: "Browse AgentMail answers and troubleshooting guides for inbox setup, agent workflows, domains, deliverability, DNS configuration, API errors, and email issues." --- ## Getting Started diff --git a/fern/pages/knowledge-base/labels-track-state.mdx b/fern/pages/knowledge-base/labels-track-state.mdx index 3242c132..a5b175b9 100644 --- a/fern/pages/knowledge-base/labels-track-state.mdx +++ b/fern/pages/knowledge-base/labels-track-state.mdx @@ -2,6 +2,7 @@ title: "How do I use labels to track email state?" subtitle: Use labels to manage agent workflow state on emails and threads. slug: knowledge-base/labels-track-state +description: "Use AgentMail labels to track email workflow state, classify messages and threads, filter conversations, coordinate agents, and support reliable automation." --- Labels are string-based tags you attach to messages and threads. They are the primary way agents track state, classify emails, and filter conversations in AgentMail. diff --git a/fern/pages/knowledge-base/mx-record-conflicts.mdx b/fern/pages/knowledge-base/mx-record-conflicts.mdx index b096fe0d..30445ae4 100644 --- a/fern/pages/knowledge-base/mx-record-conflicts.mdx +++ b/fern/pages/knowledge-base/mx-record-conflicts.mdx @@ -2,6 +2,7 @@ title: "How do I avoid MX record conflicts?" subtitle: Add AgentMail DNS records without breaking existing email. slug: knowledge-base/mx-record-conflicts +description: "Avoid MX record conflicts when using AgentMail with Google Workspace, Outlook, or another provider by choosing a subdomain and preserving existing mail." --- If you already use Gmail, Outlook, or another email provider for your domain, adding AgentMail's MX records could conflict with your existing setup. Here is how to avoid that. diff --git a/fern/pages/knowledge-base/pods-multi-tenant.mdx b/fern/pages/knowledge-base/pods-multi-tenant.mdx index 0f6e3198..2c16fee7 100644 --- a/fern/pages/knowledge-base/pods-multi-tenant.mdx +++ b/fern/pages/knowledge-base/pods-multi-tenant.mdx @@ -2,6 +2,7 @@ title: "How do I use Pods for multi-tenant email?" subtitle: Isolate inboxes, domains, and data across tenants with Pods. slug: knowledge-base/pods-multi-tenant +description: "Use AgentMail Pods to isolate inboxes, domains, threads, drafts, API keys, and customer data across secure multi-tenant applications and agent platforms." --- Pods provide tenant isolation for multi-tenant applications. Each Pod is an isolated workspace containing its own inboxes, domains, threads, and drafts, completely separated from other Pods. diff --git a/fern/pages/knowledge-base/preventing-duplicate-sends.mdx b/fern/pages/knowledge-base/preventing-duplicate-sends.mdx index 75a5685b..0aabe4fb 100644 --- a/fern/pages/knowledge-base/preventing-duplicate-sends.mdx +++ b/fern/pages/knowledge-base/preventing-duplicate-sends.mdx @@ -2,6 +2,7 @@ title: "How do I prevent duplicate sends?" subtitle: Use idempotency to avoid sending the same email twice. slug: knowledge-base/preventing-duplicate-sends +description: "Prevent duplicate AgentMail sends and resources by using client IDs, idempotent create operations, stable retry keys, and safe network retry patterns." --- AI agents can sometimes retry requests due to network errors, timeouts, or logic bugs. Without safeguards, this can cause the same email to be sent multiple times. Here is how to prevent that. diff --git a/fern/pages/knowledge-base/rate-limits.mdx b/fern/pages/knowledge-base/rate-limits.mdx index 81d92574..266c03dc 100644 --- a/fern/pages/knowledge-base/rate-limits.mdx +++ b/fern/pages/knowledge-base/rate-limits.mdx @@ -2,6 +2,7 @@ title: "What are the rate limits?" subtitle: Understand AgentMail's rate limits and how to work within them. slug: knowledge-base/rate-limits +description: "Understand AgentMail API and sending limits by plan, recognize 429 responses, use retry headers and backoff, and design high-volume agent workflows at scale." --- AgentMail is built for high-volume agent workflows. Limits vary by plan. diff --git a/fern/pages/knowledge-base/spf-dkim-dmarc.mdx b/fern/pages/knowledge-base/spf-dkim-dmarc.mdx index f98b0995..d4ec55bd 100644 --- a/fern/pages/knowledge-base/spf-dkim-dmarc.mdx +++ b/fern/pages/knowledge-base/spf-dkim-dmarc.mdx @@ -2,6 +2,7 @@ title: "How do I set up SPF, DKIM, and DMARC?" subtitle: Authenticate your domain for reliable email deliverability. slug: knowledge-base/spf-dkim-dmarc +description: "Configure SPF, DKIM, and DMARC records for AgentMail, verify domain authentication, prevent spoofing, and improve reliable inbox placement with DNS for agents." --- SPF, DKIM, and DMARC are three email authentication protocols that prove your emails are legitimate. They are essential for deliverability: Gmail, Outlook, and other major providers now require all three for reliable inbox placement. diff --git a/fern/pages/knowledge-base/threaded-conversations.mdx b/fern/pages/knowledge-base/threaded-conversations.mdx index 22e45978..a3dd7229 100644 --- a/fern/pages/knowledge-base/threaded-conversations.mdx +++ b/fern/pages/knowledge-base/threaded-conversations.mdx @@ -2,6 +2,7 @@ title: "How do I manage threaded conversations?" subtitle: Maintain context across multi-turn email conversations with your agent. slug: knowledge-base/threaded-conversations +description: "Manage multi-turn email conversations with AgentMail threads so agents can preserve context, retrieve message history, reply correctly, and track state." --- Threads are how AgentMail organizes conversations. Every time your agent sends a new email, a thread is created. Replies are automatically grouped into the same thread, giving your agent full conversation context. diff --git a/fern/pages/knowledge-base/what-is-agentmail.mdx b/fern/pages/knowledge-base/what-is-agentmail.mdx index 38879970..ef3820a1 100644 --- a/fern/pages/knowledge-base/what-is-agentmail.mdx +++ b/fern/pages/knowledge-base/what-is-agentmail.mdx @@ -2,6 +2,7 @@ title: "What is AgentMail and how is it different?" subtitle: Understand how AgentMail compares to traditional email providers. slug: knowledge-base/what-is-agentmail +description: "Learn how AgentMail gives AI agents dedicated, API-first inboxes with two-way email, native threading, receiving support, and scalable identity management." --- AgentMail is email infrastructure built specifically for AI agents. Unlike transactional email APIs that focus on one-way sending, AgentMail is built for two-way agent communication: dedicated inboxes, native threading, and full receiving support with no shared sending domains. diff --git a/fern/pages/resources/community.mdx b/fern/pages/resources/community.mdx index 5f9044bf..dfb80675 100644 --- a/fern/pages/resources/community.mdx +++ b/fern/pages/resources/community.mdx @@ -1,7 +1,7 @@ --- title: "Join the AgentMail Community" slug: community -description: "Connect with the AgentMail team and developers, share what you're building, and get support." +description: "Join the AgentMail developer community to ask questions, share AI email projects, get implementation help, follow product updates, and connect with the team." --- diff --git a/fern/pages/resources/errors.mdx b/fern/pages/resources/errors.mdx index acb031c0..6d60cb88 100644 --- a/fern/pages/resources/errors.mdx +++ b/fern/pages/resources/errors.mdx @@ -1,7 +1,7 @@ --- title: "Error Reference" slug: errors -description: "Every AgentMail API error code, what it means, and how to fix it." +description: "Understand every AgentMail API error code, response field, likely cause, and recommended fix so agents can recover from failed requests safely and reliably." --- Every error response from the AgentMail API includes a stable, machine-readable `code` you can branch on, a `message` describing what went wrong, and a `docs` link pointing to the matching entry on this page. Most responses also include a `fix` describing the concrete next action that resolves it; `fix` is omitted when no generic remedy applies. diff --git a/fern/pages/resources/faq.mdx b/fern/pages/resources/faq.mdx index 685c46fa..a5fdf040 100644 --- a/fern/pages/resources/faq.mdx +++ b/fern/pages/resources/faq.mdx @@ -1,7 +1,7 @@ --- title: "Frequently Asked Questions (FAQ)" slug: faq -description: "Find answers to common questions about AgentMail, from core concepts to best practices and security." +description: "Find answers to common AgentMail questions about inboxes, sending and receiving email, security, deliverability, API behavior, billing, and agent workflows." --- diff --git a/fern/pages/resources/security/email-protocols.mdx b/fern/pages/resources/security/email-protocols.mdx index 92f5ddba..5526904b 100644 --- a/fern/pages/resources/security/email-protocols.mdx +++ b/fern/pages/resources/security/email-protocols.mdx @@ -1,7 +1,7 @@ --- title: "Understanding Email Authentication (SPF, DKIM, DMARC)" slug: email-protocols -description: "Learn why we ask for DNS records and what SPF, DKIM, and DMARC are." +description: "Understand SPF, DKIM, and DMARC email authentication, why AgentMail requires DNS records, and how these protocols protect sender identity and delivery." --- When you add a custom domain to AgentMail, we ask you to add several records to your DNS settings. We understand that this can seem daunting, and we want to be completely transparent about what these records are and why they are necessary. diff --git a/fern/pages/resources/security/soc2.mdx b/fern/pages/resources/security/soc2.mdx index 26957f48..e9e3f89b 100644 --- a/fern/pages/resources/security/soc2.mdx +++ b/fern/pages/resources/security/soc2.mdx @@ -1,8 +1,8 @@ --- title: "SOC 2 Compliance" -description: "AgentMail's SOC 2 Type I and Type II compliance." sidebar_position: 40 lastUpdated: "2026-03-17" +description: "Review AgentMail SOC 2 Type I and Type II compliance, validated security controls, certification status, trust service criteria, and operational safeguards." --- > AgentMail has achieved **SOC 2 Type I** (July 2025) and **Type II** (Q1 2026) compliance. diff --git a/fern/pages/resources/security/spam-virus-detection.mdx b/fern/pages/resources/security/spam-virus-detection.mdx index 4abddff4..8909128f 100644 --- a/fern/pages/resources/security/spam-virus-detection.mdx +++ b/fern/pages/resources/security/spam-virus-detection.mdx @@ -1,7 +1,7 @@ --- title: "Spam & Virus Detection" slug: spam-virus-detection -description: "How AgentMail automatically scans incoming emails for spam and viruses." +description: "Learn how AgentMail scans inbound email for spam, viruses, and malware, rejects dangerous messages, labels suspicious mail, and keeps agent workflows clean." --- AgentMail automatically scans every inbound message for spam and viruses before it reaches your inbox. This happens transparently — there is nothing you need to configure. diff --git a/fern/pages/resources/support.mdx b/fern/pages/resources/support.mdx index 57c365c8..62df1740 100644 --- a/fern/pages/resources/support.mdx +++ b/fern/pages/resources/support.mdx @@ -1,7 +1,7 @@ --- title: Support slug: support -description: Get help with AgentMail through our support channels. +description: "Get AgentMail support through email, Discord, and documentation resources for API integration questions, deliverability issues, billing, and account help." --- ## Need Help? diff --git a/fern/pages/resources/talon.mdx b/fern/pages/resources/talon.mdx index 0d983ac1..c8b59fcb 100644 --- a/fern/pages/resources/talon.mdx +++ b/fern/pages/resources/talon.mdx @@ -2,7 +2,7 @@ title: "Email Reply Extraction with Talon" subtitle: "Extract clean reply content from email threads using Talon library" slug: talon-reply-extraction -description: "Learn how to use Talon to extract new content from email replies, removing quoted text with 93.8% accuracy." +description: "Use Talon with AgentMail to extract new reply content from email threads, remove quoted history and signatures, and give agents cleaner text to process." --- ## Why Talon? diff --git a/fern/pages/webhooks/webhook-setup.mdx b/fern/pages/webhooks/webhook-setup.mdx index cf95baff..a47c15a7 100644 --- a/fern/pages/webhooks/webhook-setup.mdx +++ b/fern/pages/webhooks/webhook-setup.mdx @@ -2,7 +2,7 @@ title: "Webhook Setup Guide" subtitle: "Step-by-step guide to configure webhooks." slug: webhook-setup -description: "A comprehensive guide to setting up webhooks with ngrok and AgentMail, including account creation, inbox setup, and code examples." +description: "Set up AgentMail webhooks to receive email events, create an endpoint, register subscriptions, test delivery, process payloads, and handle retries safely." --- This guide walks you through the complete process of setting up webhooks to receive real-time notifications from AgentMail. You'll learn how to create an ngrok account, set up an inbox, configure webhooks, and write a simple webhook receiver. diff --git a/fern/pages/webhooks/webhook-verification.mdx b/fern/pages/webhooks/webhook-verification.mdx index b0b47559..8ac55336 100644 --- a/fern/pages/webhooks/webhook-verification.mdx +++ b/fern/pages/webhooks/webhook-verification.mdx @@ -2,7 +2,7 @@ title: "Verifying Webhooks" subtitle: "Ensure webhook requests are authentically from AgentMail." slug: webhook-verification -description: "Learn how to verify webhook signatures to secure your webhook endpoints and prevent spoofed requests." +description: "Verify AgentMail webhook signatures, validate request timestamps and payloads, reject spoofed events, and secure endpoints with Python or TypeScript code." --- When building webhook receivers, it's critical to verify that incoming requests actually originate from AgentMail and haven't been tampered with. AgentMail uses [Svix](https://www.svix.com/) to deliver webhooks, which provides cryptographic signature verification. diff --git a/fern/pages/webhooks/webhooks-events.mdx b/fern/pages/webhooks/webhooks-events.mdx index 618a927c..257d95b8 100644 --- a/fern/pages/webhooks/webhooks-events.mdx +++ b/fern/pages/webhooks/webhooks-events.mdx @@ -1,6 +1,7 @@ --- title: "Webhook Events" slug: events +description: "Explore AgentMail webhook event types and payloads for received, sent, delivered, bounced, complained, rejected, and domain verification activity in production." --- As mentioned in the overview, webhooks allow us to create event-driven applications. diff --git a/fern/pages/webhooks/webhooks-overview.mdx b/fern/pages/webhooks/webhooks-overview.mdx index 54321681..c7869065 100644 --- a/fern/pages/webhooks/webhooks-overview.mdx +++ b/fern/pages/webhooks/webhooks-overview.mdx @@ -2,7 +2,7 @@ title: "Webhooks Overview" subtitle: "Get real-time notifications for email events." slug: webhooks-overview -description: "Learn how to use Webhooks to build responsive, event-driven email agents with AgentMail." +description: "Learn how AgentMail webhooks deliver real-time email events to your application, including subscriptions, payloads, retries, verification, and security." --- Webhooks are the best way to get real-time information about what's happening with your emails. Instead of constantly asking the AgentMail API if there's a new email (a process called polling), you can register a URL, and we will send you a `POST` request with the details as soon as an event happens. diff --git a/fern/pages/websockets-quickstart.mdx b/fern/pages/websockets-quickstart.mdx index 66932d43..cd8cfaf4 100644 --- a/fern/pages/websockets-quickstart.mdx +++ b/fern/pages/websockets-quickstart.mdx @@ -2,6 +2,7 @@ title: "WebSockets Quickstart" subtitle: "Get started with real-time email event streaming" slug: websockets/quickstart +description: "Connect to AgentMail WebSockets, subscribe to inboxes, and process real-time email events with complete Python and TypeScript examples for AI agents in minutes." --- ## Copy for Cursor / Claude diff --git a/fern/pages/websockets.mdx b/fern/pages/websockets.mdx index db697fbd..f3c00e62 100644 --- a/fern/pages/websockets.mdx +++ b/fern/pages/websockets.mdx @@ -2,7 +2,7 @@ title: "WebSockets" subtitle: "Real-time, low-latency email event streaming" slug: websockets -description: "Learn how to use WebSockets for instant email notifications without webhooks or polling." +description: "Use AgentMail WebSockets for low-latency email events without polling, including authentication, inbox subscriptions, typed events, and reconnect handling." --- WebSockets provide a persistent, bidirectional connection to AgentMail for receiving email events in real-time. Unlike webhooks, WebSockets don't require a public URL or external tools like ngrok. diff --git a/package.json b/package.json index 24ca0344..619e71cc 100644 --- a/package.json +++ b/package.json @@ -7,8 +7,9 @@ "scripts": { "docs:preview": "tsx bin/agentmail-docs.ts preview", "docs:publish": "tsx bin/agentmail-docs.ts publish", - "lint": "tsc --noEmit", - "format": "prettier --write \"bin/**/*.ts\" package.json tsconfig.json" + "lint": "tsc --noEmit && npm run lint:seo", + "lint:seo": "node bin/check-seo-metadata.mjs", + "format": "prettier --write \"bin/**/*.{ts,mjs}\" package.json tsconfig.json" }, "devDependencies": { "@types/node": "^22.0.0",