# Email Modal Utilities Reference

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

Complete reference for the email modal utilities used across tools/calculator pages.

## Overview

The email modal utilities (`v2/js/shared/email-modal-utils.js`) provide shared functions for email validation, localStorage management, cookie handling, and UTM data collection.

## File Location

- **Source:** `v2/js/shared/email-modal-utils.js`
- **Minified:** `v2/js/shared/email-modal-utils.min.js`
- **Global Object:** `window.OrdioEmailModalUtils`

## API Reference

### `validateEmail(email)`

Validate email address format.

**Parameters:**

- `email` (string): Email address to validate

**Returns:** `boolean` - `true` if valid, `false` otherwise

**Example:**

```javascript
if (window.OrdioEmailModalUtils.validateEmail("user@example.com")) {
  // Email is valid
}
```

### `checkEmailCollected(toolName)`

Check if email has been collected for a specific tool.

**Parameters:**

- `toolName` (string): Name of the tool (e.g., 'Minijob-Rechner')

**Returns:** `Object|null` - Email data object `{email: string, collected: true}` or `null`

**Example:**

```javascript
const emailData =
  window.OrdioEmailModalUtils.checkEmailCollected("Minijob-Rechner");
if (emailData) {
  console.log("Email already collected:", emailData.email);
}
```

**Storage Format:**

Uses optimized single-key approach with JSON object:

```json
{
  "collected": true,
  "email": "user@example.com",
  "timestamp": "2026-01-10T12:00:00.000Z"
}
```

**Storage Key Format:**

`ordio_export_email_{toolName}` (lowercase, spaces replaced with underscores)

### `storeEmail(toolName, email)`

Store email address for a specific tool.

**Parameters:**

- `toolName` (string): Name of the tool
- `email` (string): Email address to store

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

**Example:**

```javascript
window.OrdioEmailModalUtils.storeEmail("Minijob-Rechner", "user@example.com");
```

**Storage Format:**

Stores as JSON object with timestamp:

```json
{
  "collected": true,
  "email": "user@example.com",
  "timestamp": "2026-01-10T12:00:00.000Z"
}
```

### `getCookie(name)`

Get cookie value by name.

**Parameters:**

- `name` (string): Cookie name

**Returns:** `string` - Cookie value or empty string

**Example:**

```javascript
const utmSource = window.OrdioEmailModalUtils.getCookie("utm_source");
```

### `getUTMData()`

Get UTM data from UTM tracker or cookies.

**Returns:** `Object` - UTM data object

**Example:**

```javascript
const utmData = window.OrdioEmailModalUtils.getUTMData();
console.log(utmData.utm_source);
console.log(utmData.utm_campaign);
```

**Returned Object:**

```javascript
{
    utm_source: string,
    utm_medium: string,
    utm_campaign: string,
    utm_term: string,
    utm_content: string,
    gclid: string,
    leadSource: string,
    partner: string,
    signuptype: string,
    page_url: string,
    referrer: string,
    hubspotutk: string
}
```

**Data Sources (Priority Order):**

1. `window.utmTracker.getUTMDataForAPI()` (if available)
2. `window.utmTracking` object (fallback)
3. URL parameters (fallback)
4. Cookies (fallback)

### `getHubspotutk()`

Get `hubspotutk` cookie value.

**Returns:** `string` - HubSpot tracking token or empty string

**Example:**

```javascript
const hubspotutk = window.OrdioEmailModalUtils.getHubspotutk();
```

## Storage Management

### localStorage Key Format

**Pattern:** `ordio_export_email_{toolName}`

**Examples:**

- `ordio_export_email_minijob_rechner`
- `ordio_export_email_arbeitstage_rechner`
- `ordio_export_email_prozentrechner`

### Storage Migration

The utilities automatically migrate old storage format to new format:

**Old Format (deprecated):**

- `{toolName}_export_email` → `'true'`
- `{toolName}_export_email_address` → `'user@example.com'`

**New Format:**

- `ordio_export_email_{toolName}` → `{"collected": true, "email": "user@example.com", "timestamp": "..."}`

### Error Handling

All storage operations gracefully handle errors:

- **localStorage disabled:** Returns `null` or `false` without throwing
- **Quota exceeded:** Returns `null` or `false` without throwing
- **Invalid JSON:** Returns `null` without throwing

## Cookie Management

### Supported Cookies

- `utm_source`
- `utm_medium`
- `utm_campaign`
- `utm_term`
- `utm_content`
- `gclid`
- `hubspotutk`
- Other UTM-related cookies

### Cookie Reading

Uses standard `document.cookie` parsing with proper decoding.

## UTM Data Collection

### Priority Order

1. **UTM Tracker** (`window.utmTracker.getUTMDataForAPI()`)

   - Most reliable source
   - Includes processed UTM data
   - Includes lead source detection

2. **UTM Tracking Object** (`window.utmTracking`)

   - Fallback if tracker not available
   - Direct access to UTM properties

3. **URL Parameters**

   - Fallback for direct URL access
   - Parses current URL query string

4. **Cookies**
   - Final fallback
   - Reads from stored cookies

### UTM Parameters Collected

- `utm_source`
- `utm_medium`
- `utm_campaign`
- `utm_term`
- `utm_content`
- `gclid` (Google Click ID)
- `leadSource` (detected lead source)
- `partner` (partner identifier)
- `signuptype` (signup type)
- `page_url` (current page URL)
- `referrer` (referrer URL)
- `hubspotutk` (HubSpot tracking token)

## Usage Examples

### Example 1: Check if Email Already Collected

```javascript
const emailData =
  window.OrdioEmailModalUtils.checkEmailCollected("Minijob-Rechner");
if (emailData && emailData.collected) {
  // Email already collected, skip modal
  this.emailCollected = true;
  this.exportEmailAddress = emailData.email;
}
```

### Example 2: Store Email After Collection

```javascript
if (success) {
  window.OrdioEmailModalUtils.storeEmail(
    "Minijob-Rechner",
    this.exportEmailAddress
  );
  this.emailCollected = true;
}
```

### Example 3: Validate Email Before Submission

```javascript
if (!window.OrdioEmailModalUtils.validateEmail(this.exportEmailAddress)) {
  this.emailError = "Bitte geben Sie eine gültige E-Mail-Adresse ein.";
  return;
}
```

### Example 4: Get UTM Data for API Call

```javascript
const utmData = window.OrdioEmailModalUtils.getUTMData();
// Use utmData in API call
```

## Browser Compatibility

- Modern browsers (Chrome, Firefox, Safari, Edge)
- Requires `localStorage` support
- Requires `document.cookie` support
- Gracefully handles missing features

## Related Documentation

- [Email Modal Component](EMAIL_MODAL_COMPONENT.md) - Component that uses these utilities
- [UTM Tracking System](UTM_TRACKING_SYSTEM.md) - UTM tracking system documentation
- [Form-to-Page Mapping](../forms/FORM_TO_PAGE_MAPPING.md) - Which tools use these utilities