Custom Domains

Custom domains are central to mailiam’s professional approach - every email, form, and interaction uses YOUR domain, never ours.

Overview

With mailiam, your custom domain becomes the foundation of your email infrastructure:

Professional branding: All emails come FROM your domain
Domain-based form endpoints: api.mailiam.dev/v1/yourdomain.com/send
Custom reply addresses: replies@yourdomain.com
SSL certificate management: Automatic HTTPS for your domain
DNS integration: Simple MX record setup

Domain Architecture

Understanding mailiam’s domain model is key to cost-effective email infrastructure.

Apex Domains vs Subdomains

mailiam uses a smart domain hierarchy built on AWS SES verification:

Apex Domain (Root Domain)

The base domain: example.com
Requires full DNS verification (MX, TXT, DKIM)
Counts toward your plan’s domain limit
Once verified, unlocks unlimited free subdomains

Subdomain (Under a Verified Apex)

Any prefix: mail.example.com, forms.example.com, api.example.com
Automatically inherits verification from the apex domain
Does not count toward your domain limit
No additional DNS setup required

Standalone Subdomain

A subdomain verified without its apex: mail.example.com (without example.com)
Counts as 1 domain toward your limit
Useful when you don’t control the apex

How Verification Inheritance Works

Verify apex domain: example.com
  ├── mail.example.com     → FREE (inherits from apex)
  ├── forms.example.com    → FREE (inherits from apex)
  ├── app.example.com      → FREE (inherits from apex)
  └── api.example.com      → FREE (inherits from apex)

This means:

Free tier (1 apex domain): 1 apex + unlimited subdomains = infinite possibilities
Pro tier (2 apex domains): 2 businesses, each with unlimited subdomains
Agency tier (unlimited): Any number of client domains

Domain Verification with AWS SES

mailiam uses AWS SES for email delivery. When you verify a domain:

DNS records are created in AWS SES
DKIM keys are generated for email authentication
Subdomains automatically inherit these credentials

# This single verification unlocks the entire family
domains:
  example.com:              # Verified apex - counts as 1 domain
    sender:
      name: "Example"
      email: "hello@example.com"

  # These subdomains are FREE and auto-verified:
  mail.example.com:         # Free - inherits from example.com
    sender:
      email: "noreply@mail.example.com"

  forms.example.com:        # Free - inherits from example.com
    forms:
      contact:
        recipient: "team@example.com"

Delegated Subdomains

For subdomains you control but don’t own the apex (e.g., yourcompany.clientdomain.com):

domains:
  yourcompany.clientdomain.com:
    type: delegated
    # This counts as 1 domain since apex isn't verified
    sender:
      name: "Your Company"
      email: "hello@yourcompany.clientdomain.com"

Cost Optimization Strategy

Recommended approach:

Always verify the apex domain first
Use subdomains for different services
Only verify standalone subdomains when you don’t control the apex

Example - Efficient setup:

# 1 apex domain = 1 counted domain
domains:
  mycompany.com:                    # Apex - counts
    forwarding:
      "*@mycompany.com": "team@gmail.com"

  forms.mycompany.com:              # FREE subdomain
    forms:
      contact: { recipient: "hello@mycompany.com" }

  mail.mycompany.com:               # FREE subdomain
    sender:
      email: "notifications@mail.mycompany.com"

  support.mycompany.com:            # FREE subdomain
    forwarding:
      "*@support.mycompany.com": "support-team@company.com"

This gives you 4 functional domains while only counting as 1 toward your limit!

Domain Setup

Basic Domain Configuration

domains:
  mycompany.com:
    forwarding:
      "*@mycompany.com": "team@gmail.com"
    forms:
      contact:
        template: "professional"
        replies: true
    settings:
      branding: true
      customSender: true

Domain Verification Process

Add domain to config and deploy:

mailiam init mycompany.com
mailiam push

mailiam provides DNS records:
- MX records for email forwarding
- TXT record for domain verification
- CNAME records for form endpoints
Update your DNS:

# MX Records (for email forwarding)
mycompany.com. MX 10 mx1.mailiam.dev.
mycompany.com. MX 20 mx2.mailiam.dev.

