openmailsh · armandokun · Jun 1, 2026 · Jun 2, 2026
diff --git a/api-reference/authentication.mdx b/api-reference/authentication.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Authentication"
-description: "API key authentication"
+description: "Authenticate OpenMail API requests using a Bearer token in the Authorization header. Learn how to generate and manage API keys for your inboxes."
 icon: key
 ---
 

diff --git a/api-reference/introduction.mdx b/api-reference/introduction.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Introduction"
-description: "OpenMail API reference for inboxes, messages, and webhooks"
+description: "OpenMail REST API reference for inboxes, messages, threads, and webhooks. Accepts JSON, returns JSON, uses Bearer token authentication. Base URL: api.openmail.sh."
 icon: book
 ---
 

diff --git a/api-reference/overview.mdx b/api-reference/overview.mdx
@@ -1,6 +1,6 @@
 ---
 title: "API Overview"
-description: "Base URL, request format, and error handling"
+description: "OpenMail API overview — base URL, request and response format, authentication, error codes, and rate limits for the OpenMail REST API."
 icon: list
 ---
 

diff --git a/concepts/attachments.mdx b/concepts/attachments.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Attachments"
-description: "Send files with outbound emails and access attachments from inbound emails"
+description: "Send files with outbound emails and access inbound attachments via the OpenMail API. Supports PDF, DOCX, and other formats — with plain-text extraction for LLMs."
 icon: paperclip
 ---
 

diff --git a/concepts/custom-domains.mdx b/concepts/custom-domains.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Custom domains"
-description: "Send and receive email from your own domain"
+description: "Send and receive email from your own domain with OpenMail. Configure custom domains with SPF, DKIM, and DMARC — all handled automatically on inbox provisioning."
 icon: globe
 ---
 
@@ -82,6 +82,44 @@ The resulting address uses your domain:
 
 If you omit `domain`, the inbox is created on your account default domain (for example `@openmail.sh`). Passing a domain that is not verified or does not belong to your account returns `invalid_domain`.
 
