Introduction

Overview

The daimon.email API provides programmatic email infrastructure designed specifically for AI agents. Create inboxes instantly, receive emails, and manage conversations without OAuth flows or human verification.

Base URL

All API requests should be made to:

https://api.daimon.email

All endpoints are versioned and available under the /v1/ path:

https://api.daimon.email/v1/inboxes

Content Type

All requests and responses use JSON:

Content-Type: application/json

Response Format

Every API response follows a consistent wrapper format designed to help AI agents make decisions.

Success Response

{
  "result": {
    // Your response data here
  },
  "next_steps": [
    "Poll GET /v1/inboxes/{id}/messages to check for new messages",
    "Configure a webhook endpoint for real-time notifications"
  ]
}

The next_steps array provides contextual guidance on what actions make sense after each operation.

Error Response

{
  "error": "INBOX_NOT_FOUND",
  "message": "No inbox found with id: inbox_abc123",
  "next_steps": [
    "Verify the inbox ID is correct",
    "Create a new inbox with POST /v1/inboxes"
  ]
}

Tier-Limited Errors

When an operation requires a paid plan, the response includes upgrade context to help agents guide their operators:

{
  "error": "SEND_REQUIRES_PAID",
  "message": "Outbound sending is only available on paid plans",
  "upgrade_context": {
    "operator_action_url": "https://daimon.email/upgrade?token=eyJ...",
    "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: https://daimon.email/upgrade?token=eyJ..."
  },
  "next_steps": [
    "Present the upgrade_context.agent_script to your operator",
    "Wait for your operator to complete the upgrade",
    "Retry this request after upgrade is complete"
  ]
}

Common tier-limit error codes:

• SEND_REQUIRES_PAID - Outbound sending requires a paid plan
• SEND_LIMIT_EXCEEDED - Monthly sending quota exceeded
• DOMAIN_REQUIRES_PAID - Custom domains require a paid plan
• INBOX_LIMIT_EXCEEDED - Account inbox limit reached
• SMTP_REQUIRES_PAID - SMTP credentials require a paid plan
• WEBHOOK_ENDPOINT_UNHEALTHY - Webhook endpoint is not responding
• ACCOUNT_UNDER_REVIEW - Account is under review

OpenAPI Specification

The complete OpenAPI 3.0 specification is available at:

https://api.daimon.email/openapi.json

You can import this into tools like Postman, Insomnia, or use it to generate SDKs.

Pagination

List endpoints support pagination using limit and offset query parameters:

GET /v1/inboxes/\{id\}/messages?limit=50&offset=100

• limit: Number of items to return (default: 50, max: 100)
• offset: Number of items to skip (default: 0)

Rate Limiting

The API enforces rate limits to ensure fair usage:

• Free tier: 10 inbox creates per IP per hour
• Paid tier: 100 inbox creates per account per hour
• All other endpoints: 1000 requests per minute

When you exceed a rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please try again in 3600 seconds.",
  "retry_after": 3600,
  "next_steps": [
    "Wait 3600 seconds before retrying",
    "Implement exponential backoff in your client"
  ]
}

Use exponential backoff when retrying requests.

Idempotency

To prevent duplicate operations, include a client_id field in POST requests:

{
  "client_id": "my-unique-operation-id",
  "address": "agent1"
}

The API will:

1. Process the request on first submission
2. Return the existing resource (200 OK) on subsequent submissions with the same client_id

This is especially useful for:

• Creating inboxes (POST /v1/inboxes)
• Sending messages (POST /v1/inboxes/{id}/send)

Example Requests

# Success example
curl https://api.daimon.email/v1/inboxes \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "address": "agent1",
    "client_id": "unique-123"
  }'

// Success example
const response = await fetch('https://api.daimon.email/v1/inboxes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    address: 'agent1',
    client_id: 'unique-123'
  })
});

const { result, next_steps } = await response.json();
console.log('Created inbox:', result.inbox_id);
console.log('What to do next:', next_steps);

# Success example
import requests

response = requests.post(
    'https://api.daimon.email/v1/inboxes',
    json={
        'address': 'agent1',
        'client_id': 'unique-123'
    }
)

data = response.json()
print(f"Created inbox: {data['result']['inbox_id']}")
print(f"Next steps: {data['next_steps']}")

Need Help?

• Documentation: docs.daimon.email
• OpenAPI Spec: api.daimon.email/openapi.json
• Support: support@daimon.email