Skip to main content

Inboxes

An inbox in mailbot is the unit of isolation, identity, and addressability for email. Every email mailbot sends or receives belongs to exactly one inbox.

Inbox vs email address​

A plain email address is a routing label. An inbox in mailbot is the routing label plus everything attached to it:

  • the address itself (support@yourdomain.com or a sandbox address on mailbot.id)
  • the API and dashboard handle to send and read mail through that address
  • the message history, threads, and engagement events tied to that address
  • per-inbox limits and policy (daily send cap, allowed labels, sandbox vs custom domain)
  • the webhook destinations that fire for messages on that address

Two inboxes never share state. Sending from inbox A never appears in the message list of inbox B. This is what isolation means in practice.

Sandbox inboxes vs custom-domain inboxes​

mailbot has two kinds of inboxes. They behave the same to your code, but they have different limits and trust profiles.

Sandbox inbox​

  • address pattern: {username}--{accountShortId}@mailbot.id
  • DNS, SPF, DKIM are managed by mailbot
  • daily send limit: fixed at 250 per inbox, with a 25/min burst guard
  • intended for: first success, prototypes, beta testing, internal automation that does not need branded sender identity

Custom-domain inbox​

  • address pattern: anything@yourdomain.com once yourdomain.com is verified
  • you control DNS; mailbot publishes the records you must add
  • daily send limit: matches the account daily send limit (e.g. 25,000 on enterprise) once the account plan is set correctly
  • intended for: production, customer-facing sender identity, branded outbound

When you onboard, the first inbox provisioned is a sandbox inbox. Custom-domain inboxes come later, when the domain passes the compliance check.

Lifecycle​

An inbox moves through a small number of states:

  1. created — the inbox exists in mailbot, addressable, and ready to send and receive.
  2. active — same as created. The dashboard treats them as one state.
  3. disabled — the inbox is soft-deleted. It can no longer send or receive. Audit trail is preserved.

There is no hard delete from the API. Disabled inboxes keep their history so audit and compliance review remain possible.

What lives on an inbox​

Every inbox carries:

  • address — the email address itself
  • labels — your own tags (outreach, support, ops, etc.) used for filtering and grouping
  • threads — see Threads
  • messages — both directions, plus delivery and engagement state
  • events — sent, delivered, opened, clicked, bounced, received, parsed
  • webhook destinations — where event notifications fire

When you call GET /v1/inboxes/:id, you get the inbox row plus its current usage and limit state. When you call GET /v1/inboxes/:id/messages, you get its message history scoped to that inbox.

Why this model​

mailbot separates inboxes for three reasons:

  1. Reasoning — an AI agent that owns an inbox can reason about its own state without seeing other inboxes' state.
  2. Reputation — sender reputation is per-address. Isolation per inbox makes it possible to suspend one address without affecting others on the same account.
  3. Operations — limit enforcement, replay, audit, and webhook scope all become predictable when the boundary is the inbox.