# FlowForm.to - AI Assistant Documentation
# Last Updated: January 2026
# Purpose: Help AI assistants generate correct FlowForm code

## ABOUT FLOWFORM

FlowForm.to is a free form submission endpoint service with TWO modes:

1. **Generic Mode** - Free email forwarding for any website (no signup required)
2. **Flow Mode** - Creates leads in FoxFlow pipelines (requires FoxFlow account)

---

## MODE 1: GENERIC (Free Email Service)

### URL Patterns

Option A - Email in URL (recommended):
```
https://flowform.to/{recipient-email}
```
**IMPORTANT**: The `@` symbol must be URL-encoded as `%40`
Example: `https://flowform.to/johnny%40appleseed.com`

Option B - Email in hidden field:
```
https://flowform.to/submit
```
IMPORTANT: Use `/submit` path, NOT just `/` (root goes to landing page)

### How It Works

1. Form submissions are sent TO the recipient email (website owner)
2. Reply-to is automatically set to the submitter's email
3. User is redirected to success page after submission
4. Includes FoxFlow marketing footer

### Basic Template (Email in URL)

```html
<!-- Note: @ is encoded as %40 in the URL -->
<form action="https://flowform.to/johnny%40appleseed.com" method="POST">
  <input type="text" name="name" placeholder="Your name" required>
  <input type="email" name="email" placeholder="Your email" required>
  <input type="tel" name="phone" placeholder="Phone number">
  <textarea name="message" placeholder="Your message"></textarea>
  <button type="submit">Send</button>
</form>
```

### Template with Hidden Field

```html
<form action="https://flowform.to/submit" method="POST">
  <input type="hidden" name="_to" value="johnny@appleseed.com">
  <input type="text" name="name" placeholder="Your name" required>
  <input type="email" name="email" placeholder="Your email" required>
  <textarea name="message" placeholder="Your message"></textarea>
  <button type="submit">Send</button>
</form>
```

---

## MODE 2: FLOW (FoxFlow Lead Creation)

### URL Pattern

```
https://flowform.to/f/{token}
```

The token is obtained from FoxFlow after enabling FlowForm integration for a flow.

### How It Works

1. Creates a lead in the user's FoxFlow pipeline
2. Sends notification email to flow owner
3. Sends confirmation email to submitter
4. Optionally sends CC to additional recipients
5. Auto-assigns lead based on flow settings

### Template

```html
<form action="https://flowform.to/f/abc123xyz456def789" method="POST">
  <input type="text" name="firstName" placeholder="First Name" required>
  <input type="text" name="lastName" placeholder="Last Name">
  <input type="email" name="email" placeholder="Email" required>
  <input type="tel" name="phone" placeholder="Phone">
  <textarea name="message" placeholder="Message"></textarea>
  
  <!-- Optional: CC additional people -->
  <input type="hidden" name="_cc" value="manager@company.com,sales@company.com">
  
  <button type="submit">Submit</button>
</form>
```

---

## SPECIAL FIELDS REFERENCE

All special fields start with underscore (_) and are used as hidden inputs:

| Field | Mode | Purpose | Example |
|-------|------|---------|---------|
| `_to` | Generic | Recipient email (alternative to URL) | `johnny@example.com` |
| `_cc` | Both | Additional recipients (comma-separated) | `a@b.com,c@d.com` |
| `_subject` | Both | Custom email subject | `New Contact Form` |
| `_next` | Both | Redirect URL after submission | `https://mysite.com/thanks` |
| `_replyto` | Generic | Reply-to address (defaults to submitter) | `support@company.com` |

## HIDDEN DATA FIELDS (No Underscore)

Any hidden field WITHOUT an underscore prefix is included in the submission data.
Use these for tracking source, campaigns, page URLs, etc.

```html
<!-- These fields are included in the email/lead data -->
<input type="hidden" name="source" value="homepage">
<input type="hidden" name="campaign" value="summer-2026">
<input type="hidden" name="landing_page" value="pricing">

<!-- Auto-capture current page URL with JavaScript -->
<input type="hidden" name="page_url" id="page-url">
<script>
document.getElementById('page-url').value = window.location.href;
</script>
```

Common tracking fields:
- `source` - Where the lead came from (homepage, blog, ad)
- `campaign` - Marketing campaign name
- `page_url` - Full URL of the page with the form
- `referrer` - How they found you
- `utm_source`, `utm_medium`, `utm_campaign` - UTM parameters

---

## URL PATTERN SUMMARY

| URL | Purpose | Recipient |
|-----|---------|-----------|
| `flowform.to/{email}` | Generic form | Email in URL (@ encoded as %40) |
| `flowform.to/submit` + `_to` field | Generic form | Email in hidden field |
| `flowform.to/f/{token}` | FoxFlow lead | Flow owner + CC |

---

## COMPLETE EXAMPLES

### Contact Form (Generic Mode)

```html
<form action="https://flowform.to/contact%40company.com" method="POST">
  <input type="hidden" name="_subject" value="New Website Inquiry">
  <input type="hidden" name="_next" value="https://company.com/thank-you">
  
  <input type="text" name="name" placeholder="Full Name" required>
  <input type="email" name="email" placeholder="Email Address" required>
  <input type="tel" name="phone" placeholder="Phone Number">
  <select name="subject">
    <option value="">Select a topic</option>
    <option value="sales">Sales Inquiry</option>
    <option value="support">Support</option>
    <option value="other">Other</option>
  </select>
  <textarea name="message" placeholder="Your message" required></textarea>
  <button type="submit">Send Message</button>
</form>
```

