Update Inbox

Overview

Update metadata for a specific inbox. Currently, you can update the display_name. The email address itself cannot be changed after creation.

Authentication

Authorizationstringheaderrequired

Inbox API key in Bearer token format

Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o

Use the inbox-scoped api_key for the inbox you're updating.

Path Parameters

idstringpathrequired

Unique inbox identifier (format: inb_...)

The inbox ID you want to update.

Request Body

display_namestringbody

Human-readable display name for the inbox

Optional. Set to null to clear the display name (will default to username).

Response

resultobject

properties

idstring

Unique inbox identifier (format: inb_...)

addressstring

Full email address (unchanged, included for convenience)

display_namestring

Updated display name for the inbox

statusstring

Current inbox status

updated_atstring

ISO 8601 timestamp of when the inbox was last updated

next_stepsarray

Array of suggested actions for your agent to take next

Examples

curl -X PATCH https://api.daimon.email/v1/inboxes/inb_abc123def456 \
  -H "Authorization: Bearer dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Production Support Agent"
  }'

import { DaimonClient } from 'daimon-email';

// Initialize with inbox-scoped API key
const client = new DaimonClient({
  apiKey: 'dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o'
});

const updatedInbox = await client.inboxes.update('inb_abc123def456', {
  displayName: 'Production Support Agent'
});

console.log(`Updated display name to: ${updatedInbox.displayName}`);
console.log(`Updated at: ${updatedInbox.updatedAt}`);

from daimon_email import DaimonClient

# Initialize with inbox-scoped API key
client = DaimonClient(
    api_key="dm_free_7d8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o"
)

updated_inbox = client.inboxes.update(
    'inb_abc123def456',
    display_name='Production Support Agent'
)

print(f"Updated display name to: {updated_inbox.display_name}")
print(f"Updated at: {updated_inbox.updated_at}")

Response

{
  "result": {
    "id": "inb_abc123def456",
    "address": "my-agent@daimon.email",
    "display_name": "Production Support Agent",
    "status": "active",
    "updated_at": "2026-03-16T16:30:00Z"
  },
  "next_steps": [
    "The display name has been updated successfully",
    "Call GET /v1/inboxes/{id} to verify the changes"
  ]
}

{
  "result": {
    "id": "inb_abc123def456",
    "address": "my-agent@daimon.email",
    "display_name": "my-agent",
    "status": "active",
    "updated_at": "2026-03-16T16:35:00Z"
  },
  "next_steps": [
    "Display name cleared - now defaults to username",
    "Set a new display_name anytime to override the default"
  ]
}

{
  "error": "INVALID_API_KEY",
  "message": "The provided API key does not have access to this inbox",
  "next_steps": [
    "Verify you are using the correct inbox-scoped API key",
    "Ensure the API key has not been revoked"
  ]
}

{
  "error": "INBOX_NOT_FOUND",
  "message": "No inbox found with ID 'inb_abc123def456'",
  "next_steps": [
    "Verify the inbox ID is correct",
    "Call GET /v1/inboxes to list all available inboxes"
  ]
}

Important Notes

Note

Email address is immutable: You cannot change the email address (username@daimon.email) after inbox creation. Only the display_name can be updated.

Tip

Clearing display name: Set display_name to null to clear it. The inbox will then use the username portion of the email address as the display name.

Use Cases

Agent role changes: Update the display name when your agent's role or purpose changes (e.g., "Test Agent" → "Production Support Agent")
Organizational clarity: Use display names to distinguish between multiple inboxes (e.g., "Sales Bot", "Support Bot", "Notifications Bot")
Human readability: Make inbox lists more readable in dashboards or admin interfaces

On this page