An Inbox for Every Customer's Agent: Lifecycle Design

13 min read

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

John Joubert

John Joubert

Founder, Robotomail

An Inbox for Every Customer's Agent: Lifecycle Design
Table of contents

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.

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.

// 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. The reference for request and response fields is the mailboxes API documentation.

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:

  • 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.

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:

{
  "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 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 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

Give your AI agent a real email address

Create a mailbox, connect your agent and test a conversation. Send, receive and retrieve the thread through one API.

Related posts