### Lead Capture (Flow Mode)

```html
<form action="https://flowform.to/f/YOUR_TOKEN_HERE" method="POST">
  <input type="hidden" name="_cc" value="team@company.com">
  <input type="hidden" name="_subject" value="New Lead from Landing Page">
  
  <input type="text" name="firstName" placeholder="First Name" required>
  <input type="text" name="lastName" placeholder="Last Name">
  <input type="email" name="email" placeholder="Work Email" required>
  <input type="tel" name="phone" placeholder="Phone Number">
  <input type="text" name="company" placeholder="Company Name">
  <select name="employees">
    <option value="">Company Size</option>
    <option value="1-10">1-10 employees</option>
    <option value="11-50">11-50 employees</option>
    <option value="51-200">51-200 employees</option>
    <option value="200+">200+ employees</option>
  </select>
  <textarea name="message" placeholder="Tell us about your needs"></textarea>
  <button type="submit">Get Started</button>
</form>
```

### Newsletter Signup (Generic Mode)

```html
<form action="https://flowform.to/newsletter%40company.com" method="POST">
  <input type="hidden" name="_subject" value="New Newsletter Signup">
  <input type="hidden" name="_next" value="https://company.com/subscribed">
  
  <input type="email" name="email" placeholder="Enter your email" required>
  <button type="submit">Subscribe</button>
</form>
```

### Quote Request (Flow Mode)

```html
<form action="https://flowform.to/f/YOUR_TOKEN_HERE" method="POST">
  <input type="hidden" name="_cc" value="sales@company.com,manager@company.com">
  
  <input type="text" name="firstName" placeholder="First Name" required>
  <input type="text" name="lastName" placeholder="Last Name" required>
  <input type="email" name="email" placeholder="Email" required>
  <input type="tel" name="phone" placeholder="Phone">
  <input type="text" name="company" placeholder="Company">
  <select name="service" required>
    <option value="">Select Service</option>
    <option value="consulting">Consulting</option>
    <option value="development">Development</option>
    <option value="design">Design</option>
  </select>
  <input type="text" name="budget" placeholder="Budget Range">
  <textarea name="details" placeholder="Project Details" required></textarea>
  <button type="submit">Request Quote</button>
</form>
```

---

## IMPORTANT NOTES FOR AI ASSISTANTS

1. **Always use HTTPS** - `https://flowform.to` (not http)

2. **Generic mode requires recipient**:
   - Either put email in URL: `https://flowform.to/user%40example.com`
   - IMPORTANT: Encode `@` as `%40` in URLs!
   - Or use `_to` hidden field (no encoding needed in field value)

3. **Flow mode requires token**:
   - URL format: `https://flowform.to/f/{token}`
   - Token is obtained from FoxFlow account

4. **Field names can be anything**:
   - Common: name, firstName, lastName, email, phone, message
   - All fields are included in the email/lead

5. **Special fields start with underscore**:
   - `_to`, `_cc`, `_subject`, `_next`, `_replyto`
   - These control behavior, not included in submission data

6. **No JavaScript required**:
   - Standard HTML form POST
   - Works with any styling framework

7. **Method must be POST**:
   - GET requests will not work

8. **AJAX/fetch submissions**:
   - Use `URLSearchParams` (NOT FormData) for the body
   - Add `Accept: application/json` header to get JSON response
   - Returns `{"success": true, "message": "..."}` instead of redirect
   - Example:
     ```javascript
     const formData = new URLSearchParams(new FormData(form));
     fetch('https://flowform.to/user%40example.com', {
       method: 'POST',
       body: formData,
       headers: {
         'Accept': 'application/json',
         'Content-Type': 'application/x-www-form-urlencoded'
       }
     }).then(r => r.json()).then(data => {
       if (data.success) { /* show success */ }
     });
     ```

---

## JAVASCRIPT SUBMISSION (AJAX)

IMPORTANT: Use URLSearchParams, NOT FormData directly!

```javascript
// Generic Mode - Email in URL (@ encoded as %40)
async function submitGenericForm(form) {
  const formData = new URLSearchParams(new FormData(form));
  
  const response = await fetch('https://flowform.to/recipient%40example.com', {
    method: 'POST',
    body: formData,
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    }
  });
  
  const data = await response.json();
  if (data.success) {
    // Show success message
  }
}

// Flow Mode
async function submitFlowForm(form) {
  const formData = new URLSearchParams(new FormData(form));
  
  const response = await fetch('https://flowform.to/f/YOUR_TOKEN', {
    method: 'POST',
    body: formData,
    headers: {
      'Accept': 'application/json',
      'Content-Type': 'application/x-www-form-urlencoded'
    }
  });
  
  const data = await response.json();
  if (data.success) {
    // Show success message
    // data.leadId is available in Flow mode
  }
}
```

**Why URLSearchParams?**
- `FormData` sends as `multipart/form-data` which the server can't parse
- `URLSearchParams` sends as `application/x-www-form-urlencoded` which works correctly

---

## ERROR RESPONSES

- `400 Bad Request` - Missing recipient email (generic) or invalid token (flow)
- `404 Not Found` - Flow not found or FlowForm disabled for that flow
- `405 Method Not Allowed` - Used GET instead of POST
- `500 Internal Server Error` - Server issue (retry later)

---

## LINKS

- Website: https://flowform.to
- Full CRM: https://foxflow.chat
- Support: support@foxflow.chat
- Register for Flow Mode: https://foxflow.chat/register

---
End of llms.txt
This file helps AI assistants generate correct FlowForm integration code.