Get Capabilities

Authentication

Account API Key required via Authorization: Bearer {api_key} header.

The capabilities endpoint is designed for AI agents to understand their current permissions and limitations. Instead of hardcoding tier checks, agents should call this endpoint to dynamically discover what actions are available.

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

import { DaimonClient } from 'daimon-email';

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

const capabilities = await client.account.getCapabilities();

console.log('Current tier:', capabilities.tier);

// Check what's allowed
capabilities.can.forEach(cap => {
  console.log(`✓ ${cap.action}: ${cap.description}`);
});

// Check what's blocked
capabilities.cannot.forEach(cap => {
  console.log(`✗ ${cap.action}: ${cap.reason}`);
  if (cap.unlock_url) {
    console.log(`  Upgrade: ${cap.unlock_url}`);
  }
});

from daimon_email import DaimonClient

client = DaimonClient(api_key='dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o')

capabilities = client.account.get_capabilities()

print(f"Current tier: {capabilities.tier}")

# Check what's allowed
for cap in capabilities.can:
    print(f"✓ {cap['action']}: {cap['description']}")

# Check what's blocked
for cap in capabilities.cannot:
    print(f"✗ {cap['action']}: {cap['reason']}")
    if 'unlock_url' in cap:
        print(f"  Upgrade: {cap['unlock_url']}")

Response

{
  "result": {
    "tier": "free",
    "can": [
      {
        "action": "receive_messages",
        "description": "Receive unlimited inbound emails"
      },
      {
        "action": "create_inboxes",
        "description": "Create unlimited inboxes with @daimon.email addresses"
      },
      {
        "action": "create_webhooks",
        "description": "Register webhooks for real-time events"
      },
      {
        "action": "use_reply_extraction",
        "description": "Automatic reply body extraction with TalonJS"
      },
      {
        "action": "use_link_extraction",
        "description": "Automatic CTA and verification link detection"
      },
      {
        "action": "use_threading",
        "description": "Automatic email threading based on headers"
      }
    ],
    "cannot": [
      {
        "action": "send_messages",
        "reason": "SEND_REQUIRES_PAID",
        "unlock_url": "https://daimon.email/upgrade?token=eyJhbGc...",
        "api_call": "POST /v1/upgrade-link"
      },
      {
        "action": "use_custom_domains",
        "reason": "DOMAIN_REQUIRES_PAID",
        "unlock_url": "https://daimon.email/upgrade?token=eyJhbGc...",
        "api_call": "POST /v1/upgrade-link"
      },
      {
        "action": "use_smtp",
        "reason": "SMTP_REQUIRES_PAID",
        "unlock_url": "https://daimon.email/upgrade?token=eyJhbGc...",
        "api_call": "POST /v1/upgrade-link"
      }
    ],
    "upgrade_context": {
      "operator_action_url": "https://daimon.email/upgrade?token=eyJhbGc...",
      "operator_action_label": "Upgrade to enable sending",
      "agent_script": "Tell your operator: I need sending access. Here's a direct upgrade link: https://daimon.email/upgrade?token=eyJhbGc..."
    }
  },
  "next_steps": [
    "Use the can[] array to determine available actions",
    "When hitting a cannot[] limitation, use the upgrade_context to request operator intervention",
    "Call POST /v1/upgrade-link to generate a fresh upgrade URL"
  ]
}

{
  "result": {
    "tier": "developer",
    "can": [
      {
        "action": "receive_messages",
        "description": "Receive unlimited inbound emails"
      },
      {
        "action": "send_messages",
        "description": "Send up to 100 emails/day, 3,000/month"
      },
      {
        "action": "create_inboxes",
        "description": "Create unlimited inboxes"
      },
      {
        "action": "use_custom_domains",
        "description": "Connect 1 custom domain"
      },
      {
        "action": "use_smtp",
        "description": "SMTP access for direct email sending"
      },
      {
        "action": "create_webhooks",
        "description": "Register webhooks for real-time events"
      },
      {
        "action": "use_reply_extraction",
        "description": "Automatic reply body extraction with TalonJS"
      },
      {
        "action": "use_link_extraction",
        "description": "Automatic CTA and verification link detection"
      },
      {
        "action": "use_threading",
        "description": "Automatic email threading based on headers"
      }
    ],
    "cannot": [],
    "upgrade_context": null
  },
  "next_steps": [
    "All core features available at Developer tier",
    "Monitor daily/monthly send limits via GET /v1/account",
    "Upgrade to Growth tier for higher sending limits"
  ]
}

Response Fields

tierstring

Current account tier: free, developer, growth, or enterprise

canarray

Array of allowed actions. Each entry contains:

action (string) - Action identifier (e.g., "send_messages")
description (string) - Human-readable description

cannotarray

Array of blocked actions. Each entry contains:

action (string) - Action identifier
reason (string) - Reason code (e.g., "SEND_REQUIRES_PAID")
unlock_url (string) - Magic link to upgrade (JWT-signed, 7-day expiry)
api_call (string) - API endpoint to generate new upgrade link

upgrade_contextobject | null

Present when cannot[] has entries. Contains:

operator_action_url - Magic upgrade link
operator_action_label - User-facing button text
agent_script - Script the agent can use to request upgrade from operator

Action Identifiers

Action	Free	Developer	Growth	Enterprise
`receive_messages`	✓	✓	✓	✓
`create_inboxes`	✓	✓	✓	✓
`create_webhooks`	✓	✓	✓	✓
`use_reply_extraction`	✓	✓	✓	✓
`use_link_extraction`	✓	✓	✓	✓
`use_threading`	✓	✓	✓	✓
`send_messages`	✗	✓	✓	✓
`use_custom_domains`	✗	✓ (1 domain)	✓ (5 domains)	✓ (unlimited)
`use_smtp`	✗	✓	✓	✓

Reason Codes

When cannot[] contains entries, each has a reason code:

SEND_REQUIRES_PAID - Sending requires paid tier
SEND_LIMIT_EXCEEDED - Daily/monthly send limit reached
DOMAIN_REQUIRES_PAID - Custom domains require paid tier
SMTP_REQUIRES_PAID - SMTP access requires paid tier
ACCOUNT_UNDER_REVIEW - Account flagged for review
WEBHOOK_ENDPOINT_UNHEALTHY - Webhook delivery failing

Agent Integration Pattern

This is the recommended pattern for capability-aware agents:

async function ensureCanSend(client: DaimonClient): Promise<void> {
  const caps = await client.account.getCapabilities();

  const sendCapability = caps.cannot.find(c => c.action === 'send_messages');

  if (sendCapability) {
    // Agent cannot send - request upgrade
    console.log(caps.upgrade_context.agent_script);
    // Output: "Tell your operator: I need sending access. Here's a direct upgrade link: https://..."

    throw new Error('Sending not available - upgrade required');
  }

  // Agent can send - proceed
  console.log('Sending is enabled');
}

Info

Why this endpoint exists: Traditional APIs require agents to memorize tier limits. This endpoint makes agents "self-aware" - they can introspect their permissions at runtime and autonomously request upgrades when needed.

Error Responses

401error

Invalid or missing API key

GET /v1/account - View account details and usage stats
POST /v1/upgrade-link - Generate a fresh upgrade link
POST /v1/notify-operator - Request operator intervention for any issue