Contact Forms

Contact forms are mailiam’s third core feature, providing lightning-fast form processing with enterprise-grade security and organizational tools.

Overview

mailiam’s contact forms deliver:

• Sub-100ms processing times globally
• Built-in spam protection with honeypots and validation
• Form collections for organizing multiple forms
• Instant deployment - no backend required
• Professional templates and custom branding
• Reply-enabled emails for real conversations

Quick Start

Instant Form (Zero Config)

Need a form endpoint immediately?

mailiam form

# Returns: https://api.mailiam.dev/f/abc123def

Use it in your HTML:

<form action="https://api.mailiam.dev/f/abc123def" method="POST">
  <input type="email" name="email" placeholder="Email" required>
  <input type="text" name="name" placeholder="Name" required>
  <textarea name="message" placeholder="Message" required></textarea>
  <button type="submit">Send</button>
</form>

Domain-Based Forms

For professional setups with your domain:

<form action="https://api.mailiam.dev/v1/mysite.com/send" method="POST">
  <input type="email" name="email" placeholder="Email" required>
  <textarea name="message" placeholder="Message" required></textarea>
  <button type="submit">Send</button>
</form>

Authentication Options

mailiam provides three ways to authenticate form submissions, depending on your deployment:

Option 1: No API Key (Recommended for Static Sites)

Perfect for: Simple HTML forms, static websites

Forms work automatically with origin validation - no API key needed!

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

How it’s secure:

• ✅ Domain verified via DNS
• ✅ Origin header validation
• ✅ Browser detection (blocks curl, Postman)
• ✅ IP-based rate limiting
• ✅ Built-in spam protection

When to use:

• Static HTML forms
• No JavaScript needed
• Quick prototypes
• Simple contact forms

---

Option 2: Public Token (Safe for Client-Side)

Perfect for: Static sites with JavaScript features

Public tokens are domain-scoped and safe to expose in client-side code:

// Safe to embed in your JavaScript!
const PUBLIC_TOKEN = 'mlm_pk_a7f8b3e1_j4k5l6m7n8o9p0q1...';

