daimon.email
Tenancy

Building on daimon.email

How platform partners provision email for all their agents and users with a single API key

Building on daimon.email

daimon.email is designed for platform partners who need to provision email infrastructure for hundreds or thousands of AI agents and users. Whether you're building a multi-agent platform, an AI IDE, or a workflow automation tool, you can centralize email provisioning, billing, and monitoring through a single account.

Two Integration Patterns

Pattern A: Single Agent

One agent, one inbox, one API key. Perfect for individual developers or standalone agents.

Pattern B: Platform

One account API key, provision thousands of inboxes for agents/users. Centralized billing and monitoring.

Pattern A: Single Agent

If you're building a single autonomous agent that needs its own email address:

Create an inbox

curl -X POST https://api.daimon.email/v1/inboxes \
  -H "Content-Type: application/json" \
  -d '{"username": "my-agent"}'

Use the inbox API key

The response includes a scoped API key for that inbox. Use it to fetch messages, send emails, and manage the inbox.

Poll or webhook

Poll GET /v1/inboxes/{id}/messages or set up a webhook for real-time notifications.

Note

This pattern is great for prototyping or single-agent use cases, but doesn't scale well for platforms managing many agents.


If you're building a platform that manages multiple agents or users, this is the pattern for you.

How It Works

Bootstrap your platform account

Create your first inbox to establish a daimon.email account. This inbox can be your platform's "support" or "admin" inbox.

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

Response:

{
  "result": {
    "id": "inbox_abc123",
    "username": "platform-admin",
    "email": "platform-admin@daimon.email",
    "inbox_api_key": "dm_free_...",
    "account_api_key": "dm_free_abc123xyz...",
    "view_url": "https://daimon.email/inbox/inbox_abc123",
    "created_at": "2026-03-16T10:30:00Z"
  },
  "next_steps": [
    "Save the account_api_key securely — use it to provision all future inboxes",
    "Use inbox_api_key to access this specific inbox",
    "Create additional inboxes with POST /v1/inboxes using account_api_key"
  ]
}

Save your account API key

The account_api_key is returned only once during the first inbox creation. Store it securely in your platform's secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault, or environment variables).

Warning

Important: The account_api_key is scoped to your entire daimon.email account. Anyone with this key can create inboxes, view billing, and manage all resources under your account. Treat it like a root password.

Provision inboxes for agents/users

Now use the account API key to create inboxes for each agent or user in your platform:

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

Response:

{
  "result": {
    "id": "inbox_def456",
    "username": "agent-slug-001",
    "email": "agent-slug-001@daimon.email",
    "inbox_api_key": "dm_free_def456...",
    "view_url": "https://daimon.email/inbox/inbox_def456",
    "created_at": "2026-03-16T10:35:00Z"
  },
  "next_steps": [
    "Save the inbox_api_key for agent-slug-001",
    "Share this inbox's email address with the agent",
    "Poll GET /v1/inboxes/inbox_def456/messages or set up webhooks"
  ]
}

Note

Notice that the account API key is NOT returned in subsequent inbox creation responses — only the first time. Each new inbox gets its own scoped inbox_api_key.

Distribute scoped API keys to agents

Each inbox has its own inbox_api_key that is scoped to that specific inbox. Your platform should:

  • Store the mapping: agent_id → inbox_api_key
  • Provide the scoped key to each agent via secure environment variables or configuration
  • Never expose the account API key to individual agents

Key Benefits

Centralized Billing

One Stripe subscription covers all inboxes. No per-agent billing complexity.

Unified Monitoring

View all inboxes, threads, and messages from a single account dashboard.

Scoped Security

Each agent only accesses its own inbox via a scoped API key. Account-level key stays with your platform backend.

Idempotent Provisioning

Use client_id to ensure idempotent inbox creation. Safe to retry failed requests.


Agent Polling Pattern

Once an inbox is provisioned, your agents can poll for new messages or set up webhooks for real-time delivery.

Polling

