Pods & Organizations

daimon.email uses a hierarchical tenancy model where accounts are the top-level organizational unit. Each account can manage multiple inboxes, webhooks, and billing settings through a single account API key.

Account Structure

Every daimon.email account follows this structure:

Account (acc_abc123)
├── Account API Key (dm_free_abc123...)
├── Inboxes
│   ├── platform-admin@daimon.email (inbox_api_key_1)
│   ├── agent-001@daimon.email (inbox_api_key_2)
│   └── support@daimon.email (inbox_api_key_3)
├── Webhooks
│   ├── webhook_1 (message.received)
│   └── webhook_2 (account.upgraded)
├── Billing
│   └── Stripe Subscription
└── Custom Domains (paid tier)
    └── agent.yourcompany.com

How Accounts Work

Single API Key

One account API key manages all inboxes, webhooks, and billing. Returned only on first inbox creation.

Unlimited Inboxes

Create as many inboxes as your tier allows. Free tier: 10 inboxes. Paid tiers: unlimited.

Centralized Billing

One Stripe subscription covers all inboxes under the account. No per-inbox charges.

Inbox-Scoped Keys

Each inbox gets its own API key that only accesses that inbox. Safe for agent distribution.

Account Creation

Accounts are created implicitly when you create your first inbox. The response includes both the account API key (returned only once) and the inbox API key (scoped to that inbox).

curl -X POST https://api.daimon.email/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{
    "username": "platform-admin",
    "client_id": "bootstrap-001"
  }'

import { DaimonClient } from 'daimon-email';

const client = new DaimonClient();

const result = await client.inboxes.create({
  username: 'platform-admin',
  clientId: 'bootstrap-001'
});

// Save the account API key securely
const accountApiKey = result.accountApiKey;
const inboxApiKey = result.inboxApiKey;

console.log(`Account: ${result.accountId}`);
console.log(`First inbox: ${result.email}`);

from daimon_email import DaimonClient

client = DaimonClient()

result = client.inboxes.create(
    username='platform-admin',
    client_id='bootstrap-001'
)

# Save the account API key securely
account_api_key = result.account_api_key
inbox_api_key = result.inbox_api_key

print(f"Account: {result.account_id}")
print(f"First inbox: {result.email}")

Response

{
  "result": {
    "id": "inbox_abc123",
    "account_id": "acc_xyz789",
    "username": "platform-admin",
    "email": "platform-admin@daimon.email",
    "inbox_api_key": "dm_free_inbox123...",
    "account_api_key": "dm_free_account456...",
    "tier": "free",
    "created_at": "2026-03-16T10:30:00Z"
  },
  "next_steps": [
    "Save account_api_key securely — it's only returned once",
    "Use account_api_key to create additional inboxes",
    "Use inbox_api_key to access this specific inbox"
  ]
}

Warning

The account API key is only returned during the first inbox creation. If you lose it, you'll need to contact support@daimon.email for recovery.

Managing Multiple Inboxes

Once you have an account API key, you can provision additional inboxes for agents, teams, or users.

Use the account API key

Authenticate subsequent inbox creation requests with the account API key (not the inbox API key).

Create additional inboxes

curl -X POST https://api.daimon.email/v1/inboxes \
  -H "Authorization: Bearer dm_free_account456..." \
  -H "Content-Type: application/json" \
  -d '{
    "username": "research-agent",
    "client_id": "agent-001"
  }'

Distribute inbox API keys

Each new inbox receives its own scoped API key. Distribute these to agents or services via environment variables.

View All Inboxes

List all inboxes under your account using the account API key:

curl -X GET https://api.daimon.email/v1/inboxes \
  -H "Authorization: Bearer dm_free_account456..."

const client = new DaimonClient({
  apiKey: accountApiKey
});

const inboxes = await client.inboxes.list();

console.log(`Total inboxes: ${inboxes.total}`);
inboxes.result.forEach(inbox => {
  console.log(`- ${inbox.email} (${inbox.id})`);
});