async function submitForm(formData) {
  const response = await fetch('https://api.mailiam.dev/v1/mysite.com/send', {
    method: 'POST',
    headers: {
      'X-Public-Token': PUBLIC_TOKEN,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(formData)
  });

  return response.json();
}

Generate a public token:

mailiam auth create-key \
  --name "Public Token for mysite.com" \
  --type public \
  --domain mysite.com

Security features:

• ✅ Only works for ONE specific domain
• ✅ Cannot access other domains
• ✅ Cannot manage settings
• ✅ Lower rate limit (100/hour)
• ✅ Can be safely embedded in JavaScript

When to use:

• Static sites needing JS interactions
• Client-side form enhancements
• Checking submission status
• Displaying analytics

---

Option 3: Usage Key (Server-Side Only)

Perfect for: Vercel/Netlify API routes, backend services

Usage keys provide higher limits but must be kept server-side:

// Vercel API Route (pages/api/contact.js)
export default async function handler(req, res) {
  const response = await fetch(
    'https://api.mailiam.dev/v1/mysite.com/send',
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.MAILIAM_USAGE_KEY, // Server-side only!
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(req.body)
    }
  );

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

Generate a usage key:

mailiam auth create-key \
  --name "Vercel API Routes" \
  --type usage

Benefits:

• ✅ Higher rate limits (1000/hour)
• ✅ API key never exposed to client
• ✅ Custom validation before sending
• ✅ Can integrate with your backend

When to use:

• Vercel/Netlify API routes
• Backend services
• Need custom validation
• Higher rate limits required

---

Decision Tree

Static HTML form, no JavaScript?
  → No API key needed! ✅

Static site with JavaScript features?
  → Public token (client-safe) ✅

Using Vercel/Netlify API routes?
  → Usage key (server-side) ✅

Need to manage domains via API?
  → Admin key (server-side only) ✅

Comparison Table

Feature	No API Key	Public Token	Usage Key	Admin Key
Static sites	✅ Perfect	✅ Yes	❌ No	❌ No
Client-side JS	⚠️ Limited	✅ Perfect	❌ No	❌ No
Server-side	❌ No	❌ No	✅ Perfect	✅ Yes
Rate limit	100/hr	100/hr	1000/hr	1000/hr
Can expose	✅ Safe	✅ Safe	❌ Never	❌ Never
Domain scope	Current	Current only	All	All

Learn more: Authentication Model

Form Collections

Organize multiple forms under a single namespace for better organization and management.

Creating Collections

# Create a collection
mailiam collections create "t3d" "Think Three Dots" --description "All T3D company forms"

# Add forms to collection
mailiam collections add-form "t3d" "contact" "Contact Form"
mailiam collections add-form "t3d" "feedback" "Feedback Form"
mailiam collections add-form "t3d" "newsletter" "Newsletter Signup"

Collection URLs

Forms in collections get clean, organized URLs:

• Contact: https://api.mailiam.dev/f/t3d/contact
• Feedback: https://api.mailiam.dev/f/t3d/feedback
• Newsletter: https://api.mailiam.dev/f/t3d/newsletter

Collection Configuration

mailiam.config.yaml

collections:
  t3d:
    name: "Think Three Dots"
    description: "All T3D company forms"
    settings:
      rateLimit: 100
      spamProtection: true
      requireApiKey: false
    forms:
      contact:
        name: "Contact Form"
        email: "contact@t3d.com"
        settings:
          customMessage: "Thanks for reaching out!"
          rateLimitPerMinute: 10
      feedback:
        name: "Feedback Form"
        email: "feedback@t3d.com"
        settings:
          customMessage: "We appreciate your feedback!"
      newsletter:
        name: "Newsletter Signup"
        email: "newsletter@t3d.com"
        settings:
          customMessage: "Welcome to our newsletter!"

Form Configuration

Basic Form Setup

domains:
  mysite.com:
    forms:
      contact:
        template: "professional"
        subject: "New Contact Form Submission"
        replies: true
        to: "team@mysite.com"
        settings:
          spamProtection: true
          rateLimitPerMinute: 10
          redirectUrl: "/thank-you"

Advanced Form Configuration

domains:
  mysite.com:
    forms:
      contact:
        template: "custom"
        subject: "New Contact from {{ name }}"
        replies: true
        replyTo: "support@mysite.com"
        to:
          - "team@mysite.com"
          - "alerts@slack.com"
        settings:
          spamProtection: true
          honeypotField: "_mailiam_honeypot"
          rateLimitPerMinute: 5
          rateLimitPerHour: 50
          requireRecaptcha: false
          allowedOrigins:
            - "https://mysite.com"
            - "https://www.mysite.com"
          blockedDomains:
            - "tempmail.org"
            - "10minutemail.com"
          customFields:
            required: ["email", "name", "message"]
            optional: ["phone", "company"]
            validation:
              email: "email"
              phone: "phone"
              message: "minLength:10"

Form Templates

Built-in Templates

mailiam provides several professional templates:

forms:
  contact:
    template: "professional"  # Clean, business-focused

  support:
    template: "technical"     # Technical support style

  feedback:
    template: "casual"        # Friendly, informal tone

  newsletter:
    template: "marketing"     # Marketing-focused design

Custom Templates

Create your own branded templates:

domains:
  mysite.com:
    templates:
      custom:
        subject: "New message from {{ name }}"
        html: |
          <!DOCTYPE html>
          <html>
          <head>
            <style>
              body { font-family: 'Helvetica', sans-serif; }
              .header { background: #007cba; color: white; padding: 20px; }
              .content { padding: 20px; }
              .message { background: #f9f9f9; padding: 15px; border-left: 3px solid #007cba; }
            </style>
          </head>
          <body>
            <div class="header">
              <h1>New Contact Form Submission</h1>
            </div>
            <div class="content">
              <p><strong>From:</strong> {{ name }} ({{ email }})</p>
              <p><strong>Submitted:</strong> {{ timestamp }}</p>
              <div class="message">
                <strong>Message:</strong><br>
                {{ message }}
              </div>
              {% if phone %}
              <p><strong>Phone:</strong> {{ phone }}</p>
              {% endif %}
            </div>
          </body>
          </html>
        text: |
          New Contact Form Submission

          From: {{ name }} ({{ email }})
          Submitted: {{ timestamp }}

          Message:
          {{ message }}

          {% if phone %}Phone: {{ phone }}{% endif %}
    forms:
      contact:
        template: "custom"

Spam Protection

Built-in Protection

Every form includes automatic spam protection:

• Honeypot fields (invisible to humans, visible to bots)
• Rate limiting per IP address
• Domain blacklisting for known spam sources
• Content filtering for spam patterns
• Submission validation for required fields

Advanced Spam Protection

forms:
  contact:
    security:
      spamProtection: "strict"        # strict, normal, or lenient
      honeypotField: "_trap"          # Custom honeypot field name
      rateLimitPerMinute: 3           # Max submissions per minute per IP
      rateLimitPerHour: 20            # Max submissions per hour per IP
      blockedCountries: ["CN", "RU"]  # Block by country code
      blockedDomains:                 # Block specific email domains
        - "tempmail.org"
        - "guerrillamail.com"
      requiredFields: ["email", "name", "message"]
      contentFiltering:
        enabled: true
        blockKeywords: ["viagra", "casino", "lottery"]
        maxLinks: 3                   # Max links allowed in message
        maxLength: 5000               # Max message length

Custom Spam Rules

forms:
  contact:
    spamRules:
      - name: "Block empty submissions"
        condition: "message.length < 10"
        action: "reject"
      - name: "Suspicious email patterns"
        condition: "email matches '^[a-z]{20,}@'"
        action: "quarantine"
      - name: "Too many caps"
        condition: "message.uppercaseRatio > 0.7"
        action: "flag"

Performance Optimization

Global Edge Deployment

Forms are deployed to 150+ locations worldwide:

• Sub-100ms response times in most regions
• Automatic scaling based on traffic
• Real-time monitoring and alerting
• 99.9% uptime SLA with redundancy

Performance Configuration

forms:
  contact:
    performance:
      caching: true                  # Cache form configuration
      compression: true              # Compress responses
      keepAlive: true               # HTTP keep-alive
      timeout: 30000                # 30-second timeout
      retries: 3                    # Automatic retries
      concurrency: 100              # Max concurrent requests

Performance Monitoring

# Check form performance
mailiam forms performance contact --last 24h

# View response time metrics
mailiam metrics forms contact

# Performance alerts
mailiam alerts create form-slow --condition "responseTime > 500ms"

Form Analytics

Submission Tracking

forms:
  contact:
    analytics:
      trackSubmissions: true
      trackErrors: true
      trackSpam: true
      retentionDays: 90            # How long to keep analytics

View Analytics

# Form submission stats
mailiam analytics forms contact --last 30d

# Spam detection stats
mailiam analytics spam contact

# Error rate monitoring
mailiam analytics errors --all-forms

CLI Commands

Form Management

# Create instant form
mailiam form

# List all forms
mailiam forms list

# Show form details
mailiam forms show contact

# Test form submission
mailiam forms test contact --data '{"email":"test@example.com","message":"test"}'

Collection Management

# Create collection
mailiam collections create "mycompany" "My Company Forms"

# List collections
mailiam collections list

# Add form to collection
mailiam collections add-form "mycompany" "support" "Support Form"

# Import existing form to collection
mailiam collections import "mycompany" abc123def "contact"

Advanced Features

Conditional Logic

forms:
  contact:
    conditionalLogic:
      - condition: "subject == 'Support Request'"
        actions:
          - setTemplate: "support"
          - addRecipient: "support@company.com"
          - setPriority: "high"
      - condition: "email endsWith '@enterprise.com'"
        actions:
          - addTag: "enterprise"
          - setTemplate: "enterprise"
          - notifySlack: "#enterprise-leads"

Webhooks and Integrations

forms:
  contact:
    webhooks:
      - url: "https://myapp.com/webhook/contact"
        method: "POST"
        headers:
          Authorization: "Bearer {{ env.WEBHOOK_TOKEN }}"
        events: ["submission", "spam_blocked"]
      - url: "https://hooks.zapier.com/hooks/catch/123/abc"
        method: "POST"
        events: ["submission"]
    integrations:
      slack:
        webhook: "{{ env.SLACK_WEBHOOK }}"
        channel: "#leads"
        template: "New contact from {{ name }}: {{ message }}"
      hubspot:
        apiKey: "{{ env.HUBSPOT_API_KEY }}"
        createContact: true
        pipelineId: "default"

File Uploads

forms:
  contact:
    fileUploads:
      enabled: true
      maxSize: "10MB"
      allowedTypes: ["pdf", "doc", "docx", "txt", "jpg", "png"]
      storage: "s3"               # s3, gcs, or azure
      bucket: "mycompany-uploads"
      path: "form-uploads/{{ timestamp }}/{{ filename }}"

<form action="https://api.mailiam.dev/v1/mysite.com/send" method="POST" enctype="multipart/form-data">
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <input type="file" name="attachment" accept=".pdf,.doc,.docx">
  <button type="submit">Send</button>
</form>

Security Best Practices

1. Always use HTTPS for form submissions
2. Validate on both client and server sides
3. Use honeypot fields to catch bots
4. Implement rate limiting to prevent abuse
5. Sanitize all input before processing
6. Monitor for spam patterns regularly
7. Keep blacklists updated with new spam domains

Troubleshooting

Common Issues

Form not receiving submissions:

# Test form endpoint
mailiam forms test contact --data '{"email":"test@test.com","message":"test"}'

# Check form configuration
mailiam forms show contact

# View form logs
mailiam logs forms contact --last 1h

High spam rate:

# Check spam statistics
mailiam analytics spam contact

# Update spam protection
mailiam forms update contact --spam-protection strict

# Add to blocked domains
mailiam forms block-domain contact tempmail.org

Slow form responses:

# Check performance metrics
mailiam metrics forms contact

# View response times by region
mailiam performance forms contact --by-region

# Enable caching
mailiam forms update contact --caching true

Form processing that’s faster than your users can blink - that’s the mailiam difference.