Each agent polls its own inbox using the scoped inbox_api_key:

// Agent code: poll for new messages every 30 seconds
async function pollMessages(inboxId, apiKey) {
  const response = await fetch(
    `https://api.daimon.email/v1/inboxes/${inboxId}/messages?sort=desc&limit=10`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  const data = await response.json();

  for (const message of data.result.messages) {
    if (!message.read) {
      await processMessage(message);
      await markAsRead(inboxId, message.id, apiKey);
    }
  }
}

setInterval(() => pollMessages('inbox_def456', 'dm_free_def456...'), 30000);

Webhooks (Real-Time)

For real-time delivery, set up a webhook endpoint and register it with daimon.email:

curl -X POST https://api.daimon.email/v1/webhooks \
  -H "Authorization: Bearer dm_free_abc123xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-platform.com/webhooks/daimon",
    "events": ["message.received"],
    "inbox_id": "inbox_def456"
  }'

Info

Webhooks are available on Developer tier and above ($9/mo). Free tier is limited to polling.

Your webhook endpoint receives a POST request for each new message:

{
  "event": "message.received",
  "inbox_id": "inbox_def456",
  "message": {
    "id": "msg_xyz789",
    "from": "user@example.com",
    "to": ["agent-slug-001@daimon.email"],
    "subject": "Request for analysis",
    "body": "Please analyze this data...",
    "received_at": "2026-03-16T10:40:00Z"
  }
}

Centralized Dashboard

As a platform operator, you can monitor all inboxes and threads from a single account:

View All Inboxes

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

Response:

{
  "result": {
    "inboxes": [
      {
        "id": "inbox_abc123",
        "username": "platform-admin",
        "email": "platform-admin@daimon.email",
        "created_at": "2026-03-16T10:30:00Z"
      },
      {
        "id": "inbox_def456",
        "username": "agent-slug-001",
        "email": "agent-slug-001@daimon.email",
        "created_at": "2026-03-16T10:35:00Z"
      }
    ],
    "total": 2
  }
}

View All Threads (Cross-Inbox)

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

Response:

{
  "result": {
    "threads": [
      {
        "id": "thread_001",
        "inbox_id": "inbox_def456",
        "subject": "Request for analysis",
        "participants": ["user@example.com", "agent-slug-001@daimon.email"],
        "message_count": 3,
        "last_message_at": "2026-03-16T10:45:00Z"
      }
    ],
    "total": 1
  }
}

Note

Filter threads by inbox: GET /v1/threads?inbox_id=inbox_def456

View Account Limits and Billing

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

Response:

{
  "result": {
    "account_id": "acc_abc123",
    "tier": "free",
    "limits": {
      "max_inboxes": 10,
      "current_inboxes": 2,
      "max_sends_per_day": 0,
      "current_sends_today": 0,
      "webhooks_enabled": false,
      "custom_domains_enabled": false
    },
    "billing": {
      "stripe_customer_id": null,
      "subscription_status": "free"
    }
  }
}

Billing and Tiers

daimon.email offers multiple tiers for platform partners:

TierPriceInboxesSends/DayWebhooksCustom Domains
Free$0100 (receive only)NoNo
Developer$9/moUnlimited1,000YesYes
Growth$49/moUnlimited10,000YesYes
EnterpriseCustomUnlimitedUnlimitedYesYes + SLA

Upgrade Flow

When an agent tries to send an email on the free tier, the API returns:

{
  "error": "SEND_REQUIRES_PAID",
  "upgrade_context": {
    "operator_action_url": "https://daimon.email/upgrade?token=<jwt>",
    "operator_action_label": "Add a payment method to enable sending",
    "agent_script": "Tell your operator: I need sending access. Here's a direct upgrade link: {url}"
  }
}

Your platform can either:

  1. Auto-upgrade: Programmatically upgrade the account via POST /v1/account/upgrade with a Stripe payment method
  2. Manual upgrade: Direct the account owner to the upgrade URL

Info

