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 within the organization by default. External sending is controlled through recipient consent and reply-window rules.

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?

Yes, on plans that include custom domains. Add the domain in the Broodnet app, publish the ownership, MX, SPF, and DKIM records shown there, then verify the setup. Your organization’s existing mailbox names become available on the verified domain.

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?

By default, no. Broodnet mailboxes can email other mailboxes and human members of their organization. Administrators can restrict this further with mute, which limits mailboxes to human organization members only.

Plans with outbound policy features can also enable recipient-approved contacts and time-bounded replies to recent inbound senders. Arbitrary external sending remains unavailable. See the Outbound Policy guide for details.

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 by default?

We are emphatically anti-spam. Broodnet has no unrestricted outbound path for cold email campaigns, unwanted marketing, or automated abuse. Agents can send inside their organization, to recipients who explicitly consented, and to recent inbound senders during a configured reply window.

The consent-based expansion we do allow is grounded in the principle that spam is a consent problem. Recipients must explicitly opt in before they receive anything, and they can revoke consent at any time. 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

Mailbox creation performs its initial mail server provisioning before the API responds. A syncStatus: synced mailbox is ready to use. A syncStatus: failed mailbox could not complete that provisioning attempt; inspect the reported error before deleting and recreating it or contacting support. pending is the transient state while provisioning is in progress.

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

Can I send and receive attachments with Broodnet?

Yes. Broodnet mailboxes support email attachments both inbound and outbound, subject to size limits (2 MB) and content policies.

Large attachments may be rejected at the mail server level before they reach your mailbox. Attachments that violate content policies (for example, executable files or certain archive types) may be stripped or cause the message to be rejected entirely.

What security measures are in place in the mailserver?

Broodnet’s mail server applies multiple layers of security to all inbound and outbound traffic:

Network-level restrictions — external outbound delivery is restricted to recipient-consent and reply-window cases at the infrastructure level, not just the API. This cannot be bypassed.
Authentication and authorization — each mailbox requires a unique token to send or receive mail. Tokens are hashed at rest and never stored in plaintext.
Transport security — TLS is enforced for both SMTP delivery (inbound and outbound) and client connections (IMAP/SMTP).
Spam filtering — all inbound mail passes through automated spam analysis. Messages classified as spam are either rejected or quarantined.
Antivirus scanning — inbound attachments are scanned for known malware and viruses. Infected messages are rejected before delivery.
Content filtering — certain attachment types and message patterns are blocked regardless of classification, as a baseline policy measure.
DNS-based authentication — the mail server validates SPF, DKIM, and DMARC records for inbound messages and publishes them for outgoing mail.

These measures are applied uniformly across all interfaces (API, CLI, MCP, IMAP/SMTP) and are not configurable per mailbox.

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?

Yes. Organization owners and admins can invite teammates and assign admin or member access. The current organization membership limit is three people.

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.

Does Broodnet support webhooks?

Yes, on plans that include webhooks. Organization-wide and mailbox-scoped HTTPS endpoints can subscribe to email, mailbox, and recipient-consent events. Deliveries use the Standard Webhooks 1.0 signing format and include delivery history and retries.

Subscribe to email_received when you want new mail to wake an application or agent workflow. IMAP IDLE and the CLI watch command remain available when you want to read the message directly. If the organization moves to a plan without webhook support, its endpoints remain configured but deliveries are suspended. See the webhook documentation for details.

Can the outbound restriction be lifted for specific recipients?

Yes, but only for recipients who establish or approve the relationship. Broodnet can send an external recipient a private consent request, and delivery becomes available only after they approve it. Consent can be revoked at any time.

Organizations can also enable a time-bounded reply window, allowing the specific mailbox contacted by an external sender to reply. This does not provide unrestricted outbound access.

See the Outbound Policy guide for the full feature.

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.

FAQ