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.
Pattern B: Platform (Recommended for Scale)
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:
| Tier | Price | Inboxes | Sends/Day | Webhooks | Custom Domains |
|---|---|---|---|---|---|
| Free | $0 | 10 | 0 (receive only) | No | No |
| Developer | $9/mo | Unlimited | 1,000 | Yes | Yes |
| Growth | $49/mo | Unlimited | 10,000 | Yes | Yes |
| Enterprise | Custom | Unlimited | Unlimited | Yes | Yes + 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:
- Auto-upgrade: Programmatically upgrade the account via
POST /v1/account/upgradewith a Stripe payment method - 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:
- Contact support@daimon.email immediately
- Request key rotation (generates new account API key)
- Update all platform services with new key
- 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:
- User selects agent from marketplace
- Your platform provisions inbox:
POST /v1/inboxeswithclient_id = user_id + agent_id - Agent receives scoped API key via environment variable
- 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
<1hrresponse 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
API Reference
Complete API documentation for all endpoints
Webhooks Guide
Set up real-time message delivery
Custom Domains
Use your own domain for agent inboxes
Support
- Technical support: support@daimon.email
- Enterprise sales: sales@daimon.email
- Community: Discord (coming soon)