Aexy Email Infrastructure - Aexy Docs

This guide covers how to configure the default *.aexy.email domain infrastructure for self-hosted Aexy deployments.

Overview#

Aexy provides each workspace with a default email domain in the format {workspace-slug}.aexy.email. This enables AI agents to have their own email addresses (e.g., support@acme.aexy.email) without requiring users to configure custom domains.

┌─────────────────────────────────────────────────────────────────────────┐
│                      Aexy Email Infrastructure                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Inbound Flow:                                                           │
│  ┌──────────┐    ┌─────────────┐    ┌────────────┐    ┌─────────────┐  │
│  │  Email   │───▶│  MX Record  │───▶│  Mailagent │───▶│  AI Agent   │  │
│  │  Sender  │    │  (SES/etc)  │    │  Service   │    │  Processor  │  │
│  └──────────┘    └─────────────┘    └────────────┘    └─────────────┘  │
│                                                                          │
│  Outbound Flow:                                                          │
│  ┌──────────┐    ┌─────────────┐    ┌────────────┐    ┌─────────────┐  │
│  │ AI Agent │───▶│   Routing   │───▶│  Provider  │───▶│  Recipient  │  │
│  │ Response │    │   Service   │    │  (SES/SG)  │    │             │  │
│  └──────────┘    └─────────────┘    └────────────┘    └─────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Prerequisites#

A domain for your Aexy deployment (e.g., aexy.email or mail.yourdomain.com)
Access to DNS management for the domain
An email provider account (Amazon SES recommended)
A server to run the mailagent service

DNS Configuration#

1. MX Records (Inbound Email)#

Configure MX records to route incoming emails to your email provider:

# For Amazon SES (US East 1)
aexy.email.    MX    10    inbound-smtp.us-east-1.amazonaws.com.

# For Amazon SES (EU West 1)
aexy.email.    MX    10    inbound-smtp.eu-west-1.amazonaws.com.

# Wildcard for workspace subdomains
*.aexy.email.  MX    10    inbound-smtp.us-east-1.amazonaws.com.

2. SPF Record (Sender Authorization)#

Add SPF records to authorize your email providers:

# Single provider (SES)
aexy.email.    TXT   "v=spf1 include:amazonses.com ~all"

# Multiple providers
aexy.email.    TXT   "v=spf1 include:amazonses.com include:sendgrid.net include:mailgun.org ~all"

# Wildcard for subdomains
*.aexy.email.  TXT   "v=spf1 include:amazonses.com ~all"

3. DKIM Records (Email Signing)#

DKIM records are provider-specific and generated when you verify your domain:

Amazon SES:

# SES generates 3 CNAME records like:
abc123._domainkey.aexy.email.  CNAME  abc123.dkim.amazonses.com.
def456._domainkey.aexy.email.  CNAME  def456.dkim.amazonses.com.
ghi789._domainkey.aexy.email.  CNAME  ghi789.dkim.amazonses.com.

SendGrid:

s1._domainkey.aexy.email.  CNAME  s1.domainkey.u12345.wl.sendgrid.net.
s2._domainkey.aexy.email.  CNAME  s2.domainkey.u12345.wl.sendgrid.net.

4. DMARC Record (Policy)#

Add a DMARC record to specify how receiving servers should handle authentication failures:

_dmarc.aexy.email.  TXT  "v=DMARC1; p=quarantine; rua=mailto:dmarc-reports@aexy.email; pct=100"

DMARC Policy Options:

p=none - Monitor only, don't reject
p=quarantine - Send failures to spam
p=reject - Reject authentication failures

5. Return-Path / Bounce Handling#

For proper bounce handling, configure a custom return-path subdomain:

bounce.aexy.email.  MX    10  feedback-smtp.us-east-1.amazonses.com.
bounce.aexy.email.  TXT   "v=spf1 include:amazonses.com ~all"

Email Provider Setup#

Amazon SES Configuration#

Verify the Domain

aws ses verify-domain-identity --domain aexy.email
aws ses verify-domain-dkim --domain aexy.email

Request Production Access
- New SES accounts are in sandbox mode (limited sending)
- Request production access via AWS console

Configure Inbound Email Receipt

# Create an S3 bucket for email storage (optional)
aws s3 mb s3://aexy-email-inbound

# Create receipt rule set
aws ses create-receipt-rule-set --rule-set-name aexy-inbound

# Create receipt rule to forward to mailagent
aws ses create-receipt-rule \
  --rule-set-name aexy-inbound \
  --rule '{
    "Name": "forward-to-mailagent",
    "Enabled": true,
    "Recipients": ["aexy.email"],
    "Actions": [{
      "SNSAction": {
        "TopicArn": "arn:aws:sns:us-east-1:123456789:aexy-email-inbound",
        "Encoding": "UTF-8"
      }
    }]
  }'

Set Active Receipt Rule Set

aws ses set-active-receipt-rule-set --rule-set-name aexy-inbound

SendGrid Configuration#

Authenticate Domain
- Go to Settings > Sender Authentication
- Add domain aexy.email
- Add the provided DNS records
Configure Inbound Parse
- Go to Settings > Inbound Parse
- Add aexy.email pointing to your mailagent webhook URL

Mailgun Configuration#

Add Domain
- Go to Sending > Domains > Add New Domain
- Add aexy.email
- Configure DNS records as shown

Configure Routes for Inbound

