Environment Configuration

Environment Configuration

Learn how to manage mailiam configurations across development, staging, and production environments.

Overview

mailiam supports multiple approaches for managing environment-specific configurations:

1. Environment Variables - Dynamic values at runtime
2. Multiple Config Files - Separate files per environment
3. Conditional Configuration - Environment-based logic in single file
4. CI/CD Integration - Automated deployment workflows

Environment Variables

Basic Usage

Reference environment variables in your mailiam.config.yaml:

project:
  name: "${PROJECT_NAME:-My Application}"
  slug: "${PROJECT_SLUG:-my-app}"

domains:
  "${DOMAIN}":
    forwarding:
      "hello@${DOMAIN}": "${ADMIN_EMAIL}"
      "support@${DOMAIN}": "${SUPPORT_EMAIL}"

    forms:
      contact:
        name: "Contact Form"
        replyTo: "${CONTACT_EMAIL}"

templates:
  branded:
    variables:
      company_name: "${COMPANY_NAME:-My Company}"
      api_url: "${API_URL:-https://api.example.com}"

Environment Variable Patterns

Development

export PROJECT_NAME="My App (Dev)"
export DOMAIN="dev.example.com"
export ADMIN_EMAIL="dev-admin@example.com"
export MAILIAM_API_KEY="mlm_dev_your_key_here"

Staging

export PROJECT_NAME="My App (Staging)"
export DOMAIN="staging.example.com"
export ADMIN_EMAIL="staging-admin@example.com"
export MAILIAM_API_KEY="mlm_staging_your_key_here"

Production

export PROJECT_NAME="My App"
export DOMAIN="example.com"
export ADMIN_EMAIL="admin@example.com"
export MAILIAM_API_KEY="mlm_prod_your_key_here"

Default Values

Provide fallback values using the ${VAR:-default} syntax:

settings:
  rate_limit: "${RATE_LIMIT:-10}"
  spam_protection: "${SPAM_PROTECTION:-true}"
  sending_mode: "${SENDING_MODE:-standard}"

domains:
  "${DOMAIN:-localhost}":
    forms:
      contact:
        name: "${FORM_NAME:-Contact Form}"
        rateLimit: "${FORM_RATE_LIMIT:-5}"

Multiple Configuration Files

File Structure

project/
├── mailiam.config.yaml          # Base configuration
├── mailiam.dev.yaml            # Development overrides
├── mailiam.staging.yaml        # Staging overrides
├── mailiam.prod.yaml           # Production configuration
└── environments/
    ├── development.yaml
    ├── staging.yaml
    └── production.yaml

Base Configuration

mailiam.config.yaml:

project:
  name: "My Application"
  slug: "my-app"

# Shared templates
templates:
  default:
    type: "form"
    subject: "New contact from {{ form.name }}"
    text: |
      Name: {{ form.name }}
      Email: {{ form.email }}
      Message: {{ form.message }}

Environment-Specific Files

mailiam.dev.yaml:

project:
  name: "My Application (Dev)"

domains:
  dev.example.com:
    forwarding:
      "*@dev.example.com": "dev-team@company.com"
    forms:
      contact:
        name: "Dev Contact Form"
        rateLimit: 100  # Higher limit for testing

settings:
  spam_protection: false  # Disabled for easier testing
  rate_limit: 100

mailiam.prod.yaml:

project:
  name: "My Application"

domains:
  example.com:
    forwarding:
      "hello@example.com": "team@company.com"
      "support@example.com": "support@company.com"
    forms:
      contact:
        name: "Contact Form"
        rateLimit: 10
        acknowledgment:
          enabled: true
          template: "professional"

settings:
  spam_protection: true
  rate_limit: 10
  enableAnalytics: true

Using Environment-Specific Files

# Deploy development configuration
cp mailiam.dev.yaml mailiam.config.yaml
mailiam push

# Deploy production configuration
cp mailiam.prod.yaml mailiam.config.yaml
mailiam push

Conditional Configuration

Use environment variables to enable conditional logic:

project:
  name: "My App${NODE_ENV == 'production' ? '' : ' (' + NODE_ENV + ')'}"

domains:
  # Use different domains based on environment
  "${NODE_ENV == 'production' ? 'example.com' : NODE_ENV + '.example.com'}":
    forwarding:
      # Different email destinations per environment
      "admin@${DOMAIN}": "${NODE_ENV == 'production' ? 'admin@company.com' : 'dev-team@company.com'}"

    forms:
      contact:
        name: "Contact Form"
        # Relaxed rate limiting in development
        rateLimit: "${NODE_ENV == 'production' ? 10 : 100}"

settings:
  # Disable spam protection in development
  spam_protection: "${NODE_ENV != 'development'}"
  # Enable analytics only in production
  enableAnalytics: "${NODE_ENV == 'production'}"

API Key Management

Per-Environment Keys

Use different API keys for each environment:

Development

# ~/.bashrc or ~/.zshrc
export MAILIAM_API_KEY_DEV="mlm_dev_abc123..."

# For development work
export MAILIAM_API_KEY="$MAILIAM_API_KEY_DEV"

Production

# Production server or CI/CD
export MAILIAM_API_KEY_PROD="mlm_prod_xyz789..."

# For production deployment
export MAILIAM_API_KEY="$MAILIAM_API_KEY_PROD"

Environment Scripts

Create helper scripts for switching environments:

scripts/dev.sh:

#!/bin/bash
export NODE_ENV=development
export MAILIAM_API_KEY="mlm_dev_your_key_here"
export DOMAIN="dev.example.com"
export ADMIN_EMAIL="dev@company.com"

echo "Environment set to development"
mailiam auth status

