FAQ

Common questions about what Broodnet can and cannot do, and where the project is headed.

General

General questions about Broodnet’s purpose, design decisions, and how it compares to other email services.

What is Broodnet?

Broodnet is a managed email infrastructure service for AI agents. It gives each agent a real, dedicated email address backed by actual mail server infrastructure — not a forwarding alias or a shared inbox. Agents can receive mail from anywhere on the internet and send mail to addresses within the same organization.

It’s the difference between an email delivery API (which can send on your behalf but gives you no inbox) and a real mailbox service. Broodnet provides the full stack: inbound routing, storage, outbound delivery, and access via REST API, CLI, and MCP.

How is Broodnet different from SendGrid, Mailgun, or Postmark?

Those services are primarily outbound delivery APIs. They let you send transactional email — password resets, notifications, receipts — but they don’t give you a real mailbox or a way to receive replies.

Broodnet is the mailbox layer. You get a real address, inbound processing, and a persistent inbox your agents can query. It’s infrastructure, not a delivery service.

Do I need to run my own mail server?

No. That’s the point. Broodnet handles the mail server, DNS, DKIM/SPF/DMARC records, TLS, spam filtering, and storage. You provision a mailbox via the API or CLI and start using it.

Can I use my own domain for mailbox addresses?

Not yet. All mailboxes currently use a subdomain of broodnet.com derived from your organization (e.g. agent@relaxedgull.broodnet.com). Custom domain support is on the roadmap.

Can an AI agent create its own Broodnet account?

No, and this is intentional. Only humans can create Broodnet accounts. Agents also cannot provision their own mailboxes — a human account owner does that on their behalf via the API, CLI, or dashboard.

The reason: email is identity. Requiring a human to own the account and vouch for the agents in it is a core anti-abuse design decision. We do plan to allow agents to perform certain self-service operations in the future, but account creation will always require a human.

What’s the difference between an org API key and a mailbox token?

Broodnet has two distinct access scopes:

Credential	Prefix	Used for
Organization API key	`brn_...`	Provisioning mailboxes, managing org settings, inviting members
Mailbox token	`bnt_...`	Reading email, checking inbox, sending messages

An agent typically holds a mailbox token scoped to its own mailbox. This lets it read and send email without being able to create new mailboxes or touch organization settings. Management operations require an org API key, which you control.

See the Authentication guide for details.

Capabilities & Limitations

Information about what Broodnet can do today, what it cannot do, and what we plan to build in the future.

Can I send email to anyone on the internet from a Broodnet mailbox?

No. Outbound email from Broodnet mailboxes can only be delivered to addresses within the same organization — other agents in your org and the human members of that org. Sending to arbitrary external addresses is blocked.

This restriction is enforced at the mail server level, not just in the API. It applies to all interfaces (REST API, CLI, MCP, direct SMTP) and cannot be bypassed.

Why is outbound email restricted to the same organization?

We are emphatically anti-spam. We don’t want Broodnet to become a platform for cold email campaigns, unwanted marketing, or automated abuse. The outbound restriction is a hard constraint by design: agents can only send to their operator and sibling agents — the people and systems they were built to work with.

This isolation is what makes it possible to provide real email infrastructure for AI agents without contributing to the spam problem. We plan to add support for verified opt-in recipients in the future (similar to how newsletter platforms manage subscriber lists), but unrestricted outbound access is not on the roadmap.

Can I use any standard IMAP/SMTP client with a Broodnet mailbox?

Yes. Each mailbox is backed by a real IMAP/POP3/SMTP server. The mailbox token doubles as the IMAP password, so any standard email client (Thunderbird, Mutt, Apple Mail, etc.) can connect using the connection settings shown on the mailbox detail page.

The CLI provides a more convenient agent-oriented interface, but it’s just a wrapper around the same protocols and REST API.

What does “pending” or “failed” sync status mean?

When you provision a mailbox, it goes through two status dimensions:

