# An Inbox for Every Customer's Agent: Lifecycle Design

Published: November 18, 2026

Design repeat-safe provisioning for customer agent inboxes: mailbox boundaries, ID mapping, scoped credentials, reconciliation and deliberate retirement.

If you run agents on behalf of paying customers, provisioning an inbox for every customer's agent is not one API call. It is a lifecycle your application owns: reserve the identity, create the mailbox, store the mapping, issue a scoped credential, then retire all of it when the customer leaves. The single POST is the easy part. The hard parts are repeat-safe onboarding, reconciling a crash between "mailbox created" and "mapping saved", and making sure a departed customer's worker cannot still authenticate.

This post walks through that design using a fictional platform called RelayDesk, which runs enquiry-handling agents for businesses. Two fictional customers, Cedar and Harbor, each have a qualification agent. RelayDesk holds one Robotomail account containing many mailboxes. All code below is application-owned pseudocode that RelayDesk would write, not a Robotomail feature.

One thing to be clear about up front: Robotomail supplies the email infrastructure. It does not know who your customers are. Account ownership does not distinguish Cedar from Harbor, so every tenant boundary in this design is yours to enforce.

## Choose the mailbox boundary before you write any code

There are two sane shapes, and the choice drives everything downstream.

**One mailbox per customer.** Cedar gets `cedar@relaydesk.example`. Several agent roles (qualification, follow-up, scheduling) read and write through that single correspondence identity, and your application dispatches inbound mail to the right role based on thread state or content. Fewer mailboxes, one address for the customer to publish, one thread history.

**One mailbox per agent.** Cedar's qualification agent gets its own mailbox, separate from Cedar's follow-up agent. Separate addresses, separate thread histories, separate runtime credentials. This is the shape to pick when the agents represent distinguishable senders to the outside world, or when you want a compromised worker to be unable to read another role's mail.

| Consideration | One per customer | One per agent |
|---|---|---|
| Mailbox count | 1 per tenant | roles x tenants |
| Correspondence identity | shared | distinct per role |
| Thread history | merged | separated |
| Runtime credential scope | one key covers all roles | key per role |
| Routing work | your dispatcher decides the role | mailbox is the route |

Two honest limits. First, a shared customer inbox does not give each agent role its own access boundary. If three workers hold a credential for the same mailbox, all three can read everything in it. If that matters, you want separate mailboxes. Second, per-agent mailboxes multiply your mailbox count, which is a plan capacity question, not a free abstraction. We cover the arithmetic below.

Do not design around mail aliases or automatic per-tenant features. Build on what is actually there: mailboxes you create, list, pause and delete, plus credentials you scope to specific mailbox IDs.

## Model provisioning as explicit states

Replace "create mailbox on signup" with a state machine your database owns. RelayDesk uses:

1. **reserved** - the customer and agent record exists, the desired local part is chosen, no remote mailbox yet.
2. **provisioning** - a create call is in flight or being verified.
3. **active** - mailbox ID stored, credential issued, worker allowed to run.
4. **offboarding** - new jobs stopped, teardown in progress.
5. **retired** - credentials revoked, retention decision applied.
6. **needs_reconciliation** - the terminal state for "we are not sure what exists remotely". Nothing automatic runs against a row in this state; a human or a reconciliation job resolves it.

The row that carries this is small and boring:

```
customer_id         uuid
agent_id            uuid
mailbox_id          text    unique, nullable until created
mailbox_address     text
reserved_local_part text
domain_id           uuid    nullable
credential_ref      text    pointer into your secret store
lifecycle_state     enum
unique (customer_id, agent_id)
```

Separately, keep your conversation and run mappings keyed by `mailbox_id` and `thread_id`, so an inbound webhook payload resolves to exactly one tenant and one agent run.

Two rules that prevent most multi-tenant incidents:

- Authorize the customer before any mailbox operation. Resolve the tenant from the authenticated session, then look up the mapping. Never accept a mailbox ID supplied by a browser as proof of ownership.
- Keep Bearer API keys server-side. Provisioning is a trusted platform service. Runtime workers receive only their own scoped credential, never the full-access key.

## Create the mailbox and capture the identifiers

The provisioning service calls the mailbox create endpoint with the reserved address. Omit `domainId` for a platform-domain mailbox; include that domain's UUID when the mailbox belongs to a verified custom domain.

```bash
curl -X POST https://api.robotomail.com/v1/mailboxes \
  -H "Authorization: Bearer rm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"address": "cedar-qualify"}'
```

Responses are camelCase. Capture the mailbox ID and the full address from the response and store both. The full address is what Cedar publishes; the mailbox ID is what every later operation and every inbound webhook is keyed on.

The onboarding entry point must be idempotent at your layer, because retries are normal. A customer double-clicks, a job runner redelivers, a deploy restarts mid-request.

