Skip to main content
An identity is a real email address on your verified domain — for example, assistant@yourcompany.com or support@yourcompany.com. Your AI sends and receives as that identity.

​
Creating an Identity

curl -X POST https://api.actionlayer.dev/v1/identities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Alex (AI Assistant)",
    "local_part": "assistant",
    "domain_id": "YOUR_DOMAIN_ID"
  }'
This creates assistant@yourcompany.com as a real sending and receiving address.

​
Identity Fields

FieldDescription
display_nameShown to recipients in the From field
local_partThe part before @ — must be unique per domain
domain_idMust reference a verified domain
approval_modemanual (default) or auto

​
Approval Mode

ModeBehavior
manual (default)Every draft requires human approval before sending
autoDrafts are automatically approved and sent on submission
Auto-send is always opt-in. Set it explicitly on the identity when creating or updating. 
curl -X POST https://api.actionlayer.dev/v1/identities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Billing Bot",
    "local_part": "billing",
    "domain_id": "YOUR_DOMAIN_ID",
    "approval_mode": "auto"
  }'

​
Identity States

StatusMeaning
activeReady to send and receive
suspendedTemporarily disabled

​
Inbound Email

When someone replies to an identity’s address, the message is parsed and stored as a new message in the thread. Your AI can read it via the threads API or MCP tools.