# Square Thumbnails - Mailchimp Integration

This documentation covers the Mailchimp integration for both the newsletter functionality and the "Notify Me When Available" feature in the Square Thumbnails plugin.

## Overview

The Mailchimp integration serves two main purposes:

1. **Newsletter Subscription**: Allow website visitors to subscribe to your newsletter through a widget or shortcode
2. **Pro Notifications**: Allow users who sign up for notifications about the Pro version to be automatically added to your Mailchimp list

## Integration Components

1. **Mailchimp Class** (`class-square-thumbnails-mailchimp.php`)
   - Handles all direct interactions with the Mailchimp API
   - Contains methods for adding subscribers and retrieving list information
   - Uses predefined API credentials

2. **Mailchimp Setup Class** (`class-square-thumbnails-mailchimp-setup.php`)
   - Verifies and creates required merge fields in your Mailchimp list
   - Ensures proper data storage for domain tracking

3. **Newsletter Class** (`class-square-thumbnails-newsletter.php`)
   - Manages the newsletter form rendering and processing
   - Handles AJAX form submissions
   - Integrates with the Mailchimp class to send user data

4. **Newsletter Widget Class** (`class-square-thumbnails-newsletter-widget.php`)
   - Provides a WordPress widget for easy placement of the newsletter form
   - Configurable title and appearance

5. **Mailchimp Admin Class** (`class-square-thumbnails-mailchimp-admin.php`)
   - Adds an admin page for configuring and testing the Mailchimp integration
   - Provides tools to check and create required merge fields

## Setup Instructions

### 1. Mailchimp Account Configuration

Before using the newsletter functionality, you need to ensure that your Mailchimp account is properly configured:

1. Log in to your Mailchimp account
2. Navigate to your audience (list) settings
3. Go to "Settings" > "Audience fields and *|MERGE|* tags"
4. Make sure the following merge fields exist (or use the admin setup tool to create them):
   - **DOMAIN** (Text field) - Stores the website domain
   - **WEBSITE** (URL field) - Stores the full website URL
   - **SITENAME** (Text field) - Stores the website name
   - **SOURCE** (Text field) - Identifies the subscription source
   - **SIGNUP_DATE** (Text field) - Records when the user subscribed

### 2. Plugin Configuration

The plugin uses the Mailchimp API to connect to your account:

1. Go to WordPress admin > Settings > ST Mailchimp
2. Click the "Setup Mailchimp Merge Fields" button to automatically create required fields
3. Review the list information to confirm that all required merge fields are present
4. Test the integration using the test page link provided at the bottom of the admin page

### 3. API Credentials

Replace the placeholder values in the `Square_Thumbnails_Mailchimp` class constructor with your actual Mailchimp API key and List ID:

```php
public function __construct() {
    $this->api_key = 'your-api-key-here'; // Your Mailchimp API key
    $this->list_id = 'your-list-id-here'; // Your Mailchimp List ID
}
```

### 4. Using the Newsletter Widget

Once configured, you can add the newsletter subscription form to your website:

1. Go to WordPress admin > Appearance > Widgets
2. Drag the "Square Thumbnails Newsletter" widget to your desired widget area
3. Customize the title if needed
4. Save the widget settings

### 5. Using the Newsletter Shortcode

You can also add the newsletter form anywhere on your site using the shortcode:

```
[square_thumbnails_newsletter]
```

Shortcode attributes:
- `title` - Form title (default: "Subscribe to our Newsletter")
- `description` - Form description (default: "Sign up to receive our latest news and updates.")
- `button_text` - Submit button text (default: "Subscribe")
- `placeholder` - Email input placeholder (default: "Your email address")

Example with custom attributes:

```
[square_thumbnails_newsletter 
  title="Join Our Mailing List" 
  description="Get updates and special offers!" 
  button_text="Sign Up" 
  placeholder="Enter your email"
]
```

## Testing and Troubleshooting

### 1. Testing the Integration

Two test scripts are included to verify the integration works correctly:

- `test-mailchimp.php` - Tests basic Mailchimp API connectivity
- `test-mailchimp-domain.php` - Specifically tests the domain tracking functionality

### 2. Domain Tracking Issues

If the domain information is not appearing in your Mailchimp list:

1. Go to Settings > ST Mailchimp and click "Setup Mailchimp Merge Fields"
2. Check that the DOMAIN merge field was created successfully
3. Test a subscription using the test page
4. Check your Mailchimp account to verify the subscriber data
5. Look for the domain information in:
   - Merge fields (DOMAIN field)
   - Tags (domain should appear as a tag)
   - Subscriber source information

### 3. Error Handling

The integration includes comprehensive error handling and logging:

1. All errors are logged to the WordPress error log with the prefix `Square Thumbnails Mailchimp -`
2. Detailed error messages from the Mailchimp API are captured and logged
3. The integration will continue functioning even if the Mailchimp API call fails

## Security Considerations

1. The API key is hardcoded in the class and not exposed to users
2. All user inputs are sanitized before processing
3. The plugin uses WordPress nonce verification for form submissions

## Advanced Configuration

For more advanced configurations, you may want to modify:

1. The subscriber status (`subscribed` vs `pending` for double opt-in)
2. Additional merge fields to collect more information
3. Error handling behavior to provide more user feedback

## Technical Details

The integration uses the Mailchimp API v3 to:
1. Create and manage merge fields
2. Add subscribers to your list
3. Track subscription sources

Subscriber data includes:
- Email address
- Website domain
- Full website URL
- Website name
- IP address (for compliance)
- Subscription date
- Source information

All information is handled in compliance with GDPR and other privacy regulations.

## Support

For additional support with the Mailchimp integration, contact the plugin developer at `narcisbodea@gmail.com`.

Include the following information:
- WordPress version
- Square Thumbnails plugin version
- Description of the issue
- Error messages (if any)
- Screenshots (if applicable)