+## Sender avatars (BIMI)
+
+You can publish a logo for your domain so mailbox providers that support [BIMI](https://bimigroup.org) (Brand Indicators for Message Identification) — such as Gmail and Apple Mail — show it next to messages you send.
+
+BIMI is configured **per domain**, not per inbox. Every inbox on the domain shares the same avatar, because the logo is published in DNS at the domain level. Gmail and Outlook do not support per-address avatars for programmatic senders.
+
+### Requirements
+
+- A **verified** custom domain with DMARC enforced (`p=quarantine` or `p=reject`).
+- An SVG logo in the **SVG Tiny Portable/Secure (SVG Tiny PS)** profile, hosted over HTTPS.
+- For Gmail and Apple Mail, a **Verified Mark Certificate (VMC)** is also required. Without a VMC the record is still valid but most providers will not display the logo.
+
+### Configuring BIMI
+
+Set the logo (and optional VMC) on a verified domain:
+
+```bash
+curl -X PATCH https://api.openmail.sh/dashboard/domains/{domainId}/bimi \
+  -H "Authorization: Bearer $OPENMAIL_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "logoUrl": "https://cdn.yourdomain.com/logo.svg",
+    "vmcUrl": "https://cdn.yourdomain.com/vmc.pem"
+  }'
+```
+
+OpenMail then returns a `default._bimi` TXT record to add at your registrar, alongside your existing MX, SPF, and DKIM records:
+
+| Type | Host | Value |
+|------|------|-------|
+| TXT | `default._bimi` | `v=BIMI1; l=https://cdn.yourdomain.com/logo.svg; a=https://cdn.yourdomain.com/vmc.pem;` |
+
+Pass an empty string for `logoUrl` to remove the avatar. `vmcUrl` is optional; omit it to publish a logo-only record.
+
+<Note>
+  Avatar display is controlled by the receiving provider, not OpenMail. Even with a valid record and VMC, providers roll out BIMI gradually and may take time to show your logo.
+</Note>
+
 ## Limits
 
 Custom domains are available on paid plans.

diff --git a/concepts/inboxes.mdx b/concepts/inboxes.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Inboxes"
-description: "Every agent gets a dedicated email address"
+description: "An inbox is a unique email address assigned to an AI agent. Learn how to create, manage, and use inboxes to send, receive, and thread email with the OpenMail API."
 icon: inbox
 ---
 

diff --git a/concepts/rate-limits.mdx b/concepts/rate-limits.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Rate Limits"
-description: "Send limits and cold outreach throttling"
+description: "OpenMail rate limits and send quotas — per-inbox sending limits, cold outreach throttling, and what happens when you hit the limit on your plan."
 icon: gauge
 ---
 

diff --git a/concepts/suppressions.mdx b/concepts/suppressions.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Suppressions"
-description: "Automatic protection against sending to bad addresses"
+description: "OpenMail automatically suppresses bad addresses — bounces, spam complaints, and unsubscribes — to protect your sender reputation and inbox deliverability."
 icon: ban
 ---
 

diff --git a/concepts/threading.mdx b/concepts/threading.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Threading"
-description: "How OpenMail groups messages into conversations"
+description: "OpenMail automatically groups messages into threads by subject and references headers. Learn how threading works and how to reply within an existing conversation."
 icon: messages-square
 ---
 

diff --git a/concepts/webhooks.mdx b/concepts/webhooks.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Overview"
-description: "Delivery semantics, headers, signature verification, and retries"
+description: "When email arrives at your inbox, OpenMail delivers it to your webhook URL in real time. Learn delivery semantics, headers, signature verification, and retry behavior."
 icon: eye
 ---
 

diff --git a/concepts/websockets.mdx b/concepts/websockets.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Overview"
-description: "Real-time, low-latency email event streaming"
+description: "Stream inbound email events in real time over WebSocket. Lower latency than webhooks and ideal for long-running agents that need to react to email instantly."
 icon: eye
 ---
 

diff --git a/docs.json b/docs.json
@@ -7,9 +7,9 @@
     "light": "#e5e5e5",
     "dark": "#09090b"
   },
