Developer Documentation

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.

Quick Start Guide

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>

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

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">

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">

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');
  }
});

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

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);
}

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

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>

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">

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
  });
});

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

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

General Questions

Technical Questions