Skip to content
mailiam Docs

Projects & Templates

Projects are mailiam’s organizational layer for managing domain-based email infrastructure with custom templates, branding, and professional workflows.

Overview

Section titled “Overview”

Projects in mailiam provide:

  • Domain-based organization - Group email infrastructure by domain
  • Custom email templates - Professional, branded email designs
  • Reply management - Enable real conversations with reply-to addresses
  • Brand consistency - Unified styling and messaging across all emails
  • Template inheritance - Reusable templates across multiple forms

Project Structure

Section titled “Project Structure”

Basic Project Configuration

Section titled “Basic Project Configuration”
mailiam.config.yaml
domains:
  mycompany.com:
    projects:
      main:
        name: "Main Website"
        description: "Primary company website communications"
        templates: "./templates/"
        branding: "./branding/"
        settings:
          defaultFrom: "MyCompany <noreply@mycompany.com>"
          replyTo: "support@mycompany.com"
          trackOpens: true
          trackClicks: true

Multi-Project Setup

Section titled “Multi-Project Setup”
domains:
  mycompany.com:
    projects:
      marketing:
        name: "Marketing Campaigns"
        templates: "./templates/marketing/"
        branding: "./branding/marketing/"
        settings:
          defaultFrom: "MyCompany Marketing <marketing@mycompany.com>"
          replyTo: "marketing@mycompany.com"


      support:
        name: "Customer Support"
        templates: "./templates/support/"
        branding: "./branding/support/"
        settings:
          defaultFrom: "MyCompany Support <support@mycompany.com>"
          replyTo: "support@mycompany.com"
          priority: "high"


      product:
        name: "Product Communications"
        templates: "./templates/product/"
        settings:
          defaultFrom: "MyCompany Product <product@mycompany.com>"
          replyTo: "product@mycompany.com"

Custom Email Templates

Section titled “Custom Email Templates”

Template Directory Structure

Section titled “Template Directory Structure”
./templates/
├── layouts/
│   ├── base.html
│   ├── minimal.html
│   └── branded.html
├── components/
│   ├── header.html
│   ├── footer.html
│   └── button.html
├── forms/
│   ├── contact.html
│   ├── newsletter.html
│   └── support.html
└── emails/
    ├── welcome.html
    ├── confirmation.html
    └── notification.html

Base Template Layout

Section titled “Base Template Layout”
templates/layouts/base.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ subject }}</title>
    <style>
        body {
            font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif;
            line-height: 1.6;
            color: #333;
            max-width: 600px;
            margin: 0 auto;
            padding: 20px;
        }
        .header {
            background: {{ brand.primaryColor }};
            color: white;
            padding: 20px;
            text-align: center;
            border-radius: 8px 8px 0 0;
        }
        .content {
            background: white;
            padding: 30px;
            border: 1px solid #ddd;
        }
        .footer {
            background: #f8f9fa;
            padding: 20px;
            text-align: center;
            border-radius: 0 0 8px 8px;
            color: #666;
            font-size: 14px;
        }
        .button {
            display: inline-block;
            padding: 12px 24px;
            background: {{ brand.primaryColor }};
            color: white;
            text-decoration: none;
            border-radius: 4px;
            margin: 20px 0;
        }
    </style>
</head>
<body>
    <div class="email-container">
        <div class="header">
            <img src="{{ brand.logoUrl }}" alt="{{ company.name }}" style="max-height: 60px;">
            <h1>{{ company.name }}</h1>
        </div>


        <div class="content">
            {% block content %}
            <!-- Content will be inserted here -->
            {% endblock %}
        </div>


        <div class="footer">
            {% include "components/footer.html" %}
        </div>
    </div>
</body>
</html>

Form-Specific Templates

Section titled “Form-Specific Templates”
templates/forms/contact.html
{% extends "layouts/base.html" %}


{% block content %}
<h2>New Contact Form Submission</h2>


<div style="background: #f8f9fa; padding: 20px; border-left: 4px solid {{ brand.primaryColor }}; margin: 20px 0;">
    <p><strong>From:</strong> {{ form.name }} &lt;{{ form.email }}&gt;</p>
    <p><strong>Submitted:</strong> {{ submission.timestamp | date:"M j, Y g:i A" }}</p>
    {% if form.phone %}
    <p><strong>Phone:</strong> {{ form.phone }}</p>
    {% endif %}
    {% if form.company %}
    <p><strong>Company:</strong> {{ form.company }}</p>
    {% endif %}
