Identity Primitives

Agent Email

Provision a fully functional email address for your AI agent, complete with DKIM signing, SPF records, and DMARC compliance. Send and receive email programmatically with webhook-driven inbound delivery.

How email provisioning works

When you create an agent with email enabled, Humiris provisions a dedicated mailbox on your workspace domain. Each agent gets a unique address in the format agent-slug@yourworkspace.humiris.com, or you can connect a custom domain.

The provisioned mailbox is fully standards-compliant. Every outbound message is DKIM-signed, SPF-aligned, and DMARC-compliant out of the box. Inbound mail is received in real time and forwarded to your application via webhooks.

bash

# Provision an agent with email
curl -X POST https://api.humiris.com/v1/agents \
  -H "Authorization: Bearer hum_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "alex-sdr",
    "persona": {
      "firstName": "Alex",
      "lastName": "Rivera"
    },
    "identity": {
      "email": true
    }
  }'

DKIM, SPF, and DMARC configuration

If you use the default *.humiris.com domain, authentication records are pre-configured. No DNS changes are required.

For custom domains, Humiris provides the DNS records you need to add. After verification, all outbound mail from your agents will pass DKIM, SPF, and DMARC checks automatically.

bash

# Check domain verification status
curl https://api.humiris.com/v1/domains/acme.com/verify \
  -H "Authorization: Bearer hum_sk_live_..."

# Response
{
  "domain": "acme.com",
  "dkim": "verified",
  "spf": "verified",
  "dmarc": "verified",
  "status": "active"
}

Sending email via API

Send email from your agent using a simple POST request. Humiris supports plain text, HTML, attachments, and CC/BCC recipients.

bash

# Send an email
curl -X POST https://api.humiris.com/v1/agents/alex-sdr/email/send \
  -H "Authorization: Bearer hum_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "customer@example.com",
    "subject": "Following up on our conversation",
    "body": "Hi there,\n\nJust wanted to follow up...",
    "format": "text"
  }'

Receiving email via API

You can poll for new messages or list the full inbox contents. Each message includes parsed headers, body content, and any attachments as download URLs.

bash

# List inbox messages
curl https://api.humiris.com/v1/agents/alex-sdr/email/inbox \
  -H "Authorization: Bearer hum_sk_live_..."

# Get a specific message
curl https://api.humiris.com/v1/agents/alex-sdr/email/messages/msg_abc123 \
  -H "Authorization: Bearer hum_sk_live_..."

Webhooks for inbound mail

For real-time processing, configure a webhook endpoint to receive inbound email events. Humiris will POST a JSON payload to your URL every time a new message arrives.

bash

# Register a webhook for inbound email
curl -X POST https://api.humiris.com/v1/webhooks \
  -H "Authorization: Bearer hum_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/email",
    "events": ["email.received"],
    "agent": "alex-sdr"
  }'

The webhook payload includes the full message content:

json

{
  "event": "email.received",
  "agent": "alex-sdr",
  "data": {
    "id": "msg_abc123",
    "from": "customer@example.com",
    "to": "alex-sdr@acme.humiris.com",
    "subject": "Re: Following up",
    "body": "Thanks for reaching out! I'd love to learn more.",
    "received_at": "2026-04-06T14:30:00Z"
  }
}

Next steps

Set up Webhooks to handle inbound email events, or explore Agent Phone for SMS and voice capabilities. See the API Reference for the full email endpoint documentation.