DOCUMENTATION

Developer Documentation

Everything you need to handle form submissions without writing a single line of backend code. Simple, secure, and efficient.

Getting Started

formly.email is a powerful form submission handler that makes it easy to collect and manage form submissions without any backend setup. Get started in minutes with our simple integration process.

💡 Pro Tip: Your access key is public and can be safely included in your HTML. It's designed to be used in client-side code.

Quick Start Guide

1. Get Your Access Key

Simply submit your email address to receive your unique access key. No signup required!

You'll receive your access key instantly via email. This key will authenticate your form submissions.

2. Create Your Form

Set up your HTML form with formly.email's submission endpoint. Here's a basic example

3. Configure Your Form

Ensure your form includes these essential elements:

  • The correct form action URL: https://formly.email/submit
  • Your access key in the hidden input field
  • Required name attributes on all form fields

4. Test Your Integration

Once you've implemented the form, test it in your browser. You should receive form submissions at your configured email address.

This is a basic implementation. Explore our documentation for advanced features and customization options.

Basic Form Setup

Setting up a basic form with formly.email is straightforward. Here's a simple example:

<form action="https://formly.email/submit" method="POST">
  <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY">

  <!-- form fields -->
  <input type="text" name="name" id="name" required>
  <input type="email" name="email" id="email" required>
  <textarea name="message" id="message" rows="4" required></textarea>
  <button type="submit">Send Message</button>
</form>

Tip: Always include a hidden honeypot field to reduce spam.

Form Field Reference

formly.email supports various field types and attributes. Here's a comprehensive reference:

Field Type Required Description
access_key hidden Yes Your formly.email access key
redirect hidden No URL to redirect after submission
subject hidden No Custom email subject line

💡 Pro Tip: Use a custom "redirect" URL with UTM parameters to track submissions in analytics.

Email Customization

Email Subject Line

Customize your notification email subject in two different ways:

1. Static Subject

<input type="hidden" name="subject" value="New Contact Form Submission">

2. User-Provided Subject

<input type="text" name="subject" placeholder="Subject">

From Name

Customize the sender name in your notification emails:

<input type="hidden" name="from_name" value="Your Website Name">

Reply-To Address

By default, formly.email uses the email field as the reply-to address. You can customize this:

<input type="hidden" name="replyto" value="custom@example.com">

Redirects & Thank You Pages

Customize what happens after a successful form submission:

Default Success Page

By default, users will see our success page after submission. To prevent stale form data when users click "Go Back", add this script:

<script>
window.onload = function() {
  document.getElementById("form").reset();
};
</script>

Custom Redirect URL

Redirect users to your own thank you page:

<input type="hidden" name="redirect" value="https://yourwebsite.com/thank-you">

Always use absolute URLs (starting with https://) for redirects. Relative URLs won't work.

Same-Page Success Message

For JavaScript-based forms, you can show success messages without redirecting:

const form = document.getElementById('contact-form');
form.addEventListener('submit', async (e) => {
  try {
    e.preventDefault();
    const formData = new FormData(form);
    const response = await fetch('https://formly.email/submit', {
        method: 'POST',
        body: formData
    });
    
    const result = await response.json();
    
    if (result.success) {
        showMessage('Thank you for your submission!', 'success');
        form.reset();
    } else {
        showMessage(result.message, 'error');
    }
  } catch (error) {
    showMessage('An error occurred. Please try again.', 'error');
  }
});

Spam Protection

formly.email provides multiple layers of spam protection to keep your forms secure:

Server-Side Protection

All form submissions are automatically checked for spam on our servers. This provides basic protection without any additional setup.

Honeypot Protection

Add a hidden field to catch automated submissions:

<form action="https://formly.email/submit" method="POST">
  <input type="hidden" name="access_key" value="YOUR_ACCESS_KEY">
  <input type="hidden" name="honeypot" value="website">
  <div style="display:none">
    <input type="text" name="website">
  </div>
  <!-- Your form fields -->
</form>

CAPTCHA Integration

For enhanced protection, you can integrate with popular CAPTCHA services:

  • hCaptcha
  • reCAPTCHA v2

💡 Pro Tip: Start with honeypot protection and add CAPTCHA only if you experience significant spam issues.

AJAX & JavaScript Integration

Handle form submissions asynchronously with JavaScript for a better user experience.

Basic AJAX Submission

const form = document.querySelector('form');
form.addEventListener('submit', async (e) => {
  try {
    e.preventDefault();
    const formData = new FormData(form);
    const response = await fetch('https://formly.email/submit', {
        method: 'POST',
        body: formData
    });
    
    const result = await response.json();
    
    if (result.success) {
        // Show success message
        showMessage('Thank you for your submission!', 'success');
    } else {
        // Show error message
        showMessage(result.message, 'error');
    }
  } catch (error) {
    console.error('Error:', error);
    showMessage('An error occurred. Please try again.', 'error');
  }
});

function showMessage(message, type) {
  const messageDiv = document.createElement('div');
  messageDiv.className = `message ${type}`;
  messageDiv.textContent = message;
  form.appendChild(messageDiv);

  setTimeout(() => {
    messageDiv.remove();
  }, 5000);
}

Autoresponder Setup

Configure automatic responses to be sent to users who submit your forms.

Basic Autoresponder

<form action="https://formly.email/submit" method="POST">
<input type="hidden" name="access_key" value="YOUR_ACCESS_KEY">
<input type="hidden" name="autorespond" value="true">
<!-- form fields -->
</form>

Custom Autoresponder Template

Configure your autoresponder template in the dashboard:

  • Custom subject line
  • Personalized message
  • HTML or plain text format
  • Variable substitution

Advanced Features

Take your forms to the next level with these advanced features.

Custom Templates

Create custom email templates with:

  • HTML/CSS styling
  • Dynamic content
  • Custom branding
  • Multiple templates

Custom Headers

Add custom headers to your form submissions for better tracking and integration:

<form action="https://formly.email/submit" method="POST">
<input type="hidden" name="access_key" value="YOUR_ACCESS_KEY">
<input type="hidden" name="headers" value='{
  "X-Source": "Contact Form",
  "X-Form-Version": "1.0",
  "X-Integration": "WordPress",
  "X-Environment": "production"
}'>
<!-- form fields -->
</form>

