AI Assistant Guide

This guide helps AI coding assistants (Claude, Copilot, Cursor, etc.) understand and work effectively with mailiam.

For the complete AI instructions, see MAILIAM_AI_INSTRUCTIONS.md in the repository root.

Quick Reference

Essential Commands

mailiam form - Create instant form endpoint
mailiam init domain.com - Initialize domain-based project
mailiam push - Deploy configuration (like git push)
mailiam collections create - Create form collection

Core Concepts

Config-as-Code: Everything in mailiam.config.yaml
Three Features: Email Forwarding, Custom Domains, Contact Forms
Git Workflow: Version controlled email infrastructure

Form Endpoints

Instant: https://api.mailiam.dev/f/{formId}
Domain: https://api.mailiam.dev/v1/{domain}/send
Collection: https://api.mailiam.dev/f/{collection}/{form}

Basic Configuration

domains:
  mysite.com:
    forwarding:
      "*@mysite.com": "me@gmail.com"
    forms:
      contact:
        template: "professional"
        replies: true

collections:
  company:
    name: "Company Forms"
    forms:
      contact:
        name: "Contact Form"

Integration Examples

React Hook

function usemailiam(endpoint) {
  const [isSubmitting, setIsSubmitting] = useState(false);

  const submit = async (formData) => {
    setIsSubmitting(true);
    try {
      const response = await fetch(endpoint, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(formData)
      });
      return response.ok;
    } finally {
      setIsSubmitting(false);
    }
  };

  return { submit, isSubmitting };
}

Next.js API Route

export default async function handler(req, res) {
  const response = await fetch('https://api.mailiam.dev/v1/mysite.com/send', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(req.body)
  });

  return res.json(await response.json());
}

Common Tasks

When helping with mailiam, focus on:

Configuration: Creating proper mailiam.config.yaml files
Integration: Framework-specific form submission code
Troubleshooting: Using CLI commands to diagnose issues
Migration: Moving from services like Formspree