# Email Modal Component Documentation

**Last Updated:** 2026-01-10

Complete documentation for the shared email modal component used on tools/calculator pages.

## Overview

The email modal component (`v2/js/shared/email-modal.js`) provides a reusable email collection modal for tools/calculators with HubSpot integration, retry logic, and timeout handling.

## File Location

- **Source:** `v2/js/shared/email-modal.js`
- **Minified:** `v2/js/shared/email-modal.min.js`
- **Dependencies:** `email-modal-utils.js` (must be loaded first)

## Dependencies

**Required:**

- `window.OrdioEmailModalUtils` - Email modal utilities (from `email-modal-utils.js`)
- `window.GTMFormTracker` - GTM form tracking utility (from `gtm-form-tracking.js`)
- `window.utmTracker` - UTM tracking system (from `utm-tracking.js`)

## API

### `submitEmailToHubSpot(config)`

Submit email to HubSpot with retry logic and timeout handling.

**Parameters:**

```javascript
{
    email: string,              // Required: Email address
    name: string,               // Required: Full name (will be parsed into firstname/lastname)
    toolName: string,           // Required: Name of the tool (e.g., 'Minijob-Rechner')
    getToolData: Function,      // Optional: Function to get tool-specific calculation data
    timeout: number,            // Optional: Request timeout in milliseconds (default: 30000)
    maxRetries: number         // Optional: Maximum number of retries (default: 3)
}
```

**Returns:** `Promise<boolean>` - `true` if successful, `false` otherwise

**Example:**

```javascript
const success = await window.OrdioEmailModal.submitEmailToHubSpot({
  email: "user@example.com",
  name: "Max Mustermann",
  toolName: "Minijob-Rechner",
  getToolData: () => ({
    brutto: 520,
    netto: 450,
    // ... calculation results
  }),
  timeout: 30000,
  maxRetries: 3,
});
```

## Integration Pattern

### 1. Load Dependencies

```html
<!-- Load utilities first -->
<script src="/v2/js/shared/email-modal-utils.min.js?v=<?php echo filemtime(__DIR__ . '/../js/shared/email-modal-utils.min.js'); ?>"></script>

<!-- Load email modal component -->
<script src="/v2/js/shared/email-modal.min.js?v=<?php echo filemtime(__DIR__ . '/../js/shared/email-modal.min.js'); ?>"></script>
```

### 2. Use in Alpine.js Component

```javascript
async submitEmail() {
    this.isSubmittingEmail = true;
    this.emailError = '';

    try {
        const success = await window.OrdioEmailModal.submitEmailToHubSpot({
            email: this.exportEmailAddress,
            name: this.exportNameAddress || 'User',
            toolName: 'Minijob-Rechner',
            getToolData: () => this.getCalculationData()
        });

        if (success) {
            this.emailCollected = true;
            this.emailSuccess = true;
            // Store in localStorage
            window.OrdioEmailModalUtils.storeEmail('Minijob-Rechner', this.exportEmailAddress);
        } else {
            this.emailError = 'Es gab einen Fehler beim Senden. Bitte versuchen Sie es erneut.';
        }
    } catch (error) {
        this.emailError = 'Es gab einen Fehler beim Senden. Bitte versuchen Sie es erneut.';
    } finally {
        this.isSubmittingEmail = false;
    }
}
```

## Features

### 1. Retry Logic

- Automatic retry with exponential backoff
- Configurable max retries (default: 3)
- Handles network errors and timeouts

### 2. Timeout Handling

- Configurable timeout (default: 30 seconds)
- Uses `AbortController` for request cancellation
- Throws timeout error if exceeded

### 3. GTM Tracking

- Automatically tracks form submission via `GTMFormTracker`
- Includes form name, form ID, HubSpot form GUID
- Tracks tool-specific content type

### 4. UTM Data Collection

- Automatically collects UTM parameters from `utmTracker`
- Includes `hubspotutk` cookie
- Passes all UTM data to HubSpot API

### 5. Tool Data Collection

- Accepts function to get tool-specific calculation data
- Automatically includes calculation results in HubSpot submission
- Supports any tool-specific data structure

## Request Payload

The component automatically constructs the request payload:

