Skip to content
Mailiam Docs

Forms Documentation

Forms Documentation

Section titled “Forms Documentation”

Mailiam provides instant form infrastructure that turns any HTML form into a working contact form without backend setup. This guide covers everything from basic usage to advanced features like reply forwarding.

Quick Start

Section titled “Quick Start”

1. Create a Form

Section titled “1. Create a Form”

Submit a POST request to create your form:

Terminal window
curl -X POST https://api.mailiam.dev/instant/forms \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Form",
    "email": "your@email.com",
    "domain": "yourdomain.com"
  }'

Response:

{
  "success": true,
  "form": {
    "id": "form_abc123",
    "endpoint": "https://api.mailiam.dev/instant/forms/form_abc123/submit",
    "replyAddress": "reply+xyz789@mail.mailiam.dev",
    "replyForwarding": true
  }
}

2. Update Your HTML Form

Section titled “2. Update Your HTML Form”
<form action="https://api.mailiam.dev/instant/forms/form_abc123/submit" method="POST">
  <input type="email" name="email" placeholder="Your email" required>
  <textarea name="message" placeholder="Your message" required></textarea>
  <button type="submit">Send Message</button>
</form>

That’s it! Your form is now live and will forward submissions to your email.

Reply Forwarding System

Section titled “Reply Forwarding System”

How It Works

Section titled “How It Works”

Each form gets a unique reply address like reply+xyz789@mail.mailiam.dev. When someone replies to the email you receive, Mailiam automatically forwards it back to the original sender, creating a seamless conversation thread.

Benefits

Section titled “Benefits”
  • Seamless Conversations: Users can reply directly to form submissions
  • Privacy Protection: Your real email stays private
  • Professional Appearance: All emails appear to come from your domain
  • Zero Configuration: Works automatically with every new form

Managing Replies

Section titled “Managing Replies”

Enable/disable reply forwarding:

Terminal window
curl -X PATCH https://api.mailiam.dev/instant/forms/form_abc123 \
  -H "Content-Type: application/json" \
  -d '{"replyForwarding": false}'

Get form reply status:

Terminal window
curl https://api.mailiam.dev/instant/forms/form_abc123/replies

Form Configuration

Section titled “Form Configuration”

Required Fields

Section titled “Required Fields”
  • name: Display name for your form
  • email: Email where submissions will be sent
  • domain: Your website domain (for security)

Optional Fields

Section titled “Optional Fields”
  • replyForwarding: Enable/disable reply forwarding (default: true)
  • honeypot: Custom honeypot field name (default: “_mailiam_honeypot”)
  • rateLimit: Submissions per hour limit (default: 10)

Example with All Options

Section titled “Example with All Options”
{
  "name": "Product Inquiry Form",
  "email": "sales@company.com",
  "domain": "company.com",
  "replyForwarding": true,
  "honeypot": "company_bot_field",
  "rateLimit": 20
}

Security Features

Section titled “Security Features”

Built-in Spam Protection

Section titled “Built-in Spam Protection”
  • Honeypot Fields: Hidden fields that catch bots
  • Rate Limiting: Prevents form submission abuse
  • Domain Verification: Forms only work from registered domains
  • Input Sanitization: All form data is cleaned and validated

Honeypot Implementation

Section titled “Honeypot Implementation”

Add a hidden field to your form:

<form action="https://api.mailiam.dev/instant/forms/form_abc123/submit" method="POST">
  <!-- Your visible fields -->
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>


  <!-- Hidden honeypot field -->
  <input type="text" name="_mailiam_honeypot" style="display:none" tabindex="-1" autocomplete="off">


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

Rate Limiting

Section titled “Rate Limiting”

Forms are automatically rate-limited to prevent abuse:

  • Default: 10 submissions per hour per IP
  • Customizable per form
  • Returns HTTP 429 when limit exceeded

Form Management API

Section titled “Form Management API”

List All Forms

Section titled “List All Forms”
Terminal window
curl -H "Authorization: Bearer your-token" \
  https://api.mailiam.dev/instant/forms

Get Form Details

Section titled “Get Form Details”
Terminal window
curl https://api.mailiam.dev/instant/forms/form_abc123

Update Form Settings

Section titled “Update Form Settings”
Terminal window
curl -X PATCH https://api.mailiam.dev/instant/forms/form_abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Form Name",
    "rateLimit": 15
  }'

Delete Form

Section titled “Delete Form”
Terminal window
curl -X DELETE https://api.mailiam.dev/instant/forms/form_abc123

Email Templates

Section titled “Email Templates”

Default Email Format

Section titled “Default Email Format”

Form submissions are formatted as clean, readable emails:

Subject: New submission from Contact Form


From: john@example.com


Message:
Hello, I'm interested in your product and would like to know more about pricing.


---
Form: Contact Form (form_abc123)
IP: 192.168.1.1
Time: 2024-01-15 10:30:00 UTC

Custom Styling

Section titled “Custom Styling”

Emails include basic HTML formatting:

  • Clean typography
  • Highlighted form fields
  • Professional footer with form metadata
  • Responsive design for mobile viewing

Advanced Usage

Section titled “Advanced Usage”

JavaScript Integration

Section titled “JavaScript Integration”

Handle form submissions with JavaScript:

document.getElementById('contact-form').addEventListener('submit', async (e) => {
  e.preventDefault();


  const formData = new FormData(e.target);


  try {
    const response = await fetch('https://api.mailiam.dev/instant/forms/form_abc123/submit', {
      method: 'POST',
      body: formData
    });


    if (response.ok) {
      alert('Message sent successfully!');
      e.target.reset();
    } else {
      alert('Failed to send message. Please try again.');
    }
  } catch (error) {
    alert('Network error. Please try again.');
  }
});

CORS Support

Section titled “CORS Support”

Mailiam automatically handles CORS for all domains:

  • Supports all HTTP methods
  • Allows custom headers
  • Works with any frontend framework

Webhook Integration

Section titled “Webhook Integration”

Get notified when forms are submitted:

Terminal window
curl -X POST https://api.mailiam.dev/instant/forms/form_abc123/webhooks \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["form.submitted"]
  }'

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

Form not working?

  • Check that the form action URL matches your form ID
  • Ensure your domain is registered correctly
  • Verify required fields (email, message) are included

Not receiving emails?

  • Check your spam folder
  • Verify the email address in your form configuration
  • Ensure your email provider isn’t blocking emails from mailiam.dev

Rate limit errors?

  • Wait an hour and try again
  • Contact support if you need a higher limit
  • Consider implementing client-side validation

Getting Help

Section titled “Getting Help”

Next Steps

Section titled “Next Steps”