Configuration Overview

The mailiam.config.yaml file is your email infrastructure as code - a single configuration file that defines domains, forms, collections, and projects.

Philosophy

mailiam treats email infrastructure like modern development treats application infrastructure:

• Configuration as Code - Your email setup lives in version control
• Declarative Configuration - Describe what you want, not how to achieve it
• Environment Parity - Same config structure across dev, staging, production
• Git Workflow - Changes are reviewed, tested, and deployed like code

Basic Structure

# mailiam.config.yaml - The complete structure

# Domain-based email infrastructure
domains:
  mysite.com:
    forwarding:
      "*@mysite.com": "me@gmail.com"
    forms:
      contact:
        template: "professional"
        replies: true
    projects:
      main:
        templates: "./templates/"
        branding: "./brand/"

# Form collections for organization
collections:
  company:
    name: "Company Forms"
    settings:
      rateLimit: 100
      spamProtection: true
    forms:
      support:
        name: "Support Form"
        email: "support@company.com"

# Global settings
settings:
  defaultRegion: "us-east-1"
  timeout: 30000
  retries: 3

# Environment variables
env:
  production:
    apiEndpoint: "https://api.mailiam.dev"
  staging:
    apiEndpoint: "https://staging-api.mailiam.dev"

Configuration Sections

Domains

The domains section defines your custom domain-based email infrastructure:

domains:
  mycompany.com:
    # Email forwarding rules
    forwarding:
      "*@mycompany.com": "team@gmail.com"
      "support@mycompany.com": "help@company.com"

    # Domain-based forms
    forms:
      contact:
        template: "professional"
        replies: true
        replyTo: "support@mycompany.com"

    # Project organization
    projects:
      main:
        name: "Main Website"
        templates: "./templates/"
        branding: "./branding/"

    # Domain settings
    settings:
      spamProtection: "strict"
      rateLimit: 100
      trackOpens: true

Collections

The collections section organizes forms under namespaced URLs:

collections:
  # Collection slug (used in URLs)
  support:
    name: "Support Forms"
    description: "Customer support and help forms"

    # Collection-level settings
    settings:
      rateLimit: 50
      spamProtection: true
      requireApiKey: false

    # Forms within collection
    forms:
      technical:
        name: "Technical Support"
        email: "tech-support@company.com"
        settings:
          rateLimitPerMinute: 5
          customMessage: "We'll respond within 4 hours"

      billing:
        name: "Billing Questions"
        email: "billing@company.com"
        settings:
          customMessage: "Billing team will respond within 24 hours"

Global Settings

settings:
  # Default region for deployments
  defaultRegion: "us-east-1"

  # Request timeout (milliseconds)
  timeout: 30000

  # Number of retries for failed requests
  retries: 3

  # Default rate limiting
  defaultRateLimit: 100

  # Global spam protection level
  defaultSpamProtection: "normal"

  # Enable analytics by default
  enableAnalytics: true

  # Default cache settings
  caching:
    enabled: true
    ttl: 3600

Configuration Workflows

Initialize New Project

# Create new project with domain
mailiam init mycompany.com

# This creates:
# - mailiam.config.yaml
# - .mailiam/ directory for local state
# - templates/ directory (if --templates flag used)
# - .gitignore with mailiam-specific entries

Edit Configuration

# Edit main configuration
vim mailiam.config.yaml

# Validate syntax before deploying
mailiam config validate

# Preview changes without deploying
mailiam push --dry-run

Deploy Changes

# Deploy to production
mailiam push

# Deploy to specific environment
mailiam push --env staging

# Deploy with verbose output
mailiam push --verbose

Sync Remote Changes

# Pull latest configuration from remote
mailiam pull

# Pull specific environment
mailiam pull --env staging

# Force overwrite local changes
mailiam pull --force

Environment Management

Environment-Specific Configs

# File structure for multiple environments
mailiam.config.yaml          # Production (default)
mailiam.config.dev.yaml      # Development
mailiam.config.staging.yaml  # Staging
mailiam.config.test.yaml     # Testing

Environment Variables

# Use environment variables in configuration
domains:
  mysite.com:
    forwarding:
      "*@mysite.com": "{{ env.ADMIN_EMAIL }}"
    forms:
      contact:
        webhookUrl: "{{ env.WEBHOOK_URL }}"

# Environment-specific values
env:
  production:
    ADMIN_EMAIL: "admin@company.com"
    WEBHOOK_URL: "https://app.company.com/webhook"
  staging:
    ADMIN_EMAIL: "staging@company.com"
    WEBHOOK_URL: "https://staging.company.com/webhook"

Deploy to Environments

# Development
mailiam push --env dev

# Staging
mailiam push --env staging

# Production (default)
mailiam push
mailiam push --env production

Advanced Configuration

Template and Asset Paths