# TXT Record (for verification)
mycompany.com. TXT "mailiam-verify=abc123def456"

# CNAME (for API endpoints)
api.mycompany.com. CNAME api.mailiam.dev.

Verify ownership:

mailiam domains verify mycompany.com

Form Endpoints with Your Domain

Domain-Based Form URLs

Once verified, your forms use your domain:

<!-- Your branded endpoint -->
<form action="https://api.mailiam.dev/v1/mycompany.com/send" method="POST">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>

Multiple Form Types

domains:
  mycompany.com:
    forms:
      contact:
        template: "support"
        subject: "New Contact Form"
        replies: true
      newsletter:
        template: "marketing"
        subject: "Newsletter Signup"
        listId: "main-newsletter"
      support:
        template: "technical"
        subject: "Support Request"
        priority: "high"

Each form gets its endpoint:

Contact: https://api.mailiam.dev/v1/mycompany.com/send?form=contact
Newsletter: https://api.mailiam.dev/v1/mycompany.com/send?form=newsletter
Support: https://api.mailiam.dev/v1/mycompany.com/send?form=support

Professional Branding

Custom Sender Addresses

All emails sent through mailiam use your domain:

domains:
  mycompany.com:
    branding:
      fromName: "MyCompany Team"
      fromEmail: "noreply@mycompany.com"
      replyTo: "support@mycompany.com"
    templates:
      footer: |
        ---
        MyCompany Inc.
        123 Business St, City, State
        Unsubscribe: https://mycompany.com/unsubscribe

Custom Email Templates

Create branded email templates:

domains:
  mycompany.com:
    templates:
      contact:
        subject: "Thank you for contacting {{ company }}"
        html: |
          <div style="font-family: Arial, sans-serif;">
            <img src="https://mycompany.com/logo.png" alt="MyCompany" width="150">
            <h2>Thanks for reaching out!</h2>
            <p>Hi {{ name }},</p>
            <p>We received your message and will get back to you within 24 hours.</p>
            <div style="background: #f5f5f5; padding: 15px; border-left: 3px solid #007cba;">
              <strong>Your message:</strong><br>
              {{ message }}
            </div>
            <p>Best regards,<br>The MyCompany Team</p>
          </div>
        text: |
          Thanks for reaching out!

          Hi {{ name }},

          We received your message: "{{ message }}"

          We'll get back to you within 24 hours.

          Best regards,
          The MyCompany Team

Multi-Domain Management

Managing Multiple Domains

domains:
  mainsite.com:
    forwarding:
      "*@mainsite.com": "team@company.com"
    forms:
      contact:
        template: "main"

  blog.company.com:
    forwarding:
      "*@blog.company.com": "editorial@company.com"
    forms:
      subscription:
        template: "blog"
        listId: "blog-subscribers"

  app.company.com:
    forwarding:
      "support@app.company.com": "app-support@company.com"
    forms:
      feedback:
        template: "app"
        priority: "high"

Domain-Specific Settings

Each domain can have different configurations:

domains:
  enterprise.com:
    security:
      spamProtection: "strict"
      rateLimit: 50
      requireRecaptcha: true
    branding:
      customSender: true
      trackOpens: false      # Privacy-focused

  marketing.com:
    security:
      spamProtection: "normal"
      rateLimit: 1000
    branding:
      trackOpens: true       # Marketing analytics
      trackClicks: true

SSL Certificate Management

Automatic HTTPS

mailiam automatically provisions and renews SSL certificates for your domain endpoints:

Let’s Encrypt integration for free certificates
Automatic renewal 30 days before expiration
Multiple domain support with SAN certificates
Wildcard support for subdomain coverage

Certificate Status

# Check certificate status
mailiam domains ssl-status mycompany.com

# Force certificate renewal
mailiam domains ssl-renew mycompany.com

# View certificate details
mailiam domains ssl-info mycompany.com

DNS Integration

Required DNS Records

For complete integration, add these DNS records:

# Email forwarding (MX records)
mycompany.com. MX 10 mx1.mailiam.dev.
mycompany.com. MX 20 mx2.mailiam.dev.

