Collections Commands

The mailiam collections command group provides full lifecycle management for form collections.

Quick Reference

# Create collection
mailiam collections create <slug> <name>

# List collections
mailiam collections list

# Add form to collection
mailiam collections add-form <collection> <form-slug>

# List forms in collection
mailiam collections forms <collection>

# Import existing form to collection
mailiam collections import <collection> <form-id> <form-slug>

# Delete collection
mailiam collections delete <collection>

Commands

collections create

Creates a new form collection with organized namespace.

mailiam collections create mycompany "My Company Forms"

Options:

• -d, --description <text> - Collection description
• -r, --rate-limit <number> - Rate limit per hour (default: 100)
• --no-spam-protection - Disable spam protection
• --require-api-key - Require API key for form submissions

Examples:

Basic

mailiam collections create mycompany "My Company"

With Options

mailiam collections create mycompany "My Company" \
  --description "Customer-facing forms" \
  --rate-limit 200 \
  --require-api-key

Interactive

# Prompts for missing information
mailiam collections create

Output:

✅ Collection 'My Company' created successfully!
Collection ID: abc123-def456
Slug: mycompany
Base URL: https://api.mailiam.dev/f/mycompany/

collections list

Lists all your collections with form counts and status.

mailiam collections list

Output:

Your Collections:

● My Company (mycompany)
  Customer-facing contact forms
  Forms: 3 | Created: 9/12/2023
  Base URL: https://api.mailiam.dev/f/mycompany/

● Agency Client A (client-a)
  Client forms and feedback
  Forms: 2 | Created: 9/10/2023
  Base URL: https://api.mailiam.dev/f/client-a/

collections add-form

Adds a new form to an existing collection.

mailiam collections add-form mycompany contact

Options:

• -n, --name <name> - Form display name
• -e, --email <email> - Email address for notifications (required)
• -m, --custom-message <text> - Custom thank you message
• -r, --rate-limit <number> - Rate limit per minute (default: 10)

Examples:

Basic

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

With Custom Settings

mailiam collections add-form mycompany feedback \
  --email feedback@mycompany.com \
  --name "Customer Feedback Form" \
  --custom-message "Thank you for your valuable feedback!" \
  --rate-limit 5

Interactive

# Prompts for email and other details
mailiam collections add-form mycompany support

Output:

✅ Form 'contact' added to collection 'mycompany'!

🎉 Your form is ready to use!
Endpoint: https://api.mailiam.dev/f/mycompany/contact
Form ID: form123-456

📝 Sample HTML:
<form action="https://api.mailiam.dev/f/mycompany/contact" method="POST">
  <input type="email" name="email" placeholder="Your email" required>
  <textarea name="message" placeholder="Your message" required></textarea>
  <input type="text" name="pooh-bear" style="display: none;">
  <button type="submit">Send Message</button>
</form>

collections forms

Lists all forms within a specific collection.

mailiam collections forms mycompany

Output:

Forms in Collection 'My Company':

● Contact Form (contact)
  Endpoint: https://api.mailiam.dev/f/mycompany/contact
  Email: hello@mycompany.com
  Submissions: 42
  Created: 9/12/2023

● Feedback Form (feedback)
  Endpoint: https://api.mailiam.dev/f/mycompany/feedback
  Email: feedback@mycompany.com
  Submissions: 8
  Created: 9/12/2023

collections import

Migrates an existing instant form into a collection.

mailiam collections import mycompany existing-form-id contact

Parameters:

• <collection> - Target collection slug
• <form-id> - Existing instant form ID or slug
• <form-slug> - New slug within the collection

Examples:

Import by Form ID

mailiam collections import mycompany abc123-def456 contact

Import by Custom Slug

mailiam collections import mycompany my-contact-form contact

Output:

✅ Form imported to collection 'mycompany' successfully!

🎉 Form migration complete!
New endpoint: https://api.mailiam.dev/f/mycompany/contact
Old endpoint: https://api.mailiam.dev/f/abc123-def456 (still works)

📝 Updated HTML:
<form action="https://api.mailiam.dev/f/mycompany/contact" method="POST">
  ...
</form>

Migration Notes:

• Old endpoints continue working for backward compatibility
• Form settings and submission history are preserved
• Email notifications continue to the same address

collections delete

Deletes a collection and all its forms.

mailiam collections delete mycompany

Safety Features:

• Interactive confirmation required
• Cannot delete collections with existing forms
• Must delete all forms first

Output:

? Are you sure you want to delete collection 'My Company'? This cannot be undone. No
Delete cancelled

Configuration File Integration

Collections work seamlessly with mailiam.config.yaml:

collections:
  mycompany:
    name: "My Company Forms"
    description: "All customer-facing forms"
    settings:
      rateLimit: 100
      spamProtection: true
    forms:
      contact:
        name: "Contact Form"
        email: hello@mycompany.com
      feedback:
        name: "Feedback Form"
        email: feedback@mycompany.com
        settings:
          customMessage: "Thanks for your feedback!"
          rateLimitPerMinute: 5

Deploy with:

mailiam push

Error Handling

Common error scenarios and solutions:

Collection Not Found

✗ Collection 'nonexistent' not found

Solution: Check collection slug with mailiam collections list

Form Already Exists

✗ A form with this slug already exists in this collection

Solution: Choose a different form slug or delete existing form

Permission Denied

✗ You do not own this form

Solution: You can only import forms you created or have claimed

Best Practices

Naming Conventions

Collection Slugs:

• Use company/brand identifier: mycompany, client-name
• Keep it short and memorable
• Use lowercase with hyphens: my-agency

Form Slugs:

• Descriptive but concise: contact, newsletter, quote-request
• Consistent across collections: always use contact, never mix with contact-us

Organization Patterns

Single Organization:

mailiam collections create company "Company Forms"
mailiam collections add-form company contact
mailiam collections add-form company support
mailiam collections add-form company newsletter

Agency with Clients:

mailiam collections create client-a "Client A"
mailiam collections add-form client-a contact
mailiam collections add-form client-a quote

mailiam collections create client-b "Client B"
mailiam collections add-form client-b contact
mailiam collections add-form client-b feedback

Security Settings

For public-facing forms:

mailiam collections create company "Company" \
  --rate-limit 50 \
  # (spam protection enabled by default)

For internal/admin forms:

mailiam collections create internal "Internal Forms" \
  --require-api-key \
  --rate-limit 200

Integration with Other Commands

Collections work with other mailiam CLI features:

Deploy Collections

mailiam push  # Deploys collections from config file

View Analytics

mailiam analytics --collection mycompany

Test Collection Forms

mailiam test form mycompany/contact

Troubleshooting

Debug Collection Operations

mailiam collections create mycompany "Company" --debug

Verify Collection Deployment

mailiam status collections

Reset Collection State

mailiam collections delete mycompany
mailiam collections create mycompany "Company"
# Re-add forms as needed