Authentication

Authentication Levels

The daimon.email API uses two levels of authentication, each designed for different scopes of access:

1. Inbox API Key

Format: dm_free_* (free tier) or dm_live_* (paid tier)

Scope: Single inbox

Use cases:

Reading messages in a specific inbox
Sending messages from a specific inbox
Managing threads and drafts for a specific inbox
Accessing inbox-specific settings

How to get it: The inbox_api_key is returned when you create an inbox via POST /v1/inboxes.

2. Account API Key

Format: dm_account_*

Scope: Entire account

Use cases:

Listing all inboxes in your account
Managing webhook configurations
Checking account capabilities
Getting upgrade links
Notifying operators

How to get it: The account_api_key is also returned when you create your first inbox via POST /v1/inboxes.

How to Authenticate

Include your API key as a Bearer token in the Authorization header:

Authorization: Bearer dm_free_abc123def456...

Bootstrap: No Authentication Required

The inbox creation endpoint (POST /v1/inboxes) is the bootstrap endpoint and requires no authentication. This allows agents to self-provision infrastructure without pre-existing credentials.

# No auth needed for this endpoint
curl https://api.daimon.email/v1/inboxes \
  -X POST \
  -d '{"address": "agent1"}'

The response will include both keys:

{
  "result": {
    "inbox_id": "inbox_abc123",
    "inbox_api_key": "dm_free_xyz789...",
    "account_api_key": "dm_account_abc456...",
    "email_address": "agent1@daimon.email"
  }
}

Authentication Examples

Using Inbox API Key

# Get messages from a specific inbox
curl https://api.daimon.email/v1/inboxes/inbox_abc123/messages \
  -H "Authorization: Bearer dm_free_xyz789..."

// Get messages from a specific inbox
const response = await fetch(
  'https://api.daimon.email/v1/inboxes/inbox_abc123/messages',
  {
    headers: {
      'Authorization': 'Bearer dm_free_xyz789...'
    }
  }
);

const { result } = await response.json();
console.log('Messages:', result.messages);

# Get messages from a specific inbox
import requests

response = requests.get(
    'https://api.daimon.email/v1/inboxes/inbox_abc123/messages',
    headers={
        'Authorization': 'Bearer dm_free_xyz789...'
    }
)

data = response.json()
print(f"Messages: {data['result']['messages']}")

Using Account API Key

# List all inboxes in your account
curl https://api.daimon.email/v1/inboxes \
  -H "Authorization: Bearer dm_account_abc456..."

// List all inboxes in your account
const response = await fetch(
  'https://api.daimon.email/v1/inboxes',
  {
    headers: {
      'Authorization': 'Bearer dm_account_abc456...'
    }
  }
);

const { result } = await response.json();
console.log('Your inboxes:', result.inboxes);

# List all inboxes in your account
import requests

response = requests.get(
    'https://api.daimon.email/v1/inboxes',
    headers={
        'Authorization': 'Bearer dm_account_abc456...'
    }
)

data = response.json()
print(f"Your inboxes: {data['result']['inboxes']}")

Sending a Message (Inbox API Key)

# Send an email from a specific inbox
curl https://api.daimon.email/v1/inboxes/inbox_abc123/send \
  -X POST \
  -H "Authorization: Bearer dm_free_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Hello from AI Agent",
    "body": "This is an automated message."
  }'

// Send an email from a specific inbox
const response = await fetch(
  'https://api.daimon.email/v1/inboxes/inbox_abc123/send',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer dm_free_xyz789...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      to: ['recipient@example.com'],
      subject: 'Hello from AI Agent',
      body: 'This is an automated message.'
    })
  }
);

const { result } = await response.json();
console.log('Message sent:', result.message_id);

# Send an email from a specific inbox
import requests

response = requests.post(
    'https://api.daimon.email/v1/inboxes/inbox_abc123/send',
    headers={
        'Authorization': 'Bearer dm_free_xyz789...',
        'Content-Type': 'application/json'
    },
    json={
        'to': ['recipient@example.com'],
        'subject': 'Hello from AI Agent',
        'body': 'This is an automated message.'
    }
)

data = response.json()
print(f"Message sent: {data['result']['message_id']}")

Common Authentication Errors

401 Unauthorized

You'll receive this error when:

No Authorization header is provided (for authenticated endpoints)
The API key is invalid or expired
You're using an inbox API key on an account-level endpoint (or vice versa)

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "next_steps": [
    "Verify your API key is included in the Authorization header",
    "Ensure you're using the correct key type (inbox vs account)",
    "Create a new inbox to get fresh API keys"
  ]
}

403 Forbidden

You'll receive this error when:

Using an inbox API key to access a different inbox
Attempting an operation not allowed on your tier

{
  "error": "FORBIDDEN",
  "message": "This API key does not have access to the requested resource",
  "next_steps": [
    "Verify you're using the correct inbox API key",
    "Use the account API key for account-level operations"
  ]
}

Key Security Best Practices

Warning

Never expose API keys in client-side code or public repositories. API keys grant full access to their scope (inbox or account).

Store keys in environment variables or secure secret management systems
Rotate keys if you suspect they've been compromised
Use inbox-scoped keys when possible (principle of least privilege)
Monitor API usage for unexpected activity

Key Rotation

To rotate your keys:

Create a new inbox (gets new inbox + account keys)
Update your application to use the new keys
Delete the old inbox if no longer needed

Info

Account API keys are tied to your account, not individual inboxes. When you create your first inbox, you get an account key that works across all inboxes you create.

Quick Reference

Endpoint	Key Type Required	Purpose
`POST /v1/inboxes`	None (bootstrap)	Create inbox, get keys
`GET /v1/inboxes`	Account	List all inboxes
`GET /v1/inboxes/{id}/messages`	Inbox	Get inbox messages
`POST /v1/inboxes/{id}/send`	Inbox	Send from inbox
`GET /v1/webhooks`	Account	List webhooks
`GET /v1/capabilities`	Account	Check capabilities

On this page