</div>


<h3>Message:</h3>
<div style="background: white; padding: 15px; border: 1px solid #ddd; border-radius: 4px;">
    {{ form.message | linebreaks }}
</div>


<div style="margin-top: 30px;">
    <a href="mailto:{{ form.email }}?subject=Re: {{ form.subject | default:'Your inquiry' }}" class="button">
        Reply to {{ form.name }}
    </a>
</div>


<div style="margin-top: 20px; padding: 15px; background: #e8f4f8; border-radius: 4px;">
    <p><strong>Note:</strong> This email was generated from the contact form on {{ domain }}.
    To reply, simply click the reply button above or respond to this email.</p>
</div>
{% endblock %}

Template Variables

Section titled “Template Variables”

Templates support a rich set of variables:

# Available template variables
form:
  name: "Submitted name"
  email: "Submitted email"
  message: "Form message"
  phone: "Phone number"
  company: "Company name"
  # ... any form field


submission:
  id: "Unique submission ID"
  timestamp: "Submission time"
  ip: "Submitter IP address"
  userAgent: "Browser user agent"
  referer: "Referring page"


brand:
  primaryColor: "#007cba"
  secondaryColor: "#6c757d"
  logoUrl: "https://company.com/logo.png"
  websiteUrl: "https://company.com"


company:
  name: "Company Name"
  address: "123 Business St"
  phone: "+1-555-123-4567"
  email: "contact@company.com"


domain: "mycompany.com"
project: "main"

Branding Configuration

Section titled “Branding Configuration”

Brand Assets

Section titled “Brand Assets”
domains:
  mycompany.com:
    projects:
      main:
        branding:
          colors:
            primary: "#007cba"
            secondary: "#6c757d"
            accent: "#28a745"
            text: "#333333"
          typography:
            fontFamily: "'Helvetica Neue', Helvetica, Arial, sans-serif"
            headingColor: "#2c3e50"
          logo:
            url: "https://mycompany.com/assets/logo.png"
            width: "150px"
            height: "auto"
          company:
            name: "MyCompany Inc."
            tagline: "Building the future"
            address: "123 Business Street, City, State 12345"
            phone: "+1-555-123-4567"
            website: "https://mycompany.com"

Brand Template Directory

Section titled “Brand Template Directory”
./branding/
├── logo.png
├── logo-white.png
├── favicon.ico
├── colors.yaml
├── typography.yaml
└── assets/
    ├── header-bg.png
    ├── pattern.svg
    └── social-icons/

Dynamic Branding

Section titled “Dynamic Branding”
<!-- Templates can use branding variables -->
<div style="background: {{ brand.colors.primary }};">
    <img src="{{ brand.logo.url }}"
         width="{{ brand.logo.width }}"
         alt="{{ company.name }}">
    <h1 style="color: {{ brand.colors.text }}; font-family: {{ brand.typography.fontFamily }};">
        {{ company.name }}
    </h1>
    <p>{{ company.tagline }}</p>
</div>

Reply Management

Section titled “Reply Management”

Reply-To Configuration

Section titled “Reply-To Configuration”
domains:
  mycompany.com:
    forwarding:
      # Standard forwarding rules
      "*@mycompany.com": "team@company.com"


      # Reply-specific addresses
      "replies@mycompany.com": "support@company.com"
      "no-reply@mycompany.com": "devnull@company.com"


    forms:
      contact:
        template: "contact"
        replies: true                    # Enables reply functionality
        replyTo: "support@mycompany.com" # Custom reply address


      newsletter:
        template: "newsletter"
        replies: false                   # No replies for newsletters
        replyTo: "no-reply@mycompany.com"

Reply Templates

Section titled “Reply Templates”
templates/replies/auto-acknowledgment.html
{% extends "layouts/base.html" %}


{% block content %}
<h2>Thank you for contacting us!</h2>


<p>Hi {{ form.name }},</p>


<p>We received your message and will get back to you within {{ response_time | default:"24 hours" }}.</p>


<div style="background: #f8f9fa; padding: 15px; border-left: 3px solid {{ brand.primaryColor }};">
    <strong>Your message:</strong><br>
    {{ form.message | linebreaks }}
</div>


<p>If you need immediate assistance, you can:</p>
<ul>
    <li>Call us at {{ company.phone }}</li>
    <li>Email us directly at {{ project.settings.replyTo }}</li>
    <li>Visit our help center at {{ company.website }}/help</li>
