mailiam CLI

Developer-first email infrastructure. Instant forms, declarative configuration, zero-hassle email sending.

Installation

npm install -g mailiam

Quick Start

1. Create Account & Get API Key

mailiam signup
mailiam auth set-key YOUR_API_KEY

2. Initialize Project

mailiam init
# Creates mailiam.config.yaml with your email configuration

3. Deploy Configuration

mailiam push
# Sets up domains, email forwarding, form handlers

4. Create Instant Form (Formspree-style)

mailiam form
# Get an instant form endpoint - no config needed!

Features

🚀 Instant Forms

Get a working form endpoint in seconds:

mailiam instant create --email [email protected] --name "Contact Form"
# Returns: https://api.mailiam.dev/f/abc123de

⚙️ Declarative Configuration

Define your email setup in YAML:

# mailiam.config.yaml
domains:
  myapp.com:
    forwards:
      hello: [email protected]
      support: [email protected]
    forms:
      contact:
        to: [email protected]
        subject: "New Contact from Website"

🏗️ Framework Integration

Built-in templates for:

• React/Next.js
• Vue/Nuxt
• Astro
• Static HTML

🔒 Security First

• Advanced spam protection
• Rate limiting
• Content filtering
• Security analytics

Commands

Authentication

mailiam signup              # Create account
mailiam auth set-key <key>  # Set API key
mailiam auth status         # Check auth status

API Keys

Generate API keys for programmatic access:

mailiam apikeys create               # Create new API key (interactive)
mailiam apikeys create --name "Production Key" --permissions "forms:send,domains:read"
mailiam apikeys list                 # List all API keys
mailiam apikeys delete <keyId>       # Delete API key

Key Features:

• Scoped Permissions: Control what each key can access (forms:send, domains:read, projects:read, analytics:read)
• Rate Limiting: Built-in rate limits (1000 requests/hour by default)
• Expiration: Optional expiration dates for enhanced security
• Secure Storage: Keys are stored hashed and only shown once at creation

Usage in Applications:

// Using fetch
fetch('https://api.mailiam.dev/v1/myapp.com/send', {
  method: 'POST',
  headers: {
    'x-api-key': 'mlm_abcd1234_...',
    'content-type': 'application/json'
  },
  body: JSON.stringify({ name: 'John', email: '[email protected]' })
});

// Using curl
curl -X POST https://api.mailiam.dev/v1/myapp.com/send \
  -H "x-api-key: mlm_abcd1234_..." \
  -H "content-type: application/json" \
  -d '{"name":"John","email":"[email protected]"}'

Project Management

mailiam init               # Initialize project
mailiam push               # Deploy configuration
mailiam pull               # Sync remote config
mailiam status             # Show project status

Domains

mailiam domains list       # List domains
mailiam domains add <domain>  # Add domain
mailiam domains verify <domain>  # Verify domain

Instant Forms

mailiam instant create     # Create instant form
mailiam instant list       # List your forms
mailiam instant submissions <id>  # View submissions
mailiam instant security <id>     # Security report

Testing

mailiam test send <email>  # Send test email

Configuration File

mailiam.config.yaml example:

project:
  name: "My App"
  id: "my-app-123"

domains:
  myapp.com:
    # Email forwarding
    forwards:
      hello: [email protected]
      support: [email protected]
      
    # Contact forms
    forms:
      contact:
        to: [email protected]
        subject: "New Contact from {{name}}"
        template: |
          Name: {{name}}
          Email: {{email}}
          Message: {{message}}

API Integration

Browser Forms (No API Key Required)

Perfect for contact forms and user submissions:

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

Programmatic Access (API Key Required)

For server-to-server communication and applications:

const response = await fetch('https://api.mailiam.dev/v1/myapp.com/send', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.MAILIAM_API_KEY,
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: '[email protected]',
    message: 'Hello from my app!'
  })
});

Security Model:

• Browser requests: Validated by origin, user-agent, and rate limiting
• API requests: Require valid API key with proper permissions

Beta Notice

mailiam is currently in beta. During beta:

• ✅ Unlimited usage
• ✅ Full feature access
• ✅ Production-ready reliability
• 📅 Billing starts after beta period

Support

• 📖 Documentation: https://mailiam.dev/docs
• 💬 Discord: https://discord.gg/mailiam
• 📧 Email: [email protected]
• 🐛 Issues: https://github.com/mailiam/mailiam-cli/issues

License

MIT