# MailCannon WordPress Plugin

## Description

MailCannon – Email Marketing & Campaign Sender connects your WordPress site to the MailCannon SaaS platform so you can send MailCannon campaigns to your WordPress users or WooCommerce customers directly from the WordPress admin.

Contacts are **not** managed in WordPress. Contacts are managed in the MailCannon dashboard:
https://mailcannon.pro/dashboard/contacts

When you send a campaign from WordPress, MailCannon will automatically create the contact in your MailCannon account if it does not already exist.

Website: https://mailcannon.pro

## Features

- Connect WordPress to MailCannon via API key
- Fetch campaigns from your MailCannon account
- Select WordPress users as recipients
- Select WooCommerce customers as recipients (WooCommerce installed)
- Send bulk campaigns from the WordPress admin
- Automatically create contacts in MailCannon when sending

## Requirements

- WordPress 6.0+ (recommended)
- PHP 7.4+
- Optional: WooCommerce (to select WooCommerce customers)

## Installation

### Method 1 – WordPress Admin

1. Download the plugin ZIP.
2. In WordPress, go to **Plugins → Add New → Upload Plugin**.
3. Choose the ZIP file and click **Install Now**.
4. Click **Activate Plugin**.

### Method 2 – Manual FTP Installation

1. Unzip the plugin archive.
2. Upload the `mailcannon-plugin` folder to:
   - `wp-content/plugins/`
3. In WordPress, go to **Plugins**.
4. Activate **MailCannon**.

## Configuration

1. Install and activate the plugin.
2. In WordPress admin, open **MailCannon → Settings**.
3. Get your API key from:
   - https://mailcannon.pro/dashboard/settings
4. Paste your API key and click **Save**.
5. Click **Test Connection** to confirm WordPress can access your MailCannon account.

## How To Send a Campaign

1. In WordPress admin, open **MailCannon → Send Campaign**.
2. Select the MailCannon campaign.
3. Select recipients from the list (WordPress users and/or WooCommerce customers).
4. Click **Send Campaign**.

The plugin sends the selected recipients to MailCannon for delivery.

## Recipients Source

Recipients are selected from your WordPress database:

- WordPress users
- WooCommerce customers (when WooCommerce is installed)

The plugin does not maintain a separate contacts list in WordPress.

## Contact Sync Behavior

Contacts are automatically created in MailCannon when sending emails.

Manage your contacts in the MailCannon dashboard:
https://mailcannon.pro/dashboard/contacts

## API Endpoint Used

The plugin uses this MailCannon API endpoint to send campaigns:

- POST `https://mailcannon.pro/api/v1/send-email-campaign-by-id`

Headers:

- `X-API-KEY: API_KEY`
- `Content-Type: application/json`

Example request:

```json
{
  "campaign_id": "123",
  "recipients": [
    "user@email.com",
    "customer@email.com"
  ]
}
```

## Admin Menu

After activation, you will see a new admin menu:

- MailCannon
  - Dashboard
  - Campaigns
  - Send Campaign
  - Settings

## Security

The plugin follows WordPress security best practices:

- WordPress nonces for all admin form submissions
- Sanitization of all incoming input (API key, filters, selected recipients)
- Output escaping in admin views
- Capability checks to restrict access to authorized roles (administrator, editor)

## FAQ

### Where do contacts come from?

Recipients are taken from your WordPress site users and (optionally) WooCommerce customers. The plugin does not store contacts in WordPress.

### Where do I manage contacts?

Contacts are managed in MailCannon:
https://mailcannon.pro/dashboard/contacts

### Where do I manage campaigns?

Campaigns are created and managed in your MailCannon account. The plugin fetches available campaigns from MailCannon and displays them under **MailCannon → Campaigns**.

### Why are emails sent through MailCannon?

MailCannon provides dedicated email campaign infrastructure, analytics, and deliverability features. This plugin uses MailCannon’s API to send campaigns reliably at scale.

### I don’t see any campaigns in WordPress. What should I check?

- Confirm your API key is set in **MailCannon → Settings**
- Click **Test Connection**
- Make sure you have campaigns available in your MailCannon account
- Use **MailCannon → Campaigns → Refresh**

## Screenshots

1. Dashboard
2. Campaign selection
3. Recipient selection
4. Settings page

## Changelog

### 1.0.0

- Initial release

## License

GPL v2 or later