curl -X POST https://api.wirebox.sh/api/v1/identities \
-H "Authorization: Bearer $WIREBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_handle": "eva",
"display_name": "Eva Customer Support",
"description": "Customer triage agent"
}'
from wirebox import Wirebox
with Wirebox() as wirebox:
identity = wirebox.create_identity(
"eva",
display_name="Eva Customer Support",
description="Customer triage agent"
)
import { Wirebox } from "@wirebox-sh/sdk";
const wirebox = new Wirebox();
const identity = await wirebox.createIdentity({
agent_handle: "eva",
display_name: "Eva Customer Support",
description: "Customer triage agent",
});
wirebox identity create \
--handle eva \
--display-name "Eva Customer Support" \
--description "Customer triage agent"
{
"id": "ident_01J8ABC123XYZ",
"agent_handle": "eva",
"display_name": "Eva Customer Support",
"description": "Customer triage agent",
"status": "active",
"imessage_enabled": false,
"mail_filter_mode": "blacklist",
"mail_inbound_filter_mode": "blacklist",
"mail_outbound_filter_mode": "blacklist",
"email_address": "eva@wireboxmail.com",
"created_at": "2026-09-11T10:00:00Z",
"updated_at": "2026-09-11T10:00:00Z",
"mailbox": {
"id": "mbx_01J8ABC123XYZ",
"email_address": "eva@wireboxmail.com",
"created_at": "2026-09-11T10:00:00Z"
},
"tunnel": {
"id": "tnl_01J8ABC123XYZ",
"public_url": "https://eva.wirebox.run",
"status": "active",
"is_connected": false
}
}
Agent Identities
Create Agent Identity
Register a new autonomous agent identity and automatically provision a dedicated mailbox.
POST
/
api
/
v1
/
identities
curl -X POST https://api.wirebox.sh/api/v1/identities \
-H "Authorization: Bearer $WIREBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_handle": "eva",
"display_name": "Eva Customer Support",
"description": "Customer triage agent"
}'
from wirebox import Wirebox
with Wirebox() as wirebox:
identity = wirebox.create_identity(
"eva",
display_name="Eva Customer Support",
description="Customer triage agent"
)
import { Wirebox } from "@wirebox-sh/sdk";
const wirebox = new Wirebox();
const identity = await wirebox.createIdentity({
agent_handle: "eva",
display_name: "Eva Customer Support",
description: "Customer triage agent",
});
wirebox identity create \
--handle eva \
--display-name "Eva Customer Support" \
--description "Customer triage agent"
{
"id": "ident_01J8ABC123XYZ",
"agent_handle": "eva",
"display_name": "Eva Customer Support",
"description": "Customer triage agent",
"status": "active",
"imessage_enabled": false,
"mail_filter_mode": "blacklist",
"mail_inbound_filter_mode": "blacklist",
"mail_outbound_filter_mode": "blacklist",
"email_address": "eva@wireboxmail.com",
"created_at": "2026-09-11T10:00:00Z",
"updated_at": "2026-09-11T10:00:00Z",
"mailbox": {
"id": "mbx_01J8ABC123XYZ",
"email_address": "eva@wireboxmail.com",
"created_at": "2026-09-11T10:00:00Z"
},
"tunnel": {
"id": "tnl_01J8ABC123XYZ",
"public_url": "https://eva.wirebox.run",
"status": "active",
"is_connected": false
}
}
Body Parameters
string
required
Unique handle for this agent: 3–63 characters, lowercase letters, digits, and hyphens only; must start and end with a letter or digit; consecutive hyphens are not allowed. Example:
eva.string
Human-readable name for display in email headers and the Console. Example:
Eva Support.string
Optional context describing this agent’s purpose.
boolean
default:"false"
Enable the Apple iMessage router channel for this identity.
string
Optional ID of a verified custom domain to use for this identity’s mailbox address. Takes precedence over
domain.string
Optional custom domain hostname to use for this identity’s mailbox address. If neither
custom_domain_id nor domain is provided, the organization’s verified default domain is used when available.Response
string
Unique identity identifier (e.g.
ident_01J8ABC123XYZ).string
The claimed handle.
string
Display name for the agent.
string
Description of the agent.
string
Identity status (
active).boolean
Whether the iMessage router channel is enabled.
string
Legacy combined mail filter posture (
whitelist or blacklist).string
Inbound guardrail posture:
whitelist (only approved senders) or blacklist (open to anyone).string
Outbound guardrail posture:
whitelist (only approved recipients) or blacklist (open to anyone).string
The provisioned mailbox address (e.g.
eva@wireboxmail.com).object
Provisioned mailbox summary:
id, email_address, created_at.object
Provisioned network tunnel:
id, public_url, status, is_connected.string
ISO 8601 creation timestamp.
string
ISO 8601 update timestamp.
curl -X POST https://api.wirebox.sh/api/v1/identities \
-H "Authorization: Bearer $WIREBOX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_handle": "eva",
"display_name": "Eva Customer Support",
"description": "Customer triage agent"
}'
from wirebox import Wirebox
with Wirebox() as wirebox:
identity = wirebox.create_identity(
"eva",
display_name="Eva Customer Support",
description="Customer triage agent"
)
import { Wirebox } from "@wirebox-sh/sdk";
const wirebox = new Wirebox();
const identity = await wirebox.createIdentity({
agent_handle: "eva",
display_name: "Eva Customer Support",
description: "Customer triage agent",
});
wirebox identity create \
--handle eva \
--display-name "Eva Customer Support" \
--description "Customer triage agent"
{
"id": "ident_01J8ABC123XYZ",
"agent_handle": "eva",
"display_name": "Eva Customer Support",
"description": "Customer triage agent",
"status": "active",
"imessage_enabled": false,
"mail_filter_mode": "blacklist",
"mail_inbound_filter_mode": "blacklist",
"mail_outbound_filter_mode": "blacklist",
"email_address": "eva@wireboxmail.com",
"created_at": "2026-09-11T10:00:00Z",
"updated_at": "2026-09-11T10:00:00Z",
"mailbox": {
"id": "mbx_01J8ABC123XYZ",
"email_address": "eva@wireboxmail.com",
"created_at": "2026-09-11T10:00:00Z"
},
"tunnel": {
"id": "tnl_01J8ABC123XYZ",
"public_url": "https://eva.wirebox.run",
"status": "active",
"is_connected": false
}
}