```javascript
{
    email: string,
    name: string,
    tool_name: string,
    tool_description: string,
    tool_data: object,          // From getToolData() function
    source: string,             // "{toolName} Export"
    utm_source: string,
    utm_medium: string,
    utm_campaign: string,
    utm_term: string,
    utm_content: string,
    gclid: string,
    leadSource: string,
    partner: string,
    signuptype: string,         // Default: 'tools_page'
    page_url: string,
    referrer: string,
    hubspotutk: string          // CRITICAL: For Forms API v3 context
}
```

## Error Handling

The component handles errors gracefully:

- **Validation Errors:** Returns `false` if email/name validation fails
- **Network Errors:** Retries with exponential backoff
- **Timeout Errors:** Throws timeout error after max retries
- **API Errors:** Returns `false` if API returns error

## HubSpot Integration

- **Endpoint:** `/v2/api/collect-lead.php`
- **Form GUID:** `a91b263c-7ca2-418b-b35c-9664c30e968b`
- **Constant:** `HUBSPOT_FORM_GUID_TOOLS`
- **Method:** POST
- **Content-Type:** application/json

## GTM Tracking

Automatically tracks form submission:

```javascript
window.GTMFormTracker.trackAPIForm("collect-lead.php", {
  formName: `${toolName} Export Form`,
  formId: `calculator-export-${toolName.toLowerCase().replace(/\s+/g, "-")}`,
  hubspotFormGuid: "a91b263c-7ca2-418b-b35c-9664c30e968b",
  formGuidConstant: "TOOLS",
  contentType: toolName,
});
```

## Usage Examples

### Example 1: Basic Usage

```javascript
const success = await window.OrdioEmailModal.submitEmailToHubSpot({
  email: "user@example.com",
  name: "Max Mustermann",
  toolName: "Prozentrechner",
});
```

### Example 2: With Calculation Data

```javascript
const success = await window.OrdioEmailModal.submitEmailToHubSpot({
  email: this.email,
  name: this.name,
  toolName: "Minijob-Rechner",
  getToolData: () => ({
    brutto: this.brutto,
    netto: this.netto,
    abgaben: this.abgaben,
    // ... more calculation data
  }),
});
```

### Example 3: Custom Timeout and Retries

```javascript
const success = await window.OrdioEmailModal.submitEmailToHubSpot({
  email: this.email,
  name: this.name,
  toolName: "Arbeitstage-Rechner",
  timeout: 60000, // 60 seconds
  maxRetries: 5, // 5 retries
});
```

## Browser Compatibility

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Requires `fetch` API support
- Requires `Promise` support
- Requires `AbortController` support (for timeout)

## Troubleshooting

When gated forms show "Es gab einen Fehler beim Senden" or similar:

- **Logs:** Check `v2/logs/tools_hubspot.log` for request payload, validation, and HubSpot response.
- **Test script:** Run `php v2/scripts/dev-helpers/test-collect-lead.php [base_url]` to verify API and HubSpot (see [Gated Forms Troubleshooting](../../guides/tools-pages/GATED_FORMS_TROUBLESHOOTING.md)).
- **Network tab:** In DevTools → Network, inspect the `collect-lead.php` request: status code and response body (JSON with `success`, `message`, `errors`).
- **API behavior:** The collect-lead API returns HTTP 502 when HubSpot submission fails so the frontend gets `response.ok === false`; frontends must also check `response.body.success` when status is 200.

See [Gated Forms Troubleshooting](../../guides/tools-pages/GATED_FORMS_TROUBLESHOOTING.md) for full diagnosis steps and common causes.

## Related Documentation

- [Gated Forms Troubleshooting](../../guides/tools-pages/GATED_FORMS_TROUBLESHOOTING.md) - Diagnosis and fix for tools gated form failures
- [Email Modal Utilities](EMAIL_MODAL_UTILS.md) - Utilities reference
- [UTM Tracking System](UTM_TRACKING_SYSTEM.md) - UTM tracking documentation
- [GTM Form Tracking](GTM_FORM_TRACKING.md) - Form tracking documentation
- [HubSpot API Reference](../apis/HUBSPOT_API_REFERENCE.md) - API endpoint documentation
- [Form-to-Page Mapping](../forms/FORM_TO_PAGE_MAPPING.md) - Which tools use this component