Multi-tenant apps with pods

If you build a product where each of your customers gets agents with email, keep every customer in its own pod. A pod is a partition of your organization. A key scoped to a pod sees only that pod; everything outside it returns 404, as if it did not exist.

The pattern:

1. One pod per end customer, created idempotently with your customer ID.
2. One pod-scoped API key per customer, used by that customer’s agents.
3. Inboxes, domains, webhooks and lists created inside the pod.

See Organizations and pods for the model.

1. Create a pod per customer

   Use your own customer ID as client_id. Repeating the call returns the existing pod with status 200, so it is safe in a provisioning job that may retry.

   curl https://api.machinemail.dev/v0/pods \
     -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"name": "Acme Corp", "client_id": "customer-acme"}'

   {
     "pod_id": "pod_01m4fy8hme0000t818y6dwskk4",
     "organization_id": "org_01m4fy8h140000efvagszh6rpx",
     "name": "Acme Corp",
     "is_default": false,
     "client_id": "customer-acme",
     "created_at": "2026-10-09T09:00:16.398Z",
     "updated_at": "2026-10-09T09:00:16.398Z"
   }

   Only organization-scoped keys can create pods. Store pod_id next to your customer record.

2. Mint a pod-scoped key

   Post to the pod’s api-keys route. The route decides the new key’s scope.

   curl https://api.machinemail.dev/v0/pods/pod_01m4fy8hme0000t818y6dwskk4/api-keys \
     -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "acme agents",
       "permissions": {
         "inbox_read": true, "inbox_create": true,
         "thread_read": true, "message_read": true, "message_send": true, "message_reply": true, "message_update": true,
         "draft_read": true, "draft_create": true, "draft_send": true
       }
     }'

   {
     "api_key_id": "key_01m4fybrtv00002j91wz7t063q",
     "api_key": "mm_live_YMv8qCK30MZxVwA0ltPMdTrB4eD7zknX",
     "prefix": "mm_live_YMv8",
     "name": "acme agents",
     "pod_id": "pod_01m4fy8hme0000t818y6dwskk4",
     "permissions": {
       "inbox_read": true,
       "inbox_create": true,
       "thread_read": true,
       "message_read": true,
       "message_send": true,
       "message_reply": true,
       "message_update": true,
       "draft_read": true,
       "draft_create": true,
       "draft_send": true
     },
     "created_at": "2026-10-09T09:02:02.011Z"
   }

   api_key is shown once; store it encrypted. Leave out permissions for a key with full access inside the pod. Rules for minting:

   • Only organization-scoped keys can create keys. A pod key cannot mint more keys.
   • A key with restricted permissions can only mint keys with a subset of its own permissions, never an unrestricted one.
   • expires_at (ISO 8601) makes the key stop working at that time. DELETE /v0/pods/{pod_id}/api-keys/{api_key_id} revokes it immediately.

   See API keys for every permission.

3. Create the customer’s inboxes

   Either use your organization key with pod_id:

   curl https://api.machinemail.dev/v0/inboxes \
     -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"username": "acme-support", "pod_id": "pod_01m4fy8hme0000t818y6dwskk4", "client_id": "customer-acme/support"}'

   or call with the pod key, which always creates inboxes in its own pod:

   curl https://api.machinemail.dev/v0/inboxes \
     -H "Authorization: Bearer $ACME_POD_KEY" \
     -H "Content-Type: application/json" \
     -d '{"username": "acme-support"}'

   Inbox addresses are global. On the shared domain, two customers cannot both have support@machinemail.dev, so prefix usernames with something customer-specific, or give each customer a custom domain (next step).

4. Give the customer a domain (optional)

   Add the customer’s domain with their pod key, or with the organization key on the pod route. The domain belongs to the pod, and catch-all inboxes on it are created in that pod.

   curl https://api.machinemail.dev/v0/pods/pod_01m4fy8hme0000t818y6dwskk4/domains \
     -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"domain": "agents.acme.dev", "catch_all": true}'

   Then follow Use a custom domain to publish and verify the records.

Pod-nested routes

Every resource route also exists under /v0/pods/{pod_id}. With an organization key, the prefix narrows the request to that pod, so your backend can act for one customer without holding their key:

A pod key can use these routes for its own pod or the plain /v0/... routes; both give the same results. A pod key that names another pod gets 404.

Per-customer webhooks and events

You have two options for routing events to customers.

One webhook per pod. Create the webhook with the pod key, or on /v0/pods/{pod_id}/webhooks. It gets pod_id set and only fires for that pod’s events. Use this when each customer has their own endpoint.

One webhook for everything. Create one organization webhook and route by the pod_id or inbox_id in the payload. To limit it to some pods, pass pod_ids on create, and change the set later with add_pod_ids and remove_pod_ids on PATCH /v0/webhooks/{webhook_id}.

curl https://api.machinemail.dev/v0/webhooks \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/hooks/machinemail", "event_types": ["message.received"], "pod_ids": ["pod_01m4fy8hme0000t818y6dwskk4"]}'

For streams, a pod key only ever streams its own pod. With an organization key, filter with ?pod_id= on GET /v0/events/stream or pod_ids in a WebSocket subscribe message. See Realtime events.

Per-customer lists

Allow and block lists exist at three levels, and all of them apply to an inbox: organization-wide, the inbox’s pod, and the inbox itself. Put a customer’s rules on their pod:

curl https://api.machinemail.dev/v0/pods/pod_01m4fy8hme0000t818y6dwskk4/lists/receive/allow \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entry": "acme.dev", "reason": "Only accept mail from the customer domain"}'

This switches the pod to allow-only: its inboxes now take mail only from acme.dev, and every other sender is labelled BLOCKED and withheld from agents. An allow-listed sender reaches verified only with an aligned DMARC pass. See Lists and suppressions.

One agent, one inbox

To give a single agent the narrowest possible credential, mint an inbox-scoped key:

curl https://api.machinemail.dev/v0/inboxes/acme-support@machinemail.dev/api-keys \
  -H "Authorization: Bearer $MACHINEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme support agent", "permissions": {"message_read": true, "thread_read": true, "message_reply": true}}'

An inbox key reaches only that inbox. It cannot create inboxes or delete its own. This is a good fit for a key you hand to an LLM tool or put in a browser.

Offboarding a customer

Delete the pod’s inboxes (which purges their mail), domains and webhooks, revoke its keys, then delete the pod. Deleting a pod that still has inboxes returns 409 conflict:

{
  "error": {
    "type": "conflict",
    "message": "Pod still has inboxes; delete them first"
  }
}

Every organization has a default pod (is_default: true) that holds resources created without a pod. It cannot be deleted.

Related