diff --git a/api-reference/authentication.mdx b/api-reference/authentication.mdx index 4b98726..863940d 100644 --- 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 index bb5c671..d1b9979 100644 --- 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 index 17aae48..cf4c8c8 100644 --- 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 index 74a69d4..d78cd2f 100644 --- 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 index 037cb6a..3beb801 100644 --- 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. + + + 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. + + ## Limits Custom domains are available on paid plans. diff --git a/concepts/inboxes.mdx b/concepts/inboxes.mdx index c8e6ff8..393db71 100644 --- 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 index eecc620..bf5ba75 100644 --- 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 index f01f815..6a076f1 100644 --- 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 index 247f7e6..75307e2 100644 --- 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 index 3f95754..94c6af0 100644 --- 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 index 95ba698..4a07097 100644 --- 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 index 1b96546..3f48579 100644 --- 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 index 984756e..44471bf 100644 --- 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 index 5b0ef77..2a7b0c8 100644 --- 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 index 6bb0306..9626bdc 100644 --- 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 index bb5aec6..c5a1259 100644 --- 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 index 1fe401f..482f698 100644 --- 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 index d4facce..762e34e 100644 --- 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 index 2c9e3c4..506b8a1 100644 --- 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 index c4a30cd..ec86d63 100644 --- 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 index d54d018..5761eaf 100644 --- 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 index 864134f..d5d45ed 100644 --- 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 index 6eb68f9..16339c4 100644 --- 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 index 646bf81..a0d9605 100644 --- 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 ---