Expression: match_recipient(".*@.*\.aexy\.email")
Action: forward("https://your-mailagent-url/webhook/inbound")

Mailagent Service Configuration#

The mailagent service handles inbound email processing and AI-powered responses.

Environment Variables#

# Mailagent Service
MAILAGENT_PORT=8001
MAILAGENT_HOST=0.0.0.0

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/aexy

# Aexy Backend API
AEXY_API_URL=http://localhost:8000/api/v1
AEXY_API_KEY=your-internal-api-key

# Email Provider for Outbound
DEFAULT_EMAIL_PROVIDER=ses
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

# Inbound Webhook Secret (for verifying provider webhooks)
INBOUND_WEBHOOK_SECRET=your-webhook-secret

# LLM Provider for AI Processing
LLM_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-...

Docker Compose Configuration#

services:
  mailagent:
    build: ./mailagent
    ports:
      - "8001:8001"
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - AEXY_API_URL=http://backend:8000/api/v1
      - AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}
      - AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_REGION=${AWS_REGION}
    depends_on:
      - postgres
      - backend

Webhook Endpoints#

Configure your email provider to send inbound emails to these endpoints:

Provider	Webhook URL
Amazon SES (SNS)	`https://mailagent.yourdomain.com/webhook/ses`
SendGrid	`https://mailagent.yourdomain.com/webhook/sendgrid`
Mailgun	`https://mailagent.yourdomain.com/webhook/mailgun`
Postmark	`https://mailagent.yourdomain.com/webhook/postmark`

Backend Configuration#

Environment Variables#

# Default Email Domain
DEFAULT_EMAIL_DOMAIN=aexy.email

# Mailagent Service URL
MAILAGENT_URL=http://mailagent:8001

# Email Provider (fallback for outbound)
EMAIL_PROVIDER_TYPE=ses
AWS_SES_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

Database Configuration#

Run the email infrastructure migrations:

# Via Docker
docker exec aexy-backend python scripts/run_migrations.py

# Migrations include:
# - migrate_email_infrastructure.sql
# - migrate_agent_email.sql

Testing the Setup#

1. Verify DNS Records#

# Check MX record
dig MX aexy.email

# Check SPF record
dig TXT aexy.email

# Check DKIM
dig TXT abc123._domainkey.aexy.email

# Check DMARC
dig TXT _dmarc.aexy.email

2. Test Outbound Email#

# Send a test email via the API
curl -X POST "https://api.yourdomain.com/api/v1/email/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "test@example.com",
    "subject": "Test Email",
    "body": "This is a test email from Aexy"
  }'

3. Test Inbound Email#

Create a test agent with email enabled
Send an email to agent-handle@workspace-slug.aexy.email
Check the agent's inbox in the UI or via API

# Check agent inbox
curl "https://api.yourdomain.com/api/v1/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/inbox" \
  -H "Authorization: Bearer $TOKEN"

4. Verify Email Authentication#

Use email testing tools to verify SPF/DKIM/DMARC:

Production Checklist#

DNS records configured (MX, SPF, DKIM, DMARC)
Email provider domain verified
SES production access approved (if using SES)
Inbound email webhook configured
Mailagent service deployed and healthy
SSL certificates configured for webhook endpoints
Bounce/complaint handling configured
Monitoring and alerting set up
Email authentication passing (SPF, DKIM, DMARC)

Troubleshooting#

Inbound Emails Not Received#

Check MX records - Ensure they point to your provider
Verify SES receipt rules - Make sure the rule set is active
Check mailagent logs - Look for webhook errors
Verify SNS subscription - Confirm the endpoint is subscribed

# Check mailagent logs
docker logs aexy-mailagent -f --tail 100

Outbound Emails Bouncing#

Check sender domain verification - Domain must be verified in SES
Verify SPF/DKIM - Use mail-tester.com to check
Check SES sandbox mode - Request production access if needed
Review bounce logs - Check for hard bounces

# Check SES sending statistics
aws ses get-send-statistics

DMARC Failures#

Alignment issues - Ensure From domain matches SPF/DKIM domain
Missing DKIM - Verify DKIM records are published
SPF failures - Check all sending IPs are in SPF record

Agent Not Processing Emails#

Check agent email is enabled - Verify in agent settings
Check routing rules - Ensure email routes to correct agent
Check mailagent health - Verify service is running
Review processing logs - Look for AI errors

# Health check
curl https://mailagent.yourdomain.com/health

Email Marketing - Campaign and template management
AI Agents - Agent configuration and tools
Deployment Guide - General deployment instructions

Overview#

Prerequisites#

DNS Configuration#

1. MX Records (Inbound Email)#

2. SPF Record (Sender Authorization)#

3. DKIM Records (Email Signing)#

4. DMARC Record (Policy)#

5. Return-Path / Bounce Handling#

Email Provider Setup#

Amazon SES Configuration#

SendGrid Configuration#

Mailgun Configuration#

Mailagent Service Configuration#

Environment Variables#

Docker Compose Configuration#

Webhook Endpoints#

Backend Configuration#

Environment Variables#

Database Configuration#

Testing the Setup#

1. Verify DNS Records#

2. Test Outbound Email#

3. Test Inbound Email#

4. Verify Email Authentication#

Production Checklist#

Troubleshooting#

Inbound Emails Not Received#

Outbound Emails Bouncing#

DMARC Failures#

Agent Not Processing Emails#

Related Documentation#