Provisioning status (pending → active, or failed) — whether the mailbox record has been created and is operational
Sync status (pending → synced, or failed) — whether the mailbox has been synchronized with the mail server

Sync happens asynchronously after creation. A syncStatus: pending mailbox has been registered in Broodnet but the mail server hasn’t confirmed it yet. syncStatus: failed means the mail server sync encountered an error — the mailbox detail page will show the error, and you can retry.

A mailbox is fully ready to use when syncStatus is synced.

Does Broodnet store my email content?

Yes, in the sense that Broodnet operates the mail server that delivers and stores your email — that’s the service. Email is encrypted in transit and at rest. We do not read, analyze, or process the content of your messages beyond what is necessary to route and store them.

When a mailbox is deleted, all associated email is permanently deleted from our systems. We do not retain copies of message content after deletion. Access logs are retained for a limited period for debugging purposes but do not include message content.

Can I invite teammates to my organization?

Not yet. Multi-member organization support is on the roadmap. Currently, each organization has a single owner. Invitations and role-based access (owner/admin/member) are planned features.

Is Broodnet ready for production use?

Broodnet is in early stages. Core functionality — provisioning mailboxes, sending and receiving email via API and CLI — is working and tested. The fundamentals are solid, but the product is not yet feature-complete.

We welcome early adopters who can work with a service that is still being built. If you hit issues or have feedback, we want to hear from you. We are building in public and prioritizing reliability and correctness for the features that do exist before expanding scope.

Developer

Questions about using Broodnet programmatically, integrating with agent frameworks, and technical details of the API and infrastructure.

Can I use Broodnet for automated testing with real email addresses?

Yes, and this is one of the use cases we’re most excited about. You can provision mailboxes for test agents, run them through real email workflows (OTP verification, service notifications, reply handling), and delete the mailboxes when the test suite finishes. This enables realistic integration testing of email-dependent workflows without mocking or fake SMTP servers.

Is there an MCP server?

The MCP server is in active development and not yet released. When available, it will expose tools for checking inbox, reading messages, sending mail, and related agent operations — designed to be called natively from LLM agent frameworks.

The REST API is available now and provides the same capabilities programmatically. Management operations (provisioning mailboxes, managing org settings) will remain REST-only and are intentionally not exposed through the MCP interface.

Can I provision mailboxes programmatically at scale?

Yes. The REST API supports creating mailboxes in a loop — there are no artificial rate limits on provisioning for legitimate use. We trust that you’ll use this responsibly, consistent with the platform’s purpose (agent infrastructure, not mass account creation).

What happens to emails when a mailbox is deleted?

All email data associated with the mailbox is permanently deleted from the mail server when the mailbox is deleted. This is immediate and irreversible. We do not retain message content after deletion, and there is no recovery path. Export any messages you need before deleting a mailbox.

Technically yes — nothing prevents you from handing the same mailbox token to multiple agents. In practice we recommend against it. The mailbox token is the credential for the mailbox, so sharing it means sharing access. There’s also no way to attribute which agent read or sent a given message. Separate mailboxes per agent gives you better isolation, audit clarity, and the ability to revoke access per agent independently.

Will you support inbound webhooks (push instead of poll)?

Yes, this is on the roadmap. Currently, email retrieval is poll-based via the API and CLI. Webhook delivery — pushing a notification to your endpoint when new mail arrives — is a planned feature. We are building reliable polling first and will add push once the foundation is solid.

Can the outbound restriction ever be lifted for a specific mailbox?

We have no plans to offer unrestricted outbound access, for any account or mailbox. The restriction exists because we do not believe there is a responsible way to give AI agents arbitrary outbound access to the internet’s email infrastructure without contributing to spam and abuse.

What we do plan to build: opt-in verified recipient lists, similar to how newsletter platforms handle subscribers. A human operator would invite a recipient, the recipient explicitly accepts, and only then can messages be delivered to that address. This is the only outbound expansion we’re considering. Unrestricted outbound is not on the roadmap.

FAQ