# Campaigns and Contacts

In Convert Plus, a **campaign** (also called a "list") is the connection between a conversion module (modal, slide-in, info bar) and an email provider or local subscriber storage. Campaigns are managed from **WP Admin > Campaigns**.

## Data Model

Campaigns are stored in the `smile_lists` WordPress option as a keyed array:

```php
$smile_lists = get_option( 'smile_lists' );
// Structure:
$smile_lists[ $list_id ] = array(
    'list-name'     => 'My Newsletter',
    'list-provider' => 'Convert Plug',  // or external provider name
    'list'          => '',              // External provider list ID
    'date'          => '1-1-2024',      // Creation date
    // Provider credentials stored here when an addon is used
    // Subscribers (when provider = 'Convert Plug'):
    'subscribers'   => array(
        array(
            'email' => '[email protected]',
            'name'  => 'John Doe',
            // ... additional form fields
        ),
    ),
);
```

`$list_id` is a unique identifier generated at campaign creation time.

## Creating a Campaign

1. Go to **WP Admin > Campaigns > Create New Campaign**
2. **Step 1**: Enter a campaign name
3. **Step 2**: Select a list provider
   - **Convert Plug** — stores subscribers locally in the database
   - External providers appear if their addon plugins are installed (see [Email Integrations](Email-Integrations))
4. Click Save — triggers the `smile_add_list` AJAX action

### `smile_add_list` AJAX Handler

- Verifies nonce (`cp-create-list-nonce`)
- Checks for duplicate campaign names via `is_campaign_exists()`
- Saves the new campaign to `smile_lists`
- Returns the new campaign ID and redirect URL

## Linking a Campaign to a Module

When editing a Modal, Slide-In, or Info Bar style, you select a campaign from the "Mailer" dropdown in the customizer. The selected campaign ID is saved in the style settings.

When a visitor submits the opt-in form, the hidden field `mailer` contains the campaign ID:

```html
<input type="hidden" name="mailer" value="1704067200abc123" />
```

## Subscriber Capture

When a visitor submits an opt-in form, `cp_add_subscriber` handles the request:

1. Nonce verified: `cp-submit-form-{style_id}`
2. Style looked up to find the assigned campaign
3. Campaign looked up in `smile_lists` to find the provider
4. If provider is `Convert Plug`:
   - `cp_add_subscriber_contact()` appends the subscriber to `smile_lists[{list_id}]['subscribers']`
5. On success: `smile_update_conversions()` increments the conversion counter for the style

## Viewing Contacts

**WP Admin > Campaigns > [Campaign Name] > Contacts**

Shows a paginated list of all subscribers for that campaign with the date they subscribed.

## Exporting Contacts

Contacts can be exported to CSV:

- **Single campaign**: `admin_post_cp_export_list` — triggers `handle_cp_export_list_action()`
- **All campaigns**: `admin_post_cp_export_all_list` — triggers `handle_cp_export_all_list_action()`

The export builds a CSV using `cp_generate_csv()` and streams it as a file download.

### CSV Structure

```
Email, Name, Date, [additional fields...]
[email protected], John Doe, 2024-01-15, ...
```

## Campaign Analytics

Each campaign has an analytics view showing aggregated data across all styles that use it. See [Analytics System](Analytics-System) for details.

## Deleting a Campaign

Campaigns can be deleted (trashed) from the campaign dashboard. The `cp_trash_list` AJAX action handles this. Before deletion, `cp_before_delete_action_init` filter fires (`cp_before_delete_action`) to allow cleanup.

## Custom Form Integration

When `mailer` is set to `custom-form`, the form submission is not routed to any provider. This allows using the form purely for triggering custom actions (e.g. a redirect on success).

## Utility Functions

| Function | Description |
|----------|-------------|
| `cp_generate_option( $list_id )` | Generates HTML `<option>` elements for a campaign's connected list |
| `cp_get_list_name_by_id( $list_id, $provider )` | Returns the human-readable list name |
| `cp_check_in_array( $value, $array, $key )` | Custom array search helper |
| `cp_clean_string( $string )` | Sanitizes a string for safe use |
| `cp_search_key_in_array( $array, $key )` | Searches for a key recursively in an array |

## Related Pages

- [Email Integrations](Email-Integrations)
- [Analytics System](Analytics-System)
- [AJAX Actions Reference](AJAX-Actions-Reference)
- [Module System](Module-System)