scripts/prod.sh:

#!/bin/bash
export NODE_ENV=production
export MAILIAM_API_KEY="mlm_prod_your_key_here"
export DOMAIN="example.com"
export ADMIN_EMAIL="admin@company.com"

echo "Environment set to production"
mailiam auth status

Usage:

source scripts/dev.sh
mailiam push

source scripts/prod.sh
mailiam push

CI/CD Integration

GitHub Actions

.github/workflows/deploy.yml:

name: Deploy mailiam Configuration

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy-staging:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install mailiam CLI
        run: npm install -g mailiam
      - name: Deploy to staging
        env:
          MAILIAM_API_KEY: ${{ secrets.MAILIAM_STAGING_API_KEY }}
          NODE_ENV: staging
          DOMAIN: staging.example.com
          ADMIN_EMAIL: staging@company.com
        run: |
          mailiam push --dry-run  # Preview changes first
          mailiam push

  deploy-production:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install mailiam CLI
        run: npm install -g mailiam
      - name: Deploy to production
        env:
          MAILIAM_API_KEY: ${{ secrets.MAILIAM_PRODUCTION_API_KEY }}
          NODE_ENV: production
          DOMAIN: example.com
          ADMIN_EMAIL: admin@company.com
        run: |
          mailiam test config  # Validate configuration
          mailiam push

Secrets Management

Store sensitive values as secrets in your CI/CD system:

GitHub Secrets

• MAILIAM_STAGING_API_KEY
• MAILIAM_PRODUCTION_API_KEY
• ADMIN_EMAIL_PROD
• SUPPORT_EMAIL_PROD

Accessing Secrets in Configuration

domains:
  "${DOMAIN}":
    forwarding:
      "admin@${DOMAIN}": "${ADMIN_EMAIL}"
      "support@${DOMAIN}": "${SUPPORT_EMAIL}"

Environment-Specific DNS

Development DNS

For local development, use test domains:

# Development
domains:
  localhost:
    forms:
      contact:
        name: "Local Contact Form"
        # For local testing, disable rate limits
        rateLimit: 1000

Staging DNS

Use staging subdomains:

# Staging
domains:
  staging.example.com:
    forwarding:
      "*@staging.example.com": "staging-team@company.com"
    forms:
      contact:
        name: "Staging Contact Form"
        # Similar to production but with higher limits for testing
        rateLimit: 50

Production DNS

Production domains with proper configuration:

# Production
domains:
  example.com:
    forwarding:
      "hello@example.com": "team@company.com"
      "support@example.com": "support@company.com"
    forms:
      contact:
        name: "Contact Form"
        rateLimit: 10
        acknowledgment:
          enabled: true

Testing Across Environments

Configuration Validation

Test configurations before deployment:

# Test development config
NODE_ENV=development mailiam test config

# Test production config
NODE_ENV=production mailiam test config

# Dry run deployment
mailiam push --dry-run

Email Testing

Test email functionality per environment:

# Development
mailiam test send dev-test@company.com

# Staging
mailiam test send staging-test@company.com

# Production (be careful!)
mailiam test send admin@company.com

Environment Variables Reference

Standard Environment Variables

Variable	Description	Example
NODE_ENV	Environment name	development, staging, production
MAILIAM_API_KEY	mailiam API key	mlm_abc123...
DOMAIN	Primary domain	example.com
ADMIN_EMAIL	Administrator email	admin@company.com
SUPPORT_EMAIL	Support email	support@company.com

Custom Variables

Create your own environment variables:

project:
  name: "${APP_NAME:-My App}"

domains:
  "${PRIMARY_DOMAIN}":
    forwarding:
      "contact@${PRIMARY_DOMAIN}": "${CONTACT_DESTINATION}"
      "sales@${PRIMARY_DOMAIN}": "${SALES_DESTINATION}"

Best Practices

1. Separate Concerns

• Use different API keys per environment
• Use environment-specific domains
• Configure appropriate rate limits per environment

2. Security

# Never commit secrets
echo "*.env" >> .gitignore
echo "mailiam.prod.yaml" >> .gitignore

# Use secrets management in CI/CD
# Store API keys as encrypted secrets

3. Testing

# Always test configuration changes
mailiam test config

# Use dry-run for production deployments
mailiam push --dry-run

# Validate email functionality
mailiam test send your-email@company.com

4. Documentation

Document your environment setup:

README.md:

## Environment Setup

### Development
```bash
cp environments/development.yaml mailiam.config.yaml
export MAILIAM_API_KEY="mlm_dev_..."
mailiam push

Production

cp environments/production.yaml mailiam.config.yaml
export MAILIAM_API_KEY="mlm_prod_..."
mailiam push

### 5. Monitoring

Monitor different environments separately:

```yaml
settings:
  # Enable analytics per environment
  enableAnalytics: "${NODE_ENV == 'production'}"

  # Different rate limits per environment
  rate_limit: "${NODE_ENV == 'production' ? 10 : 100}"

Troubleshooting

Environment Variable Not Found

# Check if variable is set
echo $DOMAIN

# List all mailiam-related variables
env | grep MAILIAM

Wrong Configuration Deployed

# Check current environment
mailiam auth status

# Verify configuration
mailiam test config

# Roll back if needed
git checkout HEAD~1 -- mailiam.config.yaml
mailiam push

API Key Issues

# Check which key is being used
mailiam auth status

# Switch to correct environment key
export MAILIAM_API_KEY="$MAILIAM_API_KEY_PROD"
mailiam auth status

Next Steps

• Configuration Schema Reference - Complete configuration options
• CLI Commands - Available CLI commands
• Domain Management - Setting up domains
• Security Best Practices - Securing your setup