client = DaimonClient(api_key=account_api_key)

inboxes = client.inboxes.list()

print(f"Total inboxes: {inboxes.total}")
for inbox in inboxes.result:
    print(f"- {inbox.email} ({inbox.id})")

Response

{
  "result": {
    "inboxes": [
      {
        "id": "inbox_abc123",
        "email": "platform-admin@daimon.email",
        "status": "active",
        "created_at": "2026-03-16T10:30:00Z"
      },
      {
        "id": "inbox_def456",
        "email": "research-agent@daimon.email",
        "status": "active",
        "created_at": "2026-03-16T10:35:00Z"
      }
    ],
    "total": 2,
    "limit": 50,
    "offset": 0
  }
}

Future: Pods & Teams

Note

Coming in Sprint 3: Pods and teams will allow sub-grouping of inboxes within an account for better organization and access control.

Future features will include:

Pods: Logical groupings of inboxes (e.g., "Production Agents", "Development", "Customer Support")
Teams: Role-based access control within an account
Pod-scoped API keys: Keys that access all inboxes within a pod
Billing splits: Allocate costs by pod or team

Example future structure:

Account (acc_abc123)
├── Pod: Production Agents
│   ├── agent-001@daimon.email
│   ├── agent-002@daimon.email
│   └── pod_api_key (accesses all production agents)
├── Pod: Development
│   ├── dev-agent@daimon.email
│   └── pod_api_key (accesses all dev agents)
└── Pod: Customer Support
    ├── support@daimon.email
    └── billing@daimon.email

Multi-Tenant SaaS Pattern

If you're building a multi-tenant SaaS platform, you typically want one daimon.email account for your entire platform:

Your Platform (1 daimon.email account)
├── Customer A
│   ├── agent-1@daimon.email
│   ├── agent-2@daimon.email
│   └── support@daimon.email
├── Customer B
│   ├── agent-1@daimon.email
│   └── agent-2@daimon.email
└── Customer C
    └── agent-1@daimon.email

Why one account?

Centralized billing: One subscription covers all customers
Unified monitoring: View all activity across all customers
Cost efficiency: Pass-through pricing to your customers
Simplified management: One account API key to secure

Info

For enterprise customers who need isolated accounts (separate billing, compliance boundaries), contact sales@daimon.email for multi-account management.

Account Limits

Account limits vary by tier:

Tier	Max Inboxes	Sends/Day	Webhooks	Custom Domains
Free	10	0 (receive only)	Yes	No
Developer	Unlimited	1,000	Yes	5
Growth	Unlimited	10,000	Yes	Unlimited
Enterprise	Unlimited	Unlimited	Yes	Unlimited

Check your current usage:

curl -X GET https://api.daimon.email/v1/account \
  -H "Authorization: Bearer dm_free_account456..."

Response

{
  "result": {
    "account_id": "acc_xyz789",
    "tier": "free",
    "limits": {
      "max_inboxes": 10,
      "current_inboxes": 2,
      "max_sends_per_day": 0,
      "current_sends_today": 0,
      "webhooks_enabled": true,
      "custom_domains_enabled": false
    },
    "created_at": "2026-03-16T10:30:00Z"
  }
}

Security Best Practices

Account API Key

Store in secrets manager (AWS, Vault, etc.)
Never expose to agents or users
Rotate if compromised (contact support)
Use only in backend services

Inbox API Keys

Scoped to individual inboxes
Safe to distribute via environment variables
Can be rotated without affecting other inboxes
Limit blast radius if compromised

Next Steps

Scoped API Keys

Learn about inbox-scoped vs account-scoped API keys

Building on daimon

Platform patterns for provisioning hundreds of inboxes

Custom Domains

Use your own domain for agent inboxes (paid tier)

Pods & Organizations

Use the account API key

Create additional inboxes

Distribute inbox API keys

On this page