-  "modeToggle": {
+  "appearance": {
     "default": "dark",
-    "isHidden": false
+    "strict": false
   },
   "styling": {
     "codeblocks": {
@@ -21,13 +21,34 @@
   },
   "favicon": "/favicon.ico",
   "redirects": [
-    { "source": "/quickstart/cli", "destination": "/quickstart" },
-    { "source": "/quickstart/api", "destination": "/guides/api-integration" },
-    { "source": "/guides/cli-quickstart", "destination": "/quickstart" },
-    { "source": "/guides/skills/openmail", "destination": "/integrations/skill-files/openmail" },
-    { "source": "/guides/skills/references/setup", "destination": "/integrations/skill-files/setup" },
-    { "source": "/guides/skills/references/errors", "destination": "/integrations/skill-files/errors" },
-    { "source": "/guides/skills/references/api", "destination": "/integrations/skill-files/api" }
+    {
+      "source": "/quickstart/cli",
+      "destination": "/quickstart"
+    },
+    {
+      "source": "/quickstart/api",
+      "destination": "/guides/api-integration"
+    },
+    {
+      "source": "/guides/cli-quickstart",
+      "destination": "/quickstart"
+    },
+    {
+      "source": "/guides/skills/openmail",
+      "destination": "/integrations/skill-files/openmail"
+    },
+    {
+      "source": "/guides/skills/references/setup",
+      "destination": "/integrations/skill-files/setup"
+    },
+    {
+      "source": "/guides/skills/references/errors",
+      "destination": "/integrations/skill-files/errors"
+    },
+    {
+      "source": "/guides/skills/references/api",
+      "destination": "/integrations/skill-files/api"
+    }
   ],
   "navigation": {
     "tabs": [

diff --git a/guides/api-integration.mdx b/guides/api-integration.mdx
@@ -1,6 +1,6 @@
 ---
 title: "API integration"
-description: "Create and manage inboxes via API. For multi-tenant apps and agent frameworks."
+description: "Create and manage OpenMail inboxes via REST API. Covers the multi-tenant pattern for agent frameworks like LangChain, n8n, and OpenClaw — provision inboxes, route inbound email, and inject credentials."
 icon: code
 ---
 

diff --git a/guides/webhooks.mdx b/guides/webhooks.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Setup"
-description: "Configure and implement webhook endpoints for inbound email"
+description: "Configure and implement webhook endpoints to receive inbound email events in real time. Covers endpoint setup, payload structure, signature verification, and retries."
 icon: wrench
 ---
 

diff --git a/index.mdx b/index.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Introduction"
-description: "Email infrastructure for AI agents"
+description: "OpenMail is email infrastructure purpose-built for AI agents — dedicated inboxes, real-time inbound delivery, two-way threading, and attachment parsing via API or CLI."
 icon: book
 ---
 

diff --git a/integrations/agent-frameworks.mdx b/integrations/agent-frameworks.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Agent frameworks"
-description: "Wire OpenMail into LangChain, Vercel AI SDK, or any framework that supports tool calling."
+description: "Wire OpenMail into LangChain, Vercel AI SDK, CrewAI, or any framework that supports tool calling. Includes ready-made tool definitions for send, receive, and thread operations."
 icon: cpu
 ---
 

diff --git a/integrations/claude-code.mdx b/integrations/claude-code.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Claude Code"
-description: "Give your Claude Code agent a real email address in three steps."
+description: "Give your Claude Code agent a dedicated email address in three steps. Install OpenMail, run setup, and Claude can send, receive, and reply to email immediately."
 icon: terminal
 ---
 

diff --git a/integrations/openclaw.mdx b/integrations/openclaw.mdx
@@ -1,6 +1,6 @@
 ---
 title: "OpenClaw"
-description: "Give your OpenClaw agent a real email address in three steps."
+description: "Give your OpenClaw agent a dedicated email address in three steps. OpenMail registers as an OpenClaw skill automatically — send, receive, and thread email with zero configuration."
 icon: bot
 ---
 

diff --git a/pages/resources/faq.mdx b/pages/resources/faq.mdx
@@ -1,6 +1,6 @@
 ---
 title: "FAQ"
-description: "Frequently asked questions"
+description: "Frequently asked questions about OpenMail — pricing, inbox limits, deliverability, custom domains, webhooks, and how email for AI agents works."
 icon: circle-question-mark
 ---
 

diff --git a/pages/resources/support.mdx b/pages/resources/support.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Support"
-description: "Get help with OpenMail"
+description: "Get help with OpenMail — contact support, join the Discord community, report bugs, or find answers to common setup and integration questions."
 icon: headset
 ---
 

diff --git a/pages/webhooks/events.mdx b/pages/webhooks/events.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Events"
-description: "Event types and payload structure for inbound email"
+description: "OpenMail webhook event types and payload structure for inbound email — message.received, thread.created, and all fields included in each event body."
 icon: bell
 ---
 

diff --git a/pages/websockets/protocol.mdx b/pages/websockets/protocol.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Protocol reference"
-description: "Message types, subscribe options, event replay, and connection management"
+description: "OpenMail WebSocket protocol reference — message types, subscribe options, event replay from a cursor, and connection management for real-time email streaming."
 icon: code
 ---
 

diff --git a/pages/welcome.mdx b/pages/welcome.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Welcome"
-description: "Your starting point for building with OpenMail"
+description: "Welcome to OpenMail — your starting point for giving AI agents a dedicated email address. Install the CLI, run setup, and your agent can send and receive email immediately."
 icon: hand
 ---
 

diff --git a/quickstart.mdx b/quickstart.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Quickstart"
-description: "Get your AI agent its own email address in two commands."
+description: "Get your AI agent its own dedicated email address in two commands. Install the OpenMail CLI, run setup, and start sending and receiving email immediately."
 icon: rocket
 ---