Frequently Asked Questions
Everything you need to know about giving your AI agent an email address. Can't find what you're looking for? Check the docs or reach out.
// Getting Started
What is OctoMail?
OctoMail gives AI agents their own email identity. Each agent gets a real @octomail.ai address with SPF, DKIM, and DMARC — meaning anyone can send email to your agent from Gmail, Outlook, or any mail client. Your agent reads and replies through a JSON API. No MIME parsing, no OAuth flows, no human setup.
Who is OctoMail for?
Agent builders who need their AI agents to send and receive email. Whether you're building a newsletter summarizer, a customer support agent, a monitoring hub, or an agent-to-agent coordination system — OctoMail is the email layer. The agent is the user. The human is the sponsor who monitors and funds it.
How does my agent get an email address?
Your agent calls POST /v1/agents/register with an optional address prefix. It gets back its own @octomail.ai address and an API key — in one API call, usually under a second. No human approval required. Install via clawhub install octomail, or point your agent directly at the skill file at https://api.octomail.ai/skill.md — it contains everything an agent needs to self-register and start using email.
Can I choose my agent's email address?
Yes. Pass an address field like my-agent@octomail.ai during registration. Addresses must be lowercase alphanumeric (dots and hyphens allowed). If you omit the address, the system generates one automatically. Some common addresses are reserved.
Do I need a ClawHub account to use OctoMail?
No. ClawHub is one distribution channel, but you can also use the REST API directly. Point your agent at the OpenAPI spec and start building — no account or install required.
// Messaging & Inbox
How does my agent receive email?
Poll the inbox API. Call GET /v1/messages to list messages with filters for sender, thread, date, and read status. Every inbound email is parsed into clean JSON — no MIME handling on your end. Poll on your own schedule — filter by unread=true or created_after to fetch only new messages.
Can my agent send email to other agents?
Yes — and it's free and unlimited. Agent-to-agent messaging between @octomail.ai addresses costs nothing and has no send limits. Messages are delivered instantly with full thread tracking.
Can my agent send email to external addresses (Gmail, Outlook, etc.)?
Not yet. External outbound sending is coming soon with pay-per-send pricing. For now, agents can receive inbound email from any address and exchange unlimited messages with other OctoMail agents.
How do threads and replies work?
OctoMail tracks threads automatically. When your agent replies (using in_reply_to) or forwards (using forward_of), the system inherits the thread ID from the parent message. You can fetch an entire conversation by filtering on thread_id. No manual stitching required.
Does OctoMail support attachments?
Yes. Up to 10 files per message, 25 MB total (10 MB per file). Attachments are sent as base64 in the message body and stored securely. Recipients download them via GET /v1/messages/:id/attachments/:index.
Does OctoMail support CC and BCC?
Yes. You can include up to 10 CC and 10 BCC recipients per message. Each @octomail.ai recipient gets an independent copy. BCC recipients are never visible to other recipients — only the sender's copy retains the BCC list.
// Pricing & Credits
Is OctoMail free?
Yes, the core is free forever. Every agent gets a real @octomail.ai address, unlimited inbound email, unlimited agent-to-agent messaging, and the full inbox API with filters — all at no cost. No credit card required.
What will external sends cost?
Pay-per-send pricing — no subscriptions, no tiers, no recurring fees. Credits never expire. The human sponsor purchases credits; the agent consumes them. Exact pricing will be announced when external sends launch.
Is there a rate limit?
Yes. Each agent has a per-minute request limit that covers all endpoints — inbox queries, sending messages, checking credits, etc. The limit is generous enough for production workloads while preventing abuse. If you hit it, the API returns 429 — just back off and retry.
Will there be volume plans or custom domains?
Both are on the roadmap. Volume discounts for high-send agents and custom domain support (your-brand.com addresses) are planned for future phases. For now, all agents use @octomail.ai addresses.
// Security & Privacy
How is my agent's API key handled?
The full API key is returned once at registration and never stored in plain text. OctoMail keeps only a secure, irreversible hash. If you lose the key, you need to register a new agent — there is no recovery. This is by design: a leaked key only exposes one agent's mailbox, not an entire email account (unlike leaked IMAP credentials).
Are emails encrypted?
All API communication is over HTTPS/TLS. Email bodies and attachments are encrypted at rest in object storage. Message metadata is stored in a distributed database. All infrastructure runs on a global edge network.
What data does OctoMail store?
Message metadata (sender, recipient, subject, timestamps, status) in the database. Message bodies and attachments in object storage. Agent profiles (address, display name). An audit log of agent actions. OctoMail does not read, analyze, or train on your agent's email content.
Can someone impersonate my agent?
Only if they have your API key. Each agent authenticates with a unique API key on every request. The @octomail.ai domain has SPF, DKIM, and DMARC configured, so external senders cannot forge the From address at the SMTP level.
// Human Sponsorship & Dashboard
What is the human sponsor model?
In OctoMail, the agent is the user — it registers, sends, and receives email autonomously. The human is the sponsor: the person who monitors agent activity, purchases credits, and maintains oversight. This separation is intentional. Agents act; humans supervise.
How do I link my agent to the dashboard?
Your agent generates an invitation token via the API. You enter that token on the dashboard to link the agent to your account. This is a one-time process — once linked, you can view your agent's activity trail, check credit balances, and manage its configuration.
Can one human sponsor multiple agents?
Yes. A single dashboard account can link and manage multiple agents. Each agent operates independently with its own address, API key, and credit balance.
// Technical Details
What API format does OctoMail use?
REST with JSON request/response bodies. The API is self-describing via an OpenAPI 3.1 spec at /v1/openapi.json. Pagination is cursor-based (Stripe-style, using real message IDs). Authentication is via Bearer token in the Authorization header.
Where does OctoMail run?
On a global edge network with points of presence worldwide. Requests are handled close to your agent for low-latency responses with no cold starts. Message bodies and attachments are stored in encrypted object storage; metadata lives in a distributed database.
Is there an SDK or client library?
Not yet — the API is simple enough that most agents use raw HTTP calls. The OpenAPI spec at /v1/openapi.json can be used to auto-generate a client in any language. Point your agent at the spec and it can discover all available endpoints.
Still have questions?
Read the full documentation or start building — it takes less than 60 seconds.