📧 Email Identity Management

Give Your AI Agents Email Addresses

Register email identities on domains you control. AI Maestro manages the identity, your external gateway handles the transport.

How It Works API Reference
💡

Identity vs Transport

AI Maestro handles email identity (who the agent is), not email transport (sending/receiving). You need an external email gateway or mail processor (like Mandrill, SendGrid, Postmark, or your own SMTP server) to actually deliver emails.

🎭 AI Maestro Handles

  • ✓ Email address registration
  • ✓ Domain management
  • ✓ Agent-to-email mapping
  • ✓ Webhook notifications
  • ✓ Uniqueness enforcement

📬 Your Gateway Handles

  • → SMTP/email delivery
  • → Inbound email routing
  • → DNS/MX records
  • → Spam filtering
  • → Email storage

How It Works

Three simple steps to give your agents email identity

1
🌐

Add Your Domains

Register domains you control in Settings. These become available for creating agent email addresses.

2
📧

Create Email Addresses

Assign email addresses to agents using name@domain format. Each address is globally unique.

3
🔔

Configure Webhooks

Set up webhook subscriptions to notify your email gateway when addresses are created, updated, or deleted.

API Reference

RESTful endpoints for managing domains, email addresses, and webhooks

🌐 Domains API

GET /api/domains List all domains 
curl http://localhost:23000/api/domains
POST /api/domains Add a domain 
curl -X POST http://localhost:23000/api/domains \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "isDefault": true}'
DELETE /api/domains/:id Remove a domain 
curl -X DELETE http://localhost:23000/api/domains/domain-uuid

📧 Email Addresses API

GET /api/agents/:id/emails List agent's emails 
curl http://localhost:23000/api/agents/{agentId}/emails
POST /api/agents/:id/emails Add email to agent 
curl -X POST http://localhost:23000/api/agents/{agentId}/emails \
  -H "Content-Type: application/json" \
  -d '{"address": "support@example.com", "displayName": "Support Bot"}'
GET /api/email-lookup?address=:email Find agent by email 
curl "http://localhost:23000/api/email-lookup?address=support@example.com"

🔔 Webhooks API

POST /api/webhooks Subscribe to events 
curl -X POST http://localhost:23000/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-gateway.com/webhook",
    "events": ["email.created", "email.deleted"],
    "secret": "your-webhook-secret"
  }'

Available Webhook Events

email.created New address registered
email.updated Address modified
email.deleted Address removed
domain.created Domain added

Webhook Payloads

Example payloads sent to your gateway

email.created webhook payload 
{
  "event": "email.created",
  "timestamp": "2026-01-27T14:30:00.000Z",
  "data": {
    "emailAddress": {
      "id": "email-uuid",
      "address": "support@example.com",
      "displayName": "Support Bot",
      "createdAt": "2026-01-27T14:30:00.000Z"
    },
    "agent": {
      "id": "agent-uuid",
      "name": "support-agent"
    }
  },
  "signature": "sha256=..."
}

Quick Start

Set up email identity for your agents

1

Add a domain in Settings

Go to Settings → Domains and add a domain you control (e.g., yourdomain.com).

2

Create an email address for an agent

Select an agent, go to Email Addresses, and click "Add Email Address". Choose a name and domain.

3

Configure your email gateway

Set up a webhook in Settings → Webhooks to notify your email gateway (Mandrill, SendGrid, Postmark, etc.) when email addresses are created or deleted.

4

Route inbound emails to agents

Configure your gateway to forward inbound emails to AI Maestro using the /api/email-lookup endpoint to resolve which agent should receive the email.