Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.actionlayer.dev/llms.txt

Use this file to discover all available pages before exploring further.

A sender identity is a real email address on a verified domain — assistant@yourcompany.com, mia@yourcompany.com, etc. Identities own their own approval channels, signatures, and behavior toggles.
MethodPathPurpose
POST/v1/identitiesCreate an identity
GET/v1/identitiesList identities
GET/v1/identities/{id}Get one identity
PATCH/v1/identities/{id}Update an identity
DELETE/v1/identities/{id}Delete an identity (threads/messages preserved)
POST/v1/identities/{id}/test-emailSend a test email from this identity

​
Create

The domain must have all four DNS records verified before you can create an identity on it. 
curl -X POST https://api.actionlayer.dev/v1/identities \
  -H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_id": "DOMAIN_ID",
    "local_part": "assistant",
    "display_name": "Mia (AI Assistant)",
    "signature_text": "— Mia, your AI assistant",
    "thread_history_depth": 10,
    "can_send_cold": false,
    "auto_approve_replies": false
  }'

​
Request body

FieldTypeRequiredDefaultNotes
domain_idUUIDyes—Must be a verified domain
local_partstringyes—Lowercase, alphanumerics + . _ + -. Combined with the domain to form email_address.
display_namestringyes—The “From: Display Name” that recipients see
assistant_idUUIDnonullLink to an Assistant record (for multi-agent setups)
reply_to_emailstringnonullOverride the Reply-To header
signature_text / signature_htmlstringnonullAuto-appended on sends
thread_history_depthintno10How many prior messages your agent gets when reading a thread (max 20)
approval_channelobjectnonullWhere draft notifications go — see Approval Channels below
can_send_coldboolnofalseIf false, identity can only reply on existing threads
auto_approve_repliesboolnofalseIf true, drafts auto-approve and queue for delivery on submission
email_address is derived from local_part + domain. Do not send it directly. Once an identity is created, the address cannot be changed.

​
Response (201 Created)

{
  "id": "id_…",
  "workspace_id": "…",
  "domain_id": "…",
  "local_part": "assistant",
  "email_address": "assistant@yourcompany.com",
  "display_name": "Mia (AI Assistant)",
  "thread_history_depth": 10,
  "status": "active",
  "approval_channel": null,
  "can_send_cold": false,
  "auto_approve_replies": false,
  "created_at": "…",
  "updated_at": "…"
}

​
List

curl 'https://api.actionlayer.dev/v1/identities?status=active' \
  -H "Authorization: Bearer $ACTIONLAYER_API_KEY"
Filters: domain_id, status (active | disabled), limit, offset.

​
Update

All fields optional. Only provided fields change. 
curl -X PATCH https://api.actionlayer.dev/v1/identities/IDENTITY_ID \
  -H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Mia from Acme",
    "auto_approve_replies": true,
    "approval_channel": {
      "type": "telegram",
      "config": { "bot_token": "1234:abcd…", "chat_id": "987654321" }
    }
  }'
When approval_channel.type is telegram and a bot_token is present, the Telegram webhook is auto-registered (you don’t have to call BotFather’s setWebhook). status accepts "active" or "disabled". Disabled identities cannot send.

​
Approval Channels

Each identity routes draft notifications through one channel (and optionally a secondary for escalation).

​
Telegram

{
  "type": "telegram",
  "config": {
    "bot_token": "1234567890:AAH…",
    "chat_id": "987654321"
  }
}
You provide a bot token from @BotFather and the chat ID for the destination (a personal chat or group). Approval and rejection happen via inline buttons in the chat.

​
Slack

{
  "type": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/services/T…/B…/…",
    "channel": "#approvals"
  }
}

​
Email

{
  "type": "email",
  "config": { "to": "approvers@yourcompany.com" }
}
You receive a one-click Approve / Reject email — no login required.
Secrets in approval_channel.config (bot tokens, webhook URLs) are masked in API responses. The full value lives encrypted server-side. To rotate a secret, send a new approval_channel object with the updated value.
You can also configure secondary_approval_channel and escalation_delay_minutes to route to a backup if the primary doesn’t act in time.

​
Delete

curl -X DELETE https://api.actionlayer.dev/v1/identities/IDENTITY_ID \
  -H "Authorization: Bearer $ACTIONLAYER_API_KEY"
Threads, messages, and drafts owned by the identity are preserved — only the identity record is removed. The address can no longer send or receive.

​
Test email

Sends a deliverability test from this identity. 
curl -X POST https://api.actionlayer.dev/v1/identities/IDENTITY_ID/test-email \
  -H "Authorization: Bearer $ACTIONLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient_email": "you@yourcompany.com"}'
Returns 202 with a task_id. Identity must have status: "active". Rate-limited to 10/min.

​
Errors

HTTPerrorWhen
402plan_limit_reachedWorkspace at the identities cap (1 / 10 / 50 by plan)
409invalid_request (already in use)local_part@domain already exists
422invalid_requestlocal_part failed validation, domain not verified, etc.
422identity_not_activeTried to send from a disabled identity