```ts
// Application-owned pseudocode. RelayDesk's provisioning service.
async function ensureAgentMailbox(customerId: string, agentId: string) {
  return db.transaction(async (tx) => {
    // Lock the (customer, agent) row so competing requests serialise.
    const row = await tx.selectForUpdate("agent_mailboxes", { customerId, agentId });

    if (row?.lifecycleState === "active") return row;            // repeat onboarding
    if (row?.lifecycleState === "needs_reconciliation") throw new HoldForReview(row);

    const localPart = row?.reservedLocalPart ?? makeLocalPart(customerId, agentId);
    await tx.upsert("agent_mailboxes", {
      customerId, agentId, reservedLocalPart: localPart, lifecycleState: "provisioning",
    });

    const created = await robotomail.createMailbox({ address: localPart });

    await tx.update("agent_mailboxes", { customerId, agentId }, {
      mailboxId: created.mailbox.id,
      mailboxAddress: created.mailbox.fullAddress,
      lifecycleState: "active",
    });

    return tx.select("agent_mailboxes", { customerId, agentId });
  });
}
```

Note what this does on a repeat: it looks up your mapping first and returns the existing association. It does not try to create a second mailbox and hope for a tidy error. If you drive onboarding from a queue, add a unique operation key per onboarding attempt so two workers cannot both enter the create path.

For general background on creating mail accounts by API outside a tenant context, see our notes on [automated email account creation](/blog/automated-email-account-creation-api-programmatic). The reference for request and response fields is the [mailboxes API documentation](/docs/api/mailboxes).

## Reconcile the gap between remote creation and your local write

There is a window you cannot remove with a database constraint: Robotomail accepts the create call, then your process dies before the mapping is saved. A local unique constraint protects your table. It does nothing about an orphan mailbox that now exists remotely.

Handle it explicitly:

1. On the next attempt, your row is still in `provisioning`. Do not blindly create again.
2. List mailboxes under the trusted account and look for the reserved full address. If it exists, adopt it: write the returned ID into the mapping and move to `active`.
3. If the create call returns a conflict, treat that as a conflict to investigate, not permission to use an unknown mailbox. Resolve the address through the list, confirm it is not already mapped to another `(customer_id, agent_id)`, then either adopt or move the row to `needs_reconciliation`.
4. If you cannot establish a one-to-one mapping, stop. `needs_reconciliation` with an alert beats guessing.

There is no cross-service transaction here and no client-supplied idempotency key to lean on. The reconcile step is yours, and it is short, so write it on day one rather than after your first partial outage.

## Issue runtime credentials scoped to one customer

Workers should never hold your full-access key. Create a scoped API key whose mailbox list contains only the mailboxes that belong to that customer and agent, validated against your mapping before the call. Build the list from your database, never from a request parameter.

Operational details worth knowing before you build the flow, documented in the [API keys reference](/docs/api/api-keys):

- The raw key value is returned once. Write it straight to your secret store and persist only the pointer, the key prefix and an application label such as `relaydesk:cedar:qualify`.
- Key creation does not hand you a key ID you can file away for later deletion. To revoke, list keys and resolve the ID from the prefix and label you stored. Store enough metadata at issue time to make that lookup unambiguous.
- Persist `active` and the credential reference before you enable the worker. A worker that starts before the mapping is durable will produce mail you cannot attribute.

Readiness is operational, not instant. After provisioning, have the platform run a short check: confirm the mailbox resolves, send one test message from the mailbox, and verify the inbound webhook delivers a `message.received` payload you can map back to the right tenant. API acceptance of a send means the request was accepted, not that mail reached the recipient's inbox.

```bash
curl -X POST https://api.robotomail.com/v1/mailboxes/mbx_cedar_qualify/messages \
  -H "Authorization: Bearer rm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"to": ["ops@relaydesk.example"], "subject": "Provisioning check", "bodyText": "Cedar qualification agent is live."}'
```

Inbound arrives at your registered webhook with snake_case data fields, which is what your dispatcher keys on:

```json
{
  "event": "message.received",
  "data": {
    "message_id": "...", "mailbox_id": "...", "mailbox_address": "cedar-qualify@relaydesk.example",
    "from": "buyer@example.com", "subject": "Re: Enquiry", "body_text": "...",
    "thread_id": "...", "received_at": "2026-04-17T10:00:00.000Z"
  }
}
```

Resolve `mailbox_id` to exactly one `(customer_id, agent_id)`. If it resolves to nothing, you have an orphan or a stale mapping, which is a reconciliation signal, not a message to process.

If customers correspond under your own domain, verify the domain once and pass its UUID as `domainId` when creating tenant mailboxes. The [custom domain guide](/docs/guides/custom-domain) covers the verification steps and the DNS records involved.

