Form Collections

Form Collections allow you to organize multiple forms under a single namespace, giving you cleaner URLs and better management capabilities for teams and agencies.

Why Use Collections?

Collections solve several problems:

Clean URLs: Instead of /f/{random-id}, get /f/company/contact
Organization: Group related forms (contact, feedback, support) together
Team Management: Shared settings and permissions across forms
Professional Branding: Consistent namespace across all your forms

Collection vs Instant Forms

Feature	Instant Forms	Collection Forms
URL Structure	`/f/{formId}` or `/f/{slug}`	`/f/{collection}/{form}`
Setup Time	5 seconds	30 seconds
Organization	Individual	Grouped
Best For	Quick prototypes	Production use

Both approaches work simultaneously - you can have instant forms and collection forms active at the same time.

Quick Start

mailiam collections create mycompany "My Company Forms"

collections:
  mycompany:
    name: "My Company Forms"
    description: "All customer-facing forms"
    settings:
      rateLimit: 100
      spamProtection: true

2. Add Forms to Collection

CLI
Config File

# Add a contact form
mailiam collections add-form mycompany contact --email hello@mycompany.com

# Add a feedback form
mailiam collections add-form mycompany feedback --email feedback@mycompany.com

collections:
  mycompany:
    name: "My Company Forms"
    forms:
      contact:
        name: "Contact Form"
        email: hello@mycompany.com
      feedback:
        name: "Feedback Form"
        email: feedback@mycompany.com
        settings:
          customMessage: "Thanks for your feedback!"

3. Deploy Your Collection

mailiam push

Your forms are now live at:

https://api.mailiam.dev/f/mycompany/contact
https://api.mailiam.dev/f/mycompany/feedback

HTML Integration

Use your collection forms in any HTML:

<!-- Contact Form -->
<form action="https://api.mailiam.dev/f/mycompany/contact" method="POST">
  <input type="text" name="name" placeholder="Your name" required>
  <input type="email" name="email" placeholder="Email" required>
  <textarea name="message" placeholder="Message" required></textarea>

  <!-- Anti-spam honeypot -->
  <input type="text" name="pooh-bear" style="display: none;">

  <button type="submit">Send Message</button>
</form>

Collection Settings

Collections support powerful configuration options:

collections:
  mycompany:
    name: "My Company Forms"
    settings:
      # Rate limiting (per hour)
      rateLimit: 100

      # Spam protection
      spamProtection: true

      # Require API key for submissions
      requireApiKey: false

      # Default thank you message
      customMessage: "Thank you for contacting us!"

Form-Level Settings

Override collection settings for specific forms:

collections:
  mycompany:
    forms:
      contact:
        email: hello@mycompany.com
        settings:
          # Override collection message for this form
          customMessage: "We'll get back to you within 24 hours!"

          # Custom rate limit for high-traffic forms
          rateLimitPerMinute: 5

          # Redirect after submission
          redirectUrl: "https://mycompany.com/thank-you"

Migrating from Instant Forms

Already have instant forms? Easily migrate them to collections:

# Import existing form to collection
mailiam collections import mycompany existing-form-id contact

This will:

Move the form to your collection
Give it a clean URL: /f/mycompany/contact
Keep the old URL working for backward compatibility

Managing Collections

List Your Collections

mailiam collections list

View Forms in a Collection

mailiam collections forms mycompany

Add More Forms

mailiam collections add-form mycompany support --email support@mycompany.com

Delete a Collection

mailiam collections delete mycompany

⚠️ Note: You must delete all forms in a collection before deleting the collection itself.

Team Collaboration

Collections work great with teams:

Shared Configuration: Everyone uses the same mailiam.config.yaml
Version Control: Check your collections into Git
Environment Management: Different collections for staging/production
Permission Control: Collection-level API key requirements

Best Practices

Naming Conventions

Collection slugs: Use company/brand name (mycompany, agency-client)
Form slugs: Use descriptive names (contact, newsletter, support)
Email addresses: Use role-based emails (hello@, support@)

Organization Patterns

Single Company:

company/
├── contact
├── support
└── newsletter

Agency with Multiple Clients:

client-a/
├── contact
└── quote

client-b/
├── contact
├── support
└── feedback

Security Settings

Enable spamProtection for public forms
Use requireApiKey for internal/admin forms
Set appropriate rateLimit based on expected traffic