💡 Pro Tip: Use headers to track form versions, integration sources, and environments for better debugging and analytics.

Metadata

Add rich metadata to your submissions for better tracking and organization:

Source Tracking

<input type="hidden" name="metadata[source]" value="landing_page">
<input type="hidden" name="metadata[page_url]" value="https://example.com/contact">
<input type="hidden" name="metadata[referrer]" value="https://google.com">

UTM Parameters

<input type="hidden" name="metadata[utm_source]" value="newsletter">
<input type="hidden" name="metadata[utm_medium]" value="email">
<input type="hidden" name="metadata[utm_campaign]" value="spring_sale">
<input type="hidden" name="metadata[utm_term]" value="discount">
<input type="hidden" name="metadata[utm_content]" value="banner_1">

Custom Fields

<input type="hidden" name="metadata[form_id]" value="contact_form_1">
<input type="hidden" name="metadata[form_version]" value="2.0">
<input type="hidden" name="metadata[user_type]" value="premium">
<input type="hidden" name="metadata[integration]" value="shopify">

Submission Context

<input type="hidden" name="metadata[submission_time]" value="2024-03-20T15:30:00Z">
<input type="hidden" name="metadata[user_agent]" value="Mozilla/5.0...">
<input type="hidden" name="metadata[ip_address]" value="192.168.1.1">
<input type="hidden" name="metadata[language]" value="en-US">

⚠️ Note: Be mindful of privacy regulations when collecting metadata. Only collect what you need and inform users about data collection.

Dynamic Metadata with JavaScript

const form = document.getElementById('contact-form');
form.addEventListener('submit', function(e) {
  e.preventDefault();
  
  const formData = new FormData(form);
  
  // Add dynamic metadata
  formData.append('metadata[submission_time]', new Date().toISOString());
  formData.append('metadata[page_url]', window.location.href);
  formData.append('metadata[referrer]', document.referrer);
  formData.append('metadata[user_agent]', navigator.userAgent);
  
  // Submit form
  fetch('https://formly.email/submit', {
    method: 'POST',
    body: formData
  })
  .then(response => response.json())
  .then(data => {
    // Handle response
  });
});

Security & Privacy

formly.email takes security and privacy seriously. Here's how we protect your data:

Security Features

  • HTTPS encryption
  • Access key authentication
  • Rate limiting
  • Spam protection
  • Data encryption at rest

Privacy Features

  • GDPR compliance
  • Data retention policies

We recommend reviewing our security and privacy documentation for detailed information about data handling and compliance.

Troubleshooting

Common issues and their solutions:

Form Not Submitting

  • Check your access key
  • Verify form action URL
  • Check for JavaScript errors
  • Verify required fields

Email Notifications Not Working

  • Check spam folder
  • Verify email settings
  • Verify recipient addresses

Spam Protection Issues

  • Verify honeypot configuration
  • Check CAPTCHA settings
  • Review rate limiting
  • Check IP blocking

Frequently Asked Questions

General Questions

How do I get started?

Just submit your email to get your access key, then add the form to your website. No signup or backend setup required!

Is there a free plan?

Yes! We offer a generous free plan with basic features. Check our pricing page for details.

How secure is formly.email?

We use industry-standard security practices including HTTPS, encryption, and regular security audits.

Technical Questions

Can I use formly.email with any framework?

Yes! formly.email works with any framework or plain HTML.

How do I handle file uploads?

Add a file input to your form and we'll handle the rest. Files are securely stored and accessible via email.

Happy form building! 🚀