Create Inbox
Create a new inbox with instant API access
Overview
Create a new inbox at @daimon.email with instant API access.
Authentication
No authentication required. This endpoint is designed for agent self-bootstrapping.
If an Authorization: Bearer {api_key} header is provided with a valid account API key, the inbox will be created under that existing account.
Request Body
usernamestringbodyrequiredUsername for the inbox (will become username@daimon.email)
- Must be 3-32 characters
- Lowercase alphanumeric and hyphens only
- Must start and end with alphanumeric character
- Must be unique across all inboxes
display_namestringbodyHuman-readable display name for the inbox
Optional. Defaults to the username if not provided.
client_idstringbodyIdempotency key to prevent duplicate inbox creation
Optional. If provided and matches an existing inbox for this account, returns the existing inbox instead of creating a duplicate (200 response with existing inbox data).
Response
resultobjectproperties
idstringPrefixed inbox identifier (format: inb_<uuid>)
addressstringFull email address (e.g., username@daimon.email)
api_keystringInbox-scoped API key for inbox-specific operations
account_api_keystringAccount-scoped API key for account-level operations
display_namestringDisplay name for the inbox
statusstringCurrent inbox status (e.g., active)
tierstringAccount tier (e.g., free, paid)
view_urlstringURL for viewing inbox status and activity
created_atstringISO 8601 timestamp of inbox creation
next_stepsarrayArray of suggested actions for your agent to take next
Examples
curl -X POST https://api.daimon.email/v1/inboxes \
-H "Content-Type: application/json" \
-d '{
"username": "my-agent",
"display_name": "My AI Agent",
"client_id": "unique-idempotency-key-123"
}'import { DaimonClient } from 'daimon-email';
const client = new DaimonClient();
const inbox = await client.inboxes.create({
username: 'my-agent',
displayName: 'My AI Agent',
clientId: 'unique-idempotency-key-123'
});
console.log(`Created: ${inbox.address}`);
console.log(`Inbox API Key: ${inbox.apiKey}`);
console.log(`Account API Key: ${inbox.accountApiKey}`);from daimon_email import DaimonClient
client = DaimonClient()
inbox = client.inboxes.create(
username="my-agent",
display_name="My AI Agent",
client_id="unique-idempotency-key-123"
)
print(f"Created: {inbox.address}")
print(f"Inbox API Key: {inbox.api_key}")
print(f"Account API Key: {inbox.account_api_key}")Response
{
"result": {
"id": "inb_ad809dc8-1fa1-4440-8523-cb24926b8fc2",
"address": "my-agent@daimon.email",
"api_key": "dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o",
"account_api_key": "dm_free_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
"display_name": null,
"status": "active",
"tier": "free",
"view_url": "https://daimon.email/status/ad809dc8-1fa1-4440-8523-cb24926b8fc2?key=dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o",
"created_at": "2026-03-16T12:34:56Z"
},
"next_steps": [
"Save your API keys securely",
"Use account_api_key for account-level operations (e.g., GET /v1/capabilities)",
"Use api_key for inbox-specific operations",
"Use GET /v1/inboxes/{id}/messages to poll for messages",
"Register webhooks with POST /v1/webhooks for real-time notifications",
"Share your view_url with your operator to monitor inbox state"
]
}{
"error": "INVALID_USERNAME",
"next_steps": [
"Choose a username between 3-32 characters",
"Use only lowercase letters, numbers, and hyphens",
"Ensure username starts and ends with alphanumeric character"
]
}{
"error": "USERNAME_TAKEN",
"next_steps": [
"Try a different username",
"Add a suffix like 'my-agent-2' or 'my-agent-prod'"
]
}Idempotency
When you provide a client_id, the API will return the existing inbox if one was already created with the same client_id for your account. This prevents duplicate inbox creation if your agent retries the request.
The response will be identical whether the inbox is newly created or already exists - check the created_at timestamp to determine if this is a new inbox.
Important Notes
Note
Save both API keys securely: api_key is inbox-scoped, account_api_key is account-scoped.
Warning
Free tier domain: Free tier inboxes are always created at @daimon.email. Custom domains require a paid tier.