For enterprise pricing (volume discounts, custom SLA, dedicated support), contact sales@daimon.email.


Full Code Example

Here's a complete example of a platform provisioning 3 agent inboxes and setting up webhooks:

import fetch from 'node-fetch';

const DAIMON_API_BASE = 'https://api.daimon.email/v1';

interface DaimonInbox {
  id: string;
  email: string;
  inbox_api_key: string;
  account_api_key?: string;
}

async function bootstrapPlatform(): Promise<string> {
  // Step 1: Create the first inbox to get account API key
  const response = await fetch(`${DAIMON_API_BASE}/inboxes`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'platform-admin',
      client_id: 'bootstrap-001'
    })
  });

  const data = await response.json();
  const accountApiKey = data.result.account_api_key;

  console.log('✅ Platform account created');
  console.log(`📧 Admin inbox: ${data.result.email}`);
  console.log(`🔑 Account API key: ${accountApiKey.slice(0, 20)}...`);

  // Store this securely in your platform's secrets manager
  return accountApiKey;
}

async function provisionAgentInbox(
  accountApiKey: string,
  agentSlug: string,
  clientId: string
): Promise<DaimonInbox> {
  const response = await fetch(`${DAIMON_API_BASE}/inboxes`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accountApiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      username: agentSlug,
      client_id: clientId
    })
  });

  const data = await response.json();

  console.log(`✅ Created inbox for ${agentSlug}`);
  console.log(`   📧 ${data.result.email}`);
  console.log(`   🔑 ${data.result.inbox_api_key.slice(0, 20)}...`);

  return {
    id: data.result.id,
    email: data.result.email,
    inbox_api_key: data.result.inbox_api_key
  };
}

async function setupWebhook(
  accountApiKey: string,
  webhookUrl: string,
  inboxId?: string
) {
  const response = await fetch(`${DAIMON_API_BASE}/webhooks`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accountApiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: webhookUrl,
      events: ['message.received'],
      inbox_id: inboxId // Optional: filter to specific inbox
    })
  });

  const data = await response.json();
  console.log(`✅ Webhook configured: ${webhookUrl}`);

  return data.result;
}

async function main() {
  // Bootstrap platform
  const accountApiKey = await bootstrapPlatform();

  // Provision 3 agent inboxes
  const agents = [
    { slug: 'research-agent', id: 'agent-001' },
    { slug: 'support-agent', id: 'agent-002' },
    { slug: 'analytics-agent', id: 'agent-003' }
  ];

  const inboxes: DaimonInbox[] = [];

  for (const agent of agents) {
    const inbox = await provisionAgentInbox(
      accountApiKey,
      agent.slug,
      agent.id
    );
    inboxes.push(inbox);
  }

  // Set up webhook for all inboxes
  await setupWebhook(
    accountApiKey,
    'https://your-platform.com/webhooks/daimon'
  );

  console.log('\n🎉 Platform provisioning complete!');
  console.log(`   Total inboxes: ${inboxes.length + 1}`);
  console.log(`   Webhook: active`);
}

main().catch(console.error);
import requests

DAIMON_API_BASE = 'https://api.daimon.email/v1'

def bootstrap_platform():
    """Create the first inbox to get account API key."""
    response = requests.post(
        f'{DAIMON_API_BASE}/inboxes',
        json={
            'username': 'platform-admin',
            'client_id': 'bootstrap-001'
        }
    )

    data = response.json()
    account_api_key = data['result']['account_api_key']

    print('✅ Platform account created')
    print(f"📧 Admin inbox: {data['result']['email']}")
    print(f"🔑 Account API key: {account_api_key[:20]}...")

    return account_api_key

def provision_agent_inbox(account_api_key, agent_slug, client_id):
    """Provision an inbox for a specific agent."""
    response = requests.post(
        f'{DAIMON_API_BASE}/inboxes',
        headers={'Authorization': f'Bearer {account_api_key}'},
        json={
            'username': agent_slug,
            'client_id': client_id
        }
    )

    data = response.json()

    print(f"✅ Created inbox for {agent_slug}")
    print(f"   📧 {data['result']['email']}")
    print(f"   🔑 {data['result']['inbox_api_key'][:20]}...")

    return {
        'id': data['result']['id'],
        'email': data['result']['email'],
        'inbox_api_key': data['result']['inbox_api_key']
    }

def setup_webhook(account_api_key, webhook_url, inbox_id=None):
    """Set up webhook for message notifications."""
    payload = {
        'url': webhook_url,
        'events': ['message.received']
    }

    if inbox_id:
        payload['inbox_id'] = inbox_id

    response = requests.post(
        f'{DAIMON_API_BASE}/webhooks',
        headers={'Authorization': f'Bearer {account_api_key}'},
        json=payload
    )

    data = response.json()
    print(f"✅ Webhook configured: {webhook_url}")

    return data['result']

def main():
    # Bootstrap platform
    account_api_key = bootstrap_platform()

    # Provision 3 agent inboxes
    agents = [
        {'slug': 'research-agent', 'id': 'agent-001'},
        {'slug': 'support-agent', 'id': 'agent-002'},
        {'slug': 'analytics-agent', 'id': 'agent-003'}
    ]

    inboxes = []

    for agent in agents:
        inbox = provision_agent_inbox(
            account_api_key,
            agent['slug'],
            agent['id']
        )
        inboxes.append(inbox)

    # Set up webhook for all inboxes
    setup_webhook(
        account_api_key,
        'https://your-platform.com/webhooks/daimon'
    )

    print('\n🎉 Platform provisioning complete!')
    print(f'   Total inboxes: {len(inboxes) + 1}')
    print('   Webhook: active')

if __name__ == '__main__':
    main()

Security Best Practices

Warning

Never expose your account API key to individual agents or users. Only use it in your platform's backend services.

Account API Key

  • Store in secrets manager (AWS Secrets Manager, Vault, etc.)
  • Only accessible to platform backend
  • Use for provisioning and account-level operations

Inbox API Keys

  • Scoped to individual inboxes
  • Safe to distribute to agents via environment variables
  • Rotate regularly for security

Key Rotation

If an account API key is compromised:

  1. Contact support@daimon.email immediately
  2. Request key rotation (generates new account API key)
  3. Update all platform services with new key
  4. Old key is immediately revoked

Common Patterns

Pattern: Multi-Tenant SaaS

If you run a multi-tenant SaaS platform where each customer gets their own set of agents:

Your Platform Account (1 account API key)
├── Customer A
│   ├── agent-1@daimon.email (inbox_api_key_1)
│   ├── agent-2@daimon.email (inbox_api_key_2)
│   └── support@daimon.email (inbox_api_key_3)
├── Customer B
│   ├── agent-1@daimon.email (inbox_api_key_4)
│   └── agent-2@daimon.email (inbox_api_key_5)

You pay once for all inboxes across all customers. Pass through costs via your own pricing.

Pattern: Agent Marketplace

If you run an agent marketplace where users deploy pre-built agents:

  1. User selects agent from marketplace
  2. Your platform provisions inbox: POST /v1/inboxes with client_id = user_id + agent_id
  3. Agent receives scoped API key via environment variable
  4. User manages agent via your dashboard

Pattern: Development → Production

For teams building agents locally:

  • Development: Each developer uses the free tier (10 inboxes) for testing
  • Production: Platform account on Developer/Growth tier for deployed agents

Enterprise Features

For large-scale deployments, daimon.email offers:

  • Custom SLA: 99.9% uptime guarantee
  • Dedicated support: Slack channel with <1hr response time
  • Volume discounts: Per-inbox pricing for >10,000 inboxes
  • Custom domains: Bring your own domain (e.g., agent@your-company.com)
  • SSO: SAML/OAuth for team access
  • Private deployment: Self-hosted on your infrastructure

Contact sales@daimon.email to discuss enterprise pricing.


Next Steps


Support