### Setup and Configuration Commands

Source: https://github.com/forminit/forminit-python/blob/main/examples/django/README.md

A collection of shell commands required to initialize the Django environment for Forminit. This includes installing dependencies, setting API credentials, and preparing the database.

```bash
pip install -r requirements.txt
export FORMINIT_API_KEY="your-api-key"
export FORMINIT_FORM_ID="your-form-id"
python manage.py migrate
python manage.py runserver
```

--------------------------------

### Install Forminit Python SDK

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Installs the Forminit Python SDK using pip. This is the first step to integrate Forminit into your Python projects.

```bash
pip install forminit
```

--------------------------------

### Integrate Forminit with Flask

Source: https://context7.com/forminit/forminit-python/llms.txt

A complete example of integrating Forminit into a Flask route. It highlights extracting the client IP address from proxy headers and setting user context for geolocation tracking.

```python
import os
from flask import Flask, request, jsonify
from forminit import ForminitClient

app = Flask(__name__)

@app.route("/submit", methods=["POST"])
def submit_form():
    client_ip = request.headers.get("X-Forwarded-For", request.remote_addr)
    if client_ip and "," in client_ip:
        client_ip = client_ip.split(",")[0].strip()

    client = ForminitClient(api_key=os.environ.get("FORMINIT_API_KEY"))
    client.set_user_info(
        ip=client_ip,
        user_agent=request.headers.get("User-Agent", ""),
        referer=request.headers.get("Referer")
    )

    form_data = request.form.to_dict()
    result = client.submit(form_id=os.environ.get("FORMINIT_FORM_ID"), data=form_data)
    client.close()

    if "error" in result:
        return jsonify({"success": False, "message": result["error"]["message"]}), 400

    return jsonify({"success": True, "submissionId": result["data"]["hashId"]})
```

--------------------------------

### Define Form Block Types

Source: https://context7.com/forminit/forminit-python/llms.txt

Provides a comprehensive example of all supported Forminit block types, including tracking, sender, input fields, and file metadata. This structure ensures type-safe submissions when using the Forminit Python SDK.

```python
from forminit import ForminitClient
from forminit.types import FormSubmissionData

# Type-safe form submission with all block types
submission: FormSubmissionData = {
    "blocks": [
        {
            "type": "tracking",
            "properties": {
                "utmSource": "google",
                "utmMedium": "cpc",
                "utmCampaign": "spring_sale",
                "gclid": "abc123",
                "fbclid": "xyz789",
                "msclkid": "def456"
            }
        },
        {
            "type": "sender",
            "properties": {
                "email": "user@example.com",
                "firstName": "John",
                "lastName": "Doe",
                "fullName": "John Doe",
                "phone": "+1-555-0123",
                "company": "Acme Corp",
                "position": "Software Engineer",
                "address": "123 Main St",
                "city": "San Francisco",
                "country": "United States"
            }
        },
        {"type": "text", "name": "message", "value": "Hello!"},
        {"type": "number", "name": "quantity", "value": 5},
        {"type": "email", "name": "alternate_email", "value": "alt@example.com"},
        {"type": "url", "name": "website", "value": "https://example.com"},
        {"type": "phone", "name": "mobile", "value": "+1-555-9999"},
        {"type": "rating", "name": "satisfaction", "value": 5},
        {"type": "date", "name": "preferred_date", "value": "2024-06-15"},
        {"type": "country", "name": "shipping_country", "value": "US"},
        {"type": "select", "name": "department", "value": "Sales"},
        {"type": "radio", "name": "contact_method", "value": "email"},
        {"type": "checkbox", "name": "interests", "value": ["products", "services", "support"]},
        {
            "type": "file",
            "name": "attachment",
            "value": "https://storage.example.com/file.pdf",
            "metadata": {
                "filename": "document.pdf",
                "size": 102400,
                "mimeType": "application/pdf"
            }
        }
    ]
}

client = ForminitClient(api_key="your-api-key")
result = client.submit(form_id="your-form-id", data=submission)
client.close()
```

--------------------------------

### Contact Form HTML with Django Templating

Source: https://github.com/forminit/forminit-python/blob/main/examples/django/contactform/templates/contactform/index.html