# Domain verification (TXT record)
mycompany.com. TXT "mailiam-verify=your-verification-token"

# API endpoint (CNAME) - Optional but recommended
api.mycompany.com. CNAME api.mailiam.dev.

# SPF record for email deliverability
mycompany.com. TXT "v=spf1 include:_spf.mailiam.dev ~all"

# DKIM for email authentication (provided after verification)
default._domainkey.mycompany.com. CNAME default._domainkey.mailiam.dev.

DNS Validation

# Check DNS propagation
mailiam domains check-dns mycompany.com

# Validate all records
mailiam domains validate mycompany.com

# Get recommended DNS settings
mailiam domains dns-config mycompany.com

Advanced Domain Features

Subdomain Support

Configure subdomains for different purposes:

domains:
  # Main domain
  company.com:
    forwarding:
      "*@company.com": "general@company.com"

  # Support subdomain
  support.company.com:
    forwarding:
      "*@support.company.com": "support-team@company.com"
    forms:
      ticket:
        template: "support"
        priority: "high"

  # Marketing subdomain
  marketing.company.com:
    forms:
      newsletter:
        template: "marketing"
        listId: "newsletter"
      webinar:
        template: "events"
        listId: "webinar-signups"

International Domains

mailiam supports international domain names (IDN):

domains:
  münchen.company.com:    # German umlaut
    forwarding:
      "*@münchen.company.com": "germany@company.com"

  企业.company.com:        # Chinese characters
    forwarding:
      "*@企业.company.com": "china@company.com"

Performance Optimization

Global Edge Deployment

Your domain endpoints are deployed globally:

150+ edge locations worldwide
Sub-100ms response times in most regions
Automatic failover between regions
Real-time health monitoring

Caching Configuration

domains:
  mycompany.com:
    performance:
      cacheControl: "public, max-age=300"  # 5-minute cache
      compression: true                    # Enable gzip
      http2: true                         # HTTP/2 support
      prefetch: ["css", "js", "images"]   # Resource prefetching

CLI Commands

Domain Management

# List all domains
mailiam domains list

# Add a new domain
mailiam domains add mycompany.com

# Verify domain ownership
mailiam domains verify mycompany.com

# Check domain status
mailiam domains status mycompany.com

# Remove a domain
mailiam domains remove mycompany.com

Configuration Management

# Show domain configuration
mailiam domains show mycompany.com

# Update domain settings
mailiam domains update mycompany.com --branding=true

# Test domain setup
mailiam domains test mycompany.com

Security Considerations

Domain Security

DNS SEC validation when available
Certificate pinning for API endpoints
Domain ownership verification required
SPF/DKIM authentication for emails

Access Control

domains:
  secure.company.com:
    security:
      restrictedAccess: true
      allowedOrigins:
        - "https://company.com"
        - "https://app.company.com"
      apiKeyRequired: true
      corsPolicy: "strict"

Migration from Other Services

From Existing Email Services

Set up mailiam domain without changing DNS
Test thoroughly with mailiam endpoints
Gradually migrate MX records
Monitor email delivery during transition

# Migration helper commands
mailiam migration plan mycompany.com
mailiam migration test mycompany.com
mailiam migration execute mycompany.com --phase=1

Domain Transfer Checklist

Troubleshooting

Common Issues

Domain verification failed:

# Check DNS propagation
dig TXT mycompany.com
mailiam domains check-dns mycompany.com

SSL certificate issues:

# Check certificate status
mailiam domains ssl-status mycompany.com

# View certificate logs
mailiam logs ssl mycompany.com --last 24h

Email delivery problems:

# Test email routing
mailiam domains test-email mycompany.com test@mycompany.com

# Check SPF/DKIM setup
mailiam domains check-auth mycompany.com

Best Practices

Use subdomains for different services (api.domain.com, forms.domain.com)
Set up SPF/DKIM immediately after domain verification
Monitor certificate expiration with alerts
Test thoroughly before switching DNS
Keep DNS records documented for your team
Use version control for domain configurations

Your domain is your brand - mailiam ensures every email interaction reinforces your professional identity.