</ul>


<p>Best regards,<br>
The {{ company.name }} Team</p>
{% endblock %}

Conversation Threading

Section titled “Conversation Threading”
domains:
  mycompany.com:
    projects:
      support:
        replyHandling:
          enableThreading: true
          threadIdHeader: "X-mailiam-Thread-ID"
          maxThreadAge: "30d"
          autoClose: false
        templates:
          acknowledgment: "replies/support-ack.html"
          followup: "replies/support-followup.html"

Template Development

Section titled “Template Development”

Local Development Workflow

Section titled “Local Development Workflow”
Terminal window
# 1. Initialize project with templates
mailiam init mycompany.com --templates
cd mycompany.com


# 2. Edit templates
vim templates/forms/contact.html


# 3. Test template rendering
mailiam templates test contact --data test-data.json


# 4. Preview in browser
mailiam templates preview contact --serve


# 5. Deploy when ready
mailiam push

Template Testing

Section titled “Template Testing”
Terminal window
# Test template syntax
mailiam templates validate


# Test with sample data
mailiam templates test contact --data '{"name":"John","email":"john@test.com","message":"Hello"}'


# Test all templates
mailiam templates test-all


# Generate test data
mailiam templates generate-test-data contact > test-data.json

Template Optimization

Section titled “Template Optimization”
domains:
  mycompany.com:
    projects:
      main:
        templates:
          optimization:
            minifyHTML: true
            inlineCSS: true
            optimizeImages: true
            cacheTemplates: true

Advanced Project Features

Section titled “Advanced Project Features”

Environment-Specific Projects

Section titled “Environment-Specific Projects”
# Production
domains:
  mycompany.com:
    projects:
      main:
        templates: "./templates/production/"
        branding:
          colors:
            primary: "#007cba"


# Staging
domains:
  staging.mycompany.com:
    projects:
      main:
        templates: "./templates/staging/"
        branding:
          colors:
            primary: "#ffc107"  # Yellow for staging

A/B Testing Templates

Section titled “A/B Testing Templates”
domains:
  mycompany.com:
    projects:
      marketing:
        templates:
          newsletter:
            variants:
              - template: "newsletter-v1.html"
                weight: 50
              - template: "newsletter-v2.html"
                weight: 50
            testing:
              metric: "click_rate"
              duration: "7d"

Template Inheritance

Section titled “Template Inheritance”
domains:
  mycompany.com:
    projects:
      main:
        templates:
          base: "layouts/base.html"
          inheritance:
            forms: "extends:base"
            emails: "extends:base"
            notifications: "extends:minimal"

Performance Optimization

Section titled “Performance Optimization”

Template Caching

Section titled “Template Caching”
projects:
  main:
    performance:
      templateCaching: true
      cacheTime: "1h"
      precompileTemplates: true
      enableGzip: true

Asset Optimization

Section titled “Asset Optimization”
Terminal window
# Optimize template assets
mailiam templates optimize


# Compress images
mailiam assets compress --quality 85


# Minify CSS/JS in templates
mailiam templates minify

CLI Commands for Projects

Section titled “CLI Commands for Projects”

Project Management

Section titled “Project Management”
Terminal window
# List projects
mailiam projects list


# Create new project
mailiam projects create marketing "Marketing Project" --domain mycompany.com


# Show project details
mailiam projects show marketing


# Update project settings
mailiam projects update marketing --reply-to marketing@mycompany.com

Template Management

Section titled “Template Management”
Terminal window
# List templates
mailiam templates list


# Create new template
mailiam templates create contact --type form


# Test template
mailiam templates test contact --preview


# Deploy templates
mailiam templates deploy

Integration with Forms and Forwarding

Section titled “Integration with Forms and Forwarding”

Projects seamlessly integrate with mailiam’s other core features:

domains:
  mycompany.com:
    # Email forwarding uses project reply addresses
    forwarding:
      "support@mycompany.com": "team@company.com"
      "replies@mycompany.com": "support@company.com"


    # Forms use project templates and branding
    forms:
      contact:
        project: "main"           # Use main project templates
        template: "contact"       # Specific template within project
        replies: true            # Enable replies via project settings


    # Projects define the overall structure
    projects:
      main:
        templates: "./templates/"
        branding: "./branding/"
        settings:
          replyTo: "support@mycompany.com"

Projects transform your email infrastructure from functional to professional, ensuring every interaction reinforces your brand and enables meaningful conversations with your customers.