domains:
  mycompany.com:
    projects:
      main:
        # Relative paths from config file
        templates: "./templates/"
        branding: "./assets/branding/"

        # Absolute paths
        templates: "/usr/src/app/templates/"

        # Remote URLs
        templates: "https://cdn.company.com/email-templates/"

Conditional Configuration

domains:
  mycompany.com:
    forms:
      contact:
        # Different settings based on environment
        settings:
          spamProtection: "{{ env.NODE_ENV == 'production' ? 'strict' : 'normal' }}"
          rateLimit: "{{ env.NODE_ENV == 'development' ? 1000 : 50 }}"

        # Conditional features
        features:
          analytics: "{{ env.ENABLE_ANALYTICS | default(true) }}"
          debugging: "{{ env.NODE_ENV == 'development' }}"

Includes and Modularity

# Main configuration
domains:
  mycompany.com:
    # Include external configuration files
    forwarding: !include forwarding.yaml
    forms: !include forms/forms.yaml
    projects: !include projects/projects.yaml

# forwarding.yaml
"*@mycompany.com": "team@gmail.com"
"support@mycompany.com": "help@company.com"

# forms/forms.yaml
contact:
  template: "professional"
  replies: true
newsletter:
  template: "marketing"
  listId: "main-newsletter"

Configuration Validation

Schema Validation

# Validate configuration syntax
mailiam config validate

# Validate against specific schema version
mailiam config validate --schema-version 2.0

# Strict validation (catch warnings as errors)
mailiam config validate --strict

Pre-deployment Checks

# Check configuration and preview changes
mailiam push --dry-run

# Validate all referenced files exist
mailiam config validate --check-files

# Test configuration against staging environment
mailiam config test --env staging

Common Validation Errors

# ❌ Invalid YAML syntax
domains:
  mysite.com
    forwarding:  # Missing colon after domain

# ❌ Invalid email format
forwarding:
  "*@mysite.com": "not-an-email"

# ❌ Duplicate keys
forms:
  contact:
    template: "professional"
  contact:  # Duplicate key
    template: "casual"

# ❌ Missing required fields
collections:
  support:  # Missing 'name' field
    forms:
      tech: {}  # Missing form name

Version Control Integration

Git Workflow

# 1. Create feature branch
git checkout -b add-newsletter-form

# 2. Update configuration
vim mailiam.config.yaml

# 3. Test changes
mailiam push --env dev --dry-run

# 4. Deploy to development
mailiam push --env dev

# 5. Commit changes
git add mailiam.config.yaml
git commit -m "Add newsletter signup form"

# 6. Create pull request
git push origin add-newsletter-form

# 7. After review, deploy to production
mailiam push --env production

.gitignore Recommendations

# mailiam local state
.mailiam/
mailiam.lock

# Environment-specific files (if they contain secrets)
mailiam.config.*.yaml
!mailiam.config.example.yaml

# Template compilation cache
templates/.cache/
templates/dist/

# Logs
mailiam.log
*.log

Secrets Management

# ❌ Don't commit secrets
domains:
  mysite.com:
    webhooks:
      url: "https://api.service.com/webhook"
      apiKey: "sk-1234567890abcdef"  # Don't do this!

# ✅ Use environment variables
domains:
  mysite.com:
    webhooks:
      url: "{{ env.WEBHOOK_URL }}"
      apiKey: "{{ env.WEBHOOK_API_KEY }}"

CLI Configuration Commands

View Configuration

# Show current configuration
mailiam config show

# Show specific section
mailiam config show domains.mysite.com

# Show in different formats
mailiam config show --output json
mailiam config show --output yaml

Edit Configuration

# Edit with default editor
mailiam config edit

# Edit with specific editor
mailiam config edit --editor code

# Edit specific environment
mailiam config edit --env staging

Configuration Management

# Set configuration values
mailiam config set domains.mysite.com.settings.rateLimit 200

# Get specific values
mailiam config get domains.mysite.com.forwarding

# Reset to defaults
mailiam config reset

# Import configuration from file
mailiam config import backup.yaml

Best Practices

1. Configuration Structure

• Keep it organized - Use clear sections and consistent indentation
• Document complex rules - Add comments explaining business logic
• Use meaningful names - Form and collection names should be descriptive
• Group related items - Keep similar forms/settings together

2. Environment Management

• Start simple - Begin with single config, add environments as needed
• Use environment variables - Keep secrets out of configuration files
• Test before deploying - Always validate and dry-run changes
• Document environments - Maintain clear documentation of env differences

3. Version Control

• Commit frequently - Small, focused changes are easier to review
• Write clear commit messages - Explain what changed and why
• Use pull requests - Get team review for configuration changes
• Tag releases - Mark stable configurations with version tags

4. Validation and Testing

• Validate locally - Run mailiam config validate before committing
• Test in staging - Deploy to staging environment first
• Monitor deployments - Check status after deploying changes
• Keep backups - Maintain working configuration backups

Your mailiam.config.yaml file is the single source of truth for your email infrastructure - treat it with the same care you give to application code.