## Retire an inbox on purpose, in order

Harbor churns. Cedar stays. Nothing about Cedar should change.

1. **Stop new platform jobs.** Mark the mapping `offboarding` first so no scheduler enqueues another run.
2. **Revoke runtime credentials.** List keys, resolve the IDs for Harbor's labels, delete them with your full-access credential. This is the step that actually ends access.
3. **Stop the webhook** that was feeding Harbor's mailbox into your dispatcher, so late inbound mail does not start runs for a departed tenant.
4. **Decide retention.** Open threads, attachments and transcripts may be subject to a contractual export or deletion promise. Make that decision before you touch the mailbox.
5. **Optionally pause.** Updating a mailbox status to `PAUSED` is a reversible operational control. It is not credential revocation and not deletion. Never leave a paused tenant holding a runtime key that could flip its own mailbox back on, which is exactly why step 2 comes before this one.
6. **Delete only when you mean it.** Explicit mailbox deletion requires full access and removes message, thread and attachment data. Then set the row to `retired`.

And the obvious one: do not delete the shared Robotomail account because one customer left. Cedar lives in the same account.

## Four scenarios and the states they should produce

| Scenario | Correct behaviour | End state |
|---|---|---|
| Customer submits onboarding twice | Lookup on `(customer_id, agent_id)` returns the existing association, no second create | `active`, one mailbox |
| Crash after remote creation, before local write | Next attempt finds `provisioning`, lists mailboxes, adopts the reserved address | `active`, or `needs_reconciliation` if ambiguous |
| Mailbox quota exhausted mid-onboarding | Create fails, row stays `reserved` or `provisioning`, customer sees a clear pending state, operator upgrades capacity and replays | `active` after replay |
| One customer departs, another stays | Jobs stopped, keys revoked, webhook stopped, retention applied, only that tenant's mailboxes touched | departed `retired`, other `active` |

An application-owned reconciliation job that runs nightly is enough to keep this honest. For every remote mailbox, assert exactly one mapping row. For every row in `active`, assert the mailbox exists and at least one unexpired credential reference resolves. For every row in `retired`, assert no live keys carry its label. Anything that fails goes to `needs_reconciliation` and alerts rather than self-healing.

## Capacity math before you promise an inbox for every customer's agent

Mailbox count is usually the binding constraint, not send volume. Work it out with real numbers before you price the product.

Eight customers with two role mailboxes each is 16 mailboxes. Add your signup mailbox and any test or operations mailbox and you are at 17 or 18. Starter, at $19 per month, allows 10 total mailboxes, so this does not fit even if every agent sends two emails a week. Growth, at $79 per month, allows 50 mailboxes and five custom domains, which covers the mailbox count, but you still have to check the other dimensions.

The limits that catch platform teams out:

- **Shared inbound.** Inbound allowance is counted across the account, not per mailbox: 2,000 inbound per month on Starter, 20,000 on Growth. Ten busy tenants can consume it while a mailbox count looks comfortable.
- **Daily and per-mailbox sending.** Starter allows 500 sends per day and 15,000 per month per mailbox. Growth allows 1,000 sends per day per mailbox and has no monthly send cap, but daily and rate limits still apply.
- **Custom domains.** If every customer wants its own sending domain, the domain count, not the mailbox count, decides your plan.
- **Pausing does not free a slot.** Create quota counts existing mailboxes, so a paused tenant still occupies one. If you need the slot back, delete deliberately after your retention decision.
- **Testing.** The restricted starter experience exchanges mail only with the verified owner address, with 10 sends and 10 receives per calendar month. It is fine for a provisioning smoke test. External customer correspondence and custom domains need a paid plan. (Solo, at $5 per month, is a single-mailbox plan and is not a multi-tenant shape.)

Also budget storage, your model and hosting costs, and your own support load per tenant. Mailboxes are not unlimited tenants, and none of these figures are a cost-per-customer guarantee. Check [current pricing](/pricing) for the terms that apply when you sign.

## FAQ

### Should I provision one mailbox per customer or one per agent?

One per customer when several roles can share a single correspondence identity and your application dispatches inbound mail to the right role. One per agent when the roles should look like distinct senders, keep separate thread histories, or need separate runtime credentials. Per-agent costs more mailboxes; shared costs you the access boundary between roles.

### Does Robotomail know which of my customers owns a mailbox?

No. One account can hold many mailboxes, and account ownership does not distinguish your tenants. The `(customer_id, agent_id, mailbox_id)` mapping, the authorization check before every operation and the scoped credential per worker all live in your application.

### What should happen when a customer retries onboarding?

Your handler should look up the existing association and return it. Lock the row or use a unique operation key so two concurrent requests cannot both reach the create path. If the row is stuck in `provisioning`, reconcile the reserved address against the account's mailbox list before creating anything