This snippet shows the HTML structure for a contact form using Django's template tags. It includes a CSRF token for security and input fields for name, email, and message. The form is linked to a JavaScript event listener for submission.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Contact Us</title>
    <style>
        body { font-family: Arial, sans-serif; max-width: 600px; margin: 50px auto; padding: 20px; }
        .form-group { margin-bottom: 15px; }
        label { display: block; margin-bottom: 5px; font-weight: bold; }
        input, textarea { width: 100%; padding: 8px; border: 1px solid #ddd; border-radius: 4px; box-sizing: border-box; }
        textarea { height: 100px; }
        button { background: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer; }
        button:hover { background: #0056b3; }
        .success { color: green; margin-top: 10px; }
        .error { color: red; margin-top: 10px; }
    </style>
</head>
<body>
    <h1>Contact Us</h1>
    <form id="contactForm" method="post">
        {% csrf_token %}
        <div class="form-group">
            <label for="name">Name:</label>
            <input type="text" id="name" name="name" required>
        </div>
        <div class="form-group">
            <label for="email">Email:</label>
            <input type="email" id="email" name="email" required>
        </div>
        <div class="form-group">
            <label for="message">Message:</label>
            <textarea id="message" name="message" required></textarea>
        </div>
        <button type="submit">Send Message</button>
    </form>
    <div id="status"></div>

    <script>
        document.getElementById('contactForm').addEventListener('submit', async (e) => {
            e.preventDefault();
            const formData = new FormData(e.target);
            const statusDiv = document.getElementById('status');
            statusDiv.textContent = 'Sending...';
            statusDiv.className = '';
            try {
                const response = await fetch('{% url "submit" %}', {
                    method: 'POST',
                    body: formData,
                    headers: {
                        'X-CSRFToken': formData.get('csrfmiddlewaretoken')
                    }
                });
                const result = await response.json();
                if (result.success) {
                    statusDiv.textContent = 'Message sent successfully!';
                    statusDiv.className = 'success';
                    e.target.reset();
                } else {
                    statusDiv.textContent = 'Error: ' + (result.message || 'Unknown error');
                    statusDiv.className = 'error';
                }
            } catch (error) {
                statusDiv.textContent = 'Error: ' + error.message;
                statusDiv.className = 'error';
            }
        });
    </script>
</body>
</html>
```

--------------------------------

### Configure ForminitClient Options

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Shows how to initialize `ForminitClient` with various configuration options, including API key, proxy URL, and base URL.

```python
from forminit import ForminitClient

client = ForminitClient(
    api_key="your-api-key",  # Required for server-side usage
    proxy_url=None,           # Optional: proxy URL for client-side usage
    base_url="https://forminit.com",  # Optional: override base URL
)
```

--------------------------------

### Client Configuration

Source: https://context7.com/forminit/forminit-python/llms.txt

Demonstrates how to initialize the ForminitClient and AsyncForminitClient with different configuration options, including API keys, base URLs, proxy support, and environment variables.

```APIDOC
## Client Configuration Options

Configure the client with custom options including proxy support for client-side usage scenarios.

### Standard Server-Side Configuration

```python
from forminit import ForminitClient

client = ForminitClient(
    api_key="your-api-key",              # Required for server-side
    base_url="https://forminit.com"      # Optional: override base URL
)
```

### Configuration with Proxy

```python
from forminit import ForminitClient

proxy_client = ForminitClient(
    proxy_url="https://your-proxy.com/api/forminit",  # Route through your proxy
    api_key=None  # API key handled by proxy
)
```

### Async Client Configuration

```python
from forminit import AsyncForminitClient

async_client = AsyncForminitClient(
    api_key="your-api-key",
    base_url="https://forminit.com"
)
```

### Environment Variable Configuration

Set environment variables `FORMINIT_API_KEY` and `FORMINIT_FORM_ID`.

```python
import os
from forminit import ForminitClient

client = ForminitClient(api_key=os.environ.get("FORMINIT_API_KEY"))
```
```

--------------------------------

### Configure Forminit Client Options

Source: https://context7.com/forminit/forminit-python/llms.txt

Demonstrates how to initialize the Forminit client for server-side or client-side proxy scenarios. It also shows how to retrieve API keys from environment variables for secure configuration.

```python
from forminit import ForminitClient, AsyncForminitClient
import os

# Standard server-side configuration
client = ForminitClient(
    api_key="your-api-key",
    base_url="https://forminit.com"
)

# Configuration with proxy for client-side scenarios
proxy_client = ForminitClient(
    proxy_url="https://your-proxy.com/api/forminit",
    api_key=None
)

# Async client with same options
async_client = AsyncForminitClient(
    api_key="your-api-key",
    base_url="https://forminit.com"
)

# Environment variable configuration
client = ForminitClient(api_key=os.environ.get("FORMINIT_API_KEY"))
```

--------------------------------

### Submit Forms with Synchronous Client

Source: https://context7.com/forminit/forminit-python/llms.txt

Demonstrates how to use the ForminitClient for synchronous form submissions. It covers client initialization, setting user metadata, and handling structured block data.

```python
from forminit import ForminitClient

client = ForminitClient(api_key="your-api-key")

client.set_user_info(
    ip="203.0.113.10",
    user_agent="Mozilla/5.0...",
    referer="https://example.com"
)

result = client.submit(
    form_id="your-form-id",
    data={
        "blocks": [
            {"type": "sender", "properties": {"email": "john@example.com", "firstName": "John", "lastName": "Doe"}},
            {"type": "text", "name": "message", "value": "Hello from Forminit!"},
            {"type": "email", "name": "contact_email", "value": "contact@example.com"},
            {"type": "rating", "name": "satisfaction", "value": 5}
        ]
    },
    tracking={"utmSource": "newsletter", "utmMedium": "email", "utmCampaign": "spring2024"}
)

if "error" in result:
    print(f"Error: {result['error']['message']}")
else:
    print(f"Success! Submission ID: {result['data']['hashId']}")

client.close()
```

--------------------------------

### Integrate Forminit with FastAPI

Source: https://context7.com/forminit/forminit-python/llms.txt

An asynchronous implementation for FastAPI. It utilizes the AsyncForminitClient for non-blocking I/O and demonstrates structured block-based data submission.

```python
import os
from fastapi import FastAPI, Request, HTTPException, Form
from forminit import AsyncForminitClient

app = FastAPI()

@app.post("/submit")
async def submit_form(request: Request, name: str = Form(...), email: str = Form(...), message: str = Form(...)):
    forwarded_for = request.headers.get("X-Forwarded-For")
    client_ip = forwarded_for.split(",")[0].strip() if forwarded_for else (request.client.host if request.client else "127.0.0.1")

    async with AsyncForminitClient(api_key=os.environ.get("FORMINIT_API_KEY")) as client:
        client.set_user_info(ip=client_ip, user_agent=request.headers.get("User-Agent", ""), referer=request.headers.get("Referer"))
        result = await client.submit(
            form_id=os.environ.get("FORMINIT_FORM_ID"),
            data={
                "blocks": [
                    {"type": "sender", "properties": {"email": email, "fullName": name}},
                    {"type": "text", "name": "message", "value": message}
                ]
            }
        )

    if "error" in result:
        raise HTTPException(status_code=result["error"].get("code", 400), detail=result["error"]["message"])

    return {"success": True, "submissionId": result["data"]["hashId"]}
```

--------------------------------

### Submit Form Data with Forminit Python SDK

Source: https://context7.com/forminit/forminit-python/llms.txt

Demonstrates the basic workflow for submitting form data to Forminit. It shows how to map form fields using the required prefix conventions and handle the response object.

```python
result = client.submit(
    form_id="your-form-id",
    data={
        "fi-sender-fullName": "John Doe",
        "fi-sender-email": "john@example.com",
        "fi-sender-phone": "+1-555-0100",
        "fi-sender-company": "Acme Inc",
        "fi-text-message": "I have a question about your services.",
        "fi-text-subject": "General Inquiry",
        "fi-rating-satisfaction": "4"
    }
)

if "error" in result:
    print(f"Submission failed: {result['error']['message']}")
else:
    print(f"Form submitted successfully: {result['data']['hashId']}")

client.close()
```

--------------------------------

### Form-Style Data Submission with ForminitClient

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Illustrates submitting flat form data, mimicking an HTML form submission, using the `client.submit` method. This is useful for simpler data structures.

```python
result = client.submit(
    form_id="your-form-id",
    data={
        "fi-sender-fullName": "John Doe",
        "fi-sender-email": "john@example.com",
        "fi-text-message": "Hello!",
    },
)
```

--------------------------------

### Synchronous Form Submission with ForminitClient

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Demonstrates how to initialize and use the synchronous ForminitClient to submit form data. It includes setting user information for tracking and handling the submission result.

```python
from forminit import ForminitClient

# Initialize client with your API key
client = ForminitClient(api_key="your-api-key")

# Set user info for tracking (optional)
# Note: Set user info from the client request for accurate tracking
# This ensures proper geolocation and analytics for the actual user
client.set_user_info(
    ip="203.0.113.10",  # Client's IP from X-Forwarded-For or X-Real-IP header
    user_agent="Mozilla/5.0...",  # Client's User-Agent header
    referer="https://example.com",  # Client's Referer header
)

# Submit form data
result = client.submit(
    form_id="your-form-id",
    data={
        "blocks": [
            {"type": "text", "name": "message", "value": "Hello!"},
            {"type": "email", "name": "email", "value": "user@example.com"},
        ]
    },
    tracking={"utmSource": "newsletter", "utmMedium": "email"},
)

if "error" in result:
    print(f"Error: {result['error']['message']}")
else:
    print(f"Success! Submission ID: {result['data']['hashId']}")
    if "redirectUrl" in result:
        print(f"Redirect to: {result['redirectUrl']}")

client.close()
```

--------------------------------

### Asynchronous Form Submission with AsyncForminitClient

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Demonstrates the asynchronous usage of the Forminit SDK using `AsyncForminitClient`. This is suitable for non-blocking operations in asynchronous Python applications.

```python
import asyncio
from forminit import AsyncForminitClient


async def main():
    async with AsyncForminitClient(api_key="your-api-key") as client:
        result = await client.submit(
            form_id="your-form-id",
            data={
                "blocks": [
                    {"type": "text", "name": "message", "value": "Hello!"},
                ]
            },
        )

        if "error" in result:
            print(f"Error: {result['error']['message']}")
        else:
            print(f"Success! Submission ID: {result['data']['hashId']}")


asyncio.run(main())
```

--------------------------------

### Web Framework Integration (Flask) with ForminitClient

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Shows how to integrate ForminitClient into a Flask web application. It emphasizes extracting client information from request headers for accurate tracking.

```python
from flask import Flask, request
from forminit import ForminitClient

app = Flask(__name__)

@app.route("/submit", methods=["POST"])
def submit():
    client = ForminitClient(api_key="your-api-key")
    
    # Extract client information from request headers for accurate tracking
    # Note: Use X-Forwarded-For when behind proxies/load balancers
    client_ip = request.headers.get("X-Forwarded-For", request.remote_addr)
    if client_ip and "," in client_ip:
        client_ip = client_ip.split(",")[0].strip()  # Get first IP
    
    client.set_user_info(
        ip=client_ip,
        user_agent=request.headers.get("User-Agent", ""),
        referer=request.headers.get("Referer"),
    )
    
    result = client.submit(
        form_id="your-form-id",
        data=request.form.to_dict(),
    )
    
    client.close()
    return result
```

--------------------------------

### Submit Form via Django View

Source: https://context7.com/forminit/forminit-python/llms.txt

Demonstrates how to create a Django view that processes form submissions. It handles client IP extraction from request headers, configures the Forminit client, and returns a JSON response based on the submission result.

```python
import os
import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
from forminit import ForminitClient

@csrf_exempt
@require_http_methods(["POST"])
def submit_form(request):
    # Extract client IP from Django META headers
    forwarded_for = request.META.get("HTTP_X_FORWARDED_FOR")
    client_ip = forwarded_for.split(",")[0].strip() if forwarded_for else (
        request.META.get("REMOTE_ADDR", "127.0.0.1")
    )

    # Create and configure client
    client = ForminitClient(api_key=os.environ.get("FORMINIT_API_KEY"))
    client.set_user_info(
        ip=client_ip,
        user_agent=request.META.get("HTTP_USER_AGENT", ""),
        referer=request.META.get("HTTP_REFERER")
    )

    # Parse JSON body
    data = json.loads(request.body)

    # Build structured submission
    result = client.submit(
        form_id=os.environ.get("FORMINIT_FORM_ID"),
        data={
            "blocks": [
                {
                    "type": "sender",
                    "properties": {
                        "email": data.get("email"),
                        "firstName": data.get("firstName"),
                        "lastName": data.get("lastName")
                    }
                },
                {"type": "text", "name": "message", "value": data.get("message")}
            ]
        },
        tracking=data.get("tracking")
    )

    client.close()

    if "error" in result:
        return JsonResponse(
            {"success": False, "error": result["error"]},
            status=result["error"].get("code", 400)
        )

    return JsonResponse({
        "success": True,
        "data": result["data"],
        "redirectUrl": result.get("redirectUrl")
    })
```

--------------------------------

### Set Forminit Environment Variables

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Configures Forminit using environment variables for API key and form ID. This is a common practice for managing credentials and settings.

```bash
export FORMINIT_API_KEY="your-api-key"
export FORMINIT_FORM_ID="your-form-id"
```

--------------------------------

### Error Handling and Response Processing

Source: https://context7.com/forminit/forminit-python/llms.txt

Illustrates how to handle potential errors returned by the SDK, such as validation errors, missing API keys, and network issues, as well as processing successful submission responses.

```APIDOC
## Error Handling

The SDK returns structured error responses for validation failures, network errors, and API errors.

### Handling Errors and Success Responses

```python
from forminit import ForminitClient

client = ForminitClient(api_key="your-api-key")

result = client.submit(
    form_id="your-form-id",
    data={
        "blocks": [
            {"type": "email", "name": "email", "value": "invalid-email"}
        ]
    }
)

if "error" in result:
    error = result["error"]
    print(f"Success: {error['success']}")        # False
    print(f"Error Code: {error.get('code')}")    # 400
    print(f"Error Type: {error['error']}")       # "VALIDATION_ERROR"
    print(f"Message: {error['message']}")        # "Invalid email format"
    print(f"Field: {error.get('fieldName')}")    # "email" (if field-specific)

    # Handle specific error types
    if error["error"] == "MISSING_API_KEY":
        print("Please configure your API key")
    elif error["error"] == "VALIDATION_ERROR":
        print(f"Fix the field: {error.get('fieldName')}")
    elif error["error"] == "HTTP_ERROR":
        print("Network or server error occurred")
else:
    # Success response
    data = result["data"]
    print(f"Submission ID: {data['hashId']}")
    print(f"Submitted at: {data['date']}")
    print(f"Location: {data['submissionInfo']['location']['country']}")

    if "redirectUrl" in result:
        print(f"Redirect user to: {result['redirectUrl']}")

client.close()
```
```

--------------------------------

### Submit Forms with Asynchronous Client

Source: https://context7.com/forminit/forminit-python/llms.txt

Demonstrates the use of AsyncForminitClient for non-blocking form submissions in async frameworks like FastAPI. It utilizes an async context manager for resource management.

```python
import asyncio
from forminit import AsyncForminitClient

async def submit_contact_form():
    async with AsyncForminitClient(api_key="your-api-key") as client:
        client.set_user_info(
            ip="192.168.1.100",
            user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
            referer="https://mysite.com/contact"
        )

        result = await client.submit(
            form_id="contact-form-id",
            data={
                "blocks": [
                    {"type": "sender", "properties": {"email": "user@example.com", "fullName": "Jane Smith", "company": "Acme Corp"}},
                    {"type": "text", "name": "subject", "value": "Partnership Inquiry"},
                    {"type": "text", "name": "message", "value": "I'd like to discuss..."},
                    {"type": "phone", "name": "phone", "value": "+1-555-0123"}
                ]
            },
            tracking={"utmSource": "google", "gclid": "abc123"}
        )

        if "error" in result:
            return {"success": False, "error": result["error"]["message"]}

        return {"success": True, "submissionId": result["data"]["hashId"], "redirectUrl": result.get("redirectUrl")}

response = asyncio.run(submit_contact_form())
print(response)
```

--------------------------------

### Utilize Forminit Type Definitions for Form Submission

Source: https://github.com/forminit/forminit-python/blob/main/README.md

Demonstrates using type hints from `forminit.types` for building type-safe form submissions. This improves code reliability and maintainability.

```python
from forminit.types import (
    FormBlock,
    FormSubmissionData,
    FormResponse,
    TrackingBlock,
    SenderBlock,
    TextBlock,
    # ... and more
)

# Type-safe form building
submission: FormSubmissionData = {
    "blocks": [
        {
            "type": "sender",
            "properties": {
                "email": "user@example.com",
                "firstName": "John",
                "lastName": "Doe",
            },
        },
        {"type": "text", "name": "message", "value": "Hello!"},
    ]
}
```

--------------------------------

### Handle API Errors and Responses

Source: https://context7.com/forminit/forminit-python/llms.txt

Explains how to process form submission results, including checking for error flags, parsing validation messages, and accessing successful submission data.

```python
from forminit import ForminitClient

client = ForminitClient(api_key="your-api-key")

result = client.submit(
    form_id="your-form-id",
    data={
        "blocks": [
            {"type": "email", "name": "email", "value": "invalid-email"}
        ]
    }
)

if "error" in result:
    error = result["error"]
    print(f"Error Type: {error['error']}")
    if error["error"] == "VALIDATION_ERROR":
        print(f"Fix the field: {error.get('fieldName')}")
else:
    data = result["data"]
    print(f"Submission ID: {data['hashId']}")

client.close()
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.