# Bilbok Bulk Mailer for Flamingo (v3.0.0)

> Send safe, rate‑limited email campaigns to your Flamingo (Contact Form 7) contacts – with a built‑in queue and campaigns manager.

[![License](https://img.shields.io/badge/license-GPLv2%2B-blue.svg)](https://www.gnu.org/licenses/gpl-2.0.html)

Bilbok Bulk Mailer for Flamingo is a lightweight WordPress plugin that turns your existing [Flamingo](https://wordpress.org/plugins/flamingo/) address book into a simple bulk email tool.

It **does not** try to replace full‑blown email marketing services.  
Instead, it focuses on:

- Using **contacts you already have** in Flamingo
- Sending via **your own SMTP** (Gmail, transactional providers, …)
- Throttling and queuing email traffic to keep your account safe

---

## Features

- **Campaigns**
  - Create named campaigns with subject and HTML body.
  - See total emails, sent, remaining, and status (`pending`, `running`, `paused`, `completed`).
  - Start, pause, edit, and delete campaigns from a single screen.

- **Flamingo integration**
  - Select recipients from any **Flamingo channel** (one per CF7 form).
  - Add **manual email addresses**, one per line.
  - Recipients are deduplicated and validated with `is_email()`.

- **Queue & rate limiting**
  - Emails are added to a queue and sent in small chunks every 5 minutes.
  - You can configure **max emails per hour** (e.g. 80/hour).
  - Designed to play nicely with Gmail and other SMTP providers.

- **Unsubscribe / blacklist**
  - Global blacklist of email addresses (one per line).
  - Blacklisted addresses are excluded from all campaigns.

- **Credit footer (optional)**
  - Optional footer at the bottom of each outgoing email:
    > “This email was sent with Bilbok Bulk Mailer for Flamingo by DERHAL.IR”
  - Can be turned on/off in the settings.
  - Developers can override the footer using the `bilbok_cf7bm_email_footer_html` filter.

- **Test emails**
  - Global “Send test email” from the Settings page.
  - Campaign‑specific test email, sent without touching the queue.

- **Developer friendly**
  - Fully translatable (i18n).
  - No external SaaS or phone‑home code.
  - Clean, OOP PHP with clear filters and actions.

---

## Requirements

- WordPress 5.6+
- PHP 7.4+
- [Flamingo](https://wordpress.org/plugins/flamingo/) plugin (for `flamingo_inbound` posts and channels).
- Strongly recommended: an SMTP plugin (e.g. [WP Mail SMTP](https://wordpress.org/plugins/wp-mail-smtp/)).

---

## Installation

1. Clone or download this repository into your WordPress plugins directory:

       wp-content/plugins/bilbok-bulk-mailer-for-flamingo

2. Activate the plugin through **Plugins → Installed Plugins**.
3. Make sure **Flamingo** is installed and active.
4. Go to **Bilbok Bulk Mailer → Settings** and configure:
   - From email address
   - Max emails per hour
   - Default test email
   - Credit footer visibility
   - Blacklist (unsubscribe) emails
5. Go to **Bilbok Bulk Mailer → Campaigns** and create your first campaign:
   - Choose a Flamingo channel (optional).
   - Add manual emails (optional).
   - Write your subject and HTML content.
   - Send a test campaign to yourself.
   - Enqueue the campaign.

The WordPress cron job `bilbok_cf7bm_cron_send` will process campaigns every 5 minutes, sending emails in safe batches.  
Only **one campaign at a time** is processed; older pending/running campaigns have priority.

---

## Usage

### Creating a campaign

1. Navigate to **Bilbok Bulk Mailer → Campaigns**.
2. Click **Add New Campaign**.
3. Enter a **campaign name**.
4. (Optional) Select a **Flamingo channel** to use its contacts as recipients.
5. (Optional) Enter **manual email addresses**, one per line.
6. Set:
   - **From email** (should match your SMTP plugin settings).
   - **Rate (emails per hour)**.
   - **Approximate start time**.
7. Enter the **email subject** and **HTML content**.
8. Use **Send test campaign** to send the email to your own test address.
9. When you are happy with the result, click **Create campaign and enqueue emails**.

### Managing campaigns

On the **Campaigns** screen you can:

- See all campaigns, their status and statistics.
- Use **Start** to start a pending/paused campaign.
- Use **Pause** to temporarily stop a running campaign.
- Use **Edit** to change subject/content/rate/start time.
- Use **Delete** to remove a campaign and all its queued emails.

---

## Filters & Actions

### `bilbok_cf7bm_mail_before_send`

Filter the email data before it is sent (used internally to inject the footer, but available for customization):

```php
add_filter( 'bilbok_cf7bm_mail_before_send', function ( $email_data, $row ) {
    // $email_data = [to, subject, message, headers, campaign_id, queue_id]
    return $email_data;
}, 10, 2 );

### 'bilbok_cf7bm_email_footer_html'
Customize the credit footer HTML:
add_filter( 'bilbok_cf7bm_email_footer_html', function ( $footer_html, $campaign_id ) {
    // Return your own HTML footer, or modify the default
    return $footer_html;
}, 10, 2 );

Contributing
Pull requests, bug reports and feature requests are welcome.

Website: DERHAL.IR
Issues: please open an issue in this repository.
License
Bilbok Bulk Mailer for Flamingo is licensed under the GPLv2 or later.



بیلبوک بولک میلر برای فلامینگو (فارسی)
Bilbok Bulk Mailer for Flamingo یک افزونه سبک وردپرسی است که به شما اجازه می‌دهد برای مخاطبانی که قبلاً در افزونه Flamingo ذخیره شده‌اند (معمولاً از فرم‌های Contact Form 7)، کمپین‌های ایمیلی ارسال کنید.

این افزونه جایگزین سرویس‌های بزرگ ایمیل مارکتینگ نیست؛ بلکه تمرکز آن روی این موارد است:

استفاده از مخاطبانی که همین حالا در اختیار دارید
ارسال از طریق SMTP خودتان (مثل Gmail)
کنترل سرعت ارسال و استفاده از صف ارسال تا ایمیل‌ها ایمن و مرحله‌ای ارسال شوند
امکانات
کمپین‌ها

ساخت کمپین با نام، عنوان و متن HTML.
مشاهده تعداد کل ایمیل‌ها، ارسال‌شده‌ها، باقی‌مانده و وضعیت (pending, running, paused, completed).
شروع، توقف، ویرایش و حذف کمپین از یک صفحه.
اتصال به Flamingo

انتخاب گیرندگان از روی کانال‌های Flamingo (هر فرم CF7 یک کانال).
افزودن ایمیل‌های دستی (هر ایمیل در یک خط).
حذف تکراری‌ها و اعتبارسنجی ایمیل‌ها.
صف و محدودیت سرعت

ایمیل‌ها وارد صف می‌شوند و هر ۵ دقیقه در چند دسته کوچک ارسال می‌شوند.
می‌توانید حداکثر تعداد ایمیل در ساعت را تنظیم کنید (مثلاً ۸۰ ایمیل در ساعت).
مناسب برای استفاده با Gmail و افزونه‌های SMTP.
لیست سیاه / لغو اشتراک

در تنظیمات، لیستی از ایمیل‌هایی که هرگز نباید برایشان ایمیل ارسال شود (unsubscribe).
این آدرس‌ها از تمام کمپین‌ها حذف می‌شوند، حتی اگر در Flamingo ذخیره شده باشند.
فوتر اعتباری (اختیاری)

نمایش متن اعتباری در انتهای ایمیل‌های کمپین:
«This email was sent with Bilbok Bulk Mailer for Flamingo by DERHAL.IR»

قابل غیرفعال‌سازی از صفحه تنظیمات.
قابل شخصی‌سازی برای توسعه‌دهندگان از طریق فیلتر bilbok_cf7bm_email_footer_html.
ایمیل تست

دکمه «ارسال ایمیل تست» در صفحه تنظیمات کلی.
دکمه «ارسال تست کمپین» در فرم ساخت/ویرایش کمپین.
نصب و راه‌اندازی
پوشه افزونه را در مسیر زیر قرار دهید:

text

wp-content/plugins/bilbok-bulk-mailer-for-flamingo
از بخش «افزونه‌ها → افزونه‌های نصب‌شده» آن را فعال کنید.

افزونه Flamingo را نصب و فعال کنید.

به Bilbok Bulk Mailer → Settings / تنظیمات بروید و:

ایمیل فرستنده (From)
حداکثر ایمیل در ساعت
ایمیل پیش‌فرض تست
فوتر اعتباری و لیست سیاه ایمیل‌ها
را تنظیم کنید.

به Bilbok Bulk Mailer → Campaigns / کمپین‌ها بروید و اولین کمپین خود را بسازید:

نام کمپین
انتخاب کانال Flamingo (اختیاری)
وارد کردن ایمیل‌های دستی (اختیاری)
تنظیم زمان شروع و نرخ ارسال
نوشتن عنوان و متن ایمیل
ارسال تست و سپس افزودن کمپین به صف
کرون وردپرس هر ۵ دقیقه کمپین‌ها را پردازش می‌کند و تا پایان هر کمپین، کمپین بعدی را در صف نگه می‌دارد.

مجوز
این افزونه تحت مجوز GPLv2 یا بالاتر منتشر شده است.