Documentation & System Encyclopedia

MarbleSend operates on a single master background runner: worker.php. The dashboard inspects cm_settings['worker_last_run'] to determine if cron is firing every 60 seconds.

The growth visualizer renders volume distribution across four selectable timeframes: 7 Days, 30 Days, 90 Days, and Year-to-Date (YTD). Each bar represents an aggregated time bucket, displaying sent count and open count on hover.

The right-column feed surfaces recent campaign dispatches in real time, featuring animated status badges (Completed, Sending pulse, Failed, Draft), delivery ratios, and a persistent system heartbeat status card.

The bottom audit table lists recent broadcast executions with full metadata: campaign name, lifecycle status, origin tag (manual, recurring schedule, RSS feed, or unopened resend), recipient dispatch ratio, and verified open rate.

When your sending domain lacks verified SPF, DKIM, or DMARC records, MarbleSend highlights an attention banner directly above the KPI metrics. Clicking Verify Domain DNS opens the 4-step diagnostic wizard under /settings?tab=deliverability, preventing users from burning domain reputation on unauthenticated mailboxes.

Direct action triggers linking the overview dashboard to high-velocity workflows: automated recurring newsletter schedules, RSS-to-email digest pipelines, subscriber list acquisition, double opt-in verification, and suppression protection.

Whenever a broadcast is actively dispatching, a sticky monitor banner slides into view at the top of /campaigns. It polls /api/campaigns/:id/progress every 1.5 seconds without full page refreshes.

The left column allows laser-focused subscriber targeting. Admins can filter by custom contact tags, search by partial email/name, and select individual contacts or hit Select All Matching.

To prevent catastrophic mistakes (e.g. sending emails with broken placeholders, missing unsubscribe links, or spam triggers), MarbleSend requires a preflight check before launching.

Before committing thousands of emails to the queue, the Send Test Email button dispatches an instant single test message directly to the administrator or QA mailbox without touching the database recipient list. All placeholder tags ({{first_name}}, {{email}}, {{unsubscribe_link}}) are populated with mock preview values so you can inspect email rendering across Gmail, Apple Mail, and Outlook.

All outbound anchor tags (<a href="...">) are processed through App\Services\TrackingInjector. UTM parameters (utm_source, utm_medium, utm_campaign, utm_content) are appended automatically before click-redirection wrapping. Mailto links, tel links, and unsubscribes are preserved untouched.

The full history portfolio provides multi-attribute filtering across origin (manual, recurring, rss, resend_unopened), status (completed, sending, failed, draft), and date range. Admins can multi-select campaigns to download aggregated CSV delivery logs.

Under /campaigns/:id/report, MarbleSend presents a comprehensive post-campaign report:

Centralized repository for all marketing, transactional, and autoresponder email templates. Features instant client-side search filtering, immutable URL slug IDs, and live draft status indicators.

Modern desktop email engines (notably Microsoft Outlook using Word HTML) do not support CSS Grid or Flexbox. MarbleSend ships with 8 responsive, table-based layouts battle-tested across Gmail, Outlook, Apple Mail, and Yahoo:

A focused code editor engineered for email developers, featuring tab indent trapping, real-time character count telemetry, and an automated whitespace normalizer.

Simulates desktop and mobile email clients within an isolated iframe sandbox, protecting the dashboard interface from rogue styles while providing instant visual feedback.

At delivery time, the template engine dynamically replaces tokens with recipient attributes, secure tracking links, syndicated RSS article summaries, and News posts.

A modal-driven diagnostic tool allowing senders to dispatch test emails to any recipient address via selected SMTP profiles before scheduling or broadcasting.

Integrated AI Copywriter operating directly via BYOK (Bring Your Own Key) to generate and refine high-converting, email-safe templates with zero third-party proxy latency.

Scans email subject lines across your entire template library, evaluating open-rate probability, spam filter risk, and character truncation with 1-click variant suggestions.

Write articles in the Posts tab of Templates (Markdown with live preview). A Newsletter schedule set to “News posts” sends each Ready post once, oldest first, by filling the {{news_posts}} placeholder of its template. Posts live only in your email — there is no public page.

MarbleSend provides two synchronized operating views tailored for different workflow needs: a compact Bento-grid Schedule Manager (/schedules) and an expansive interactive Monthly Calendar (/schedules/list).

Recurring schedules are powered by SchedulerService::computeNextRun(), which eliminates manual timestamp calculation in favor of robust PHP DateTimeImmutable mathematics.

MarbleSend connects directly to your blog or content feed using native SimpleXML and cURL, converting new articles into automated subscriber campaigns without third-party integration tools.

Unlike static campaign snapshots, scheduled broadcasts resolve their recipient lists dynamically at the exact second the occurrence triggers.

Every automated run creates an immutable audit row in cm_schedule_occurrences, detailing execution timestamps, outcomes, recipient counts, and error telemetry.

Administrators can bypass the countdown timer and immediately trigger an unscheduled broadcast of any schedule using the "Trigger Send Now" action.

MarbleSend features an enterprise concurrency perimeter designed specifically to prevent duplicate broadcasts on budget shared hosting environments.

The dynamic Optimization Tip card on the Schedules page provides 8 actionable, production-proven operational recommendations for reliable shared-hosting delivery:

A Newsletter schedule can now send articles instead of one fixed template. Set Content source to “News posts” and each run delivers the next Ready posts from Templates → Posts, inserted into the template through {{news_posts}}. Nothing is sent when no post is waiting.

1. 1Open Templates → Posts and write your article in Markdown.
2. 2Create or open a template and place {{news_posts}} where articles should appear (the “News Posts Newsletter” starter already has it).
3. 3Open Schedules → New, keep the type on Newsletter and set Content source to “News posts”.
4. 4Choose the template, audience, SMTP profile, posts per email (1–20) and the cadence.
5. 5Save. Only posts that become Ready after this moment can be sent by this schedule.
6. 6Mark the post Ready. The next occurrence — or Run now — delivers it.

• Switching a schedule from Template only to News posts sets a new cut-off at that moment; switching back clears it.
• Saving the schedule form re-checks that the template contains {{news_posts}}. Pause and Resume only flip the on/off switch and never re-check it, so you can always pause.
• Smart Suppression is switched off automatically in News posts mode: it would exclude everyone who received an earlier issue.
• News posts is available for Newsletter schedules only; RSS schedules keep their own feed logic.

• The schedule list labels these schedules “News posts” instead of “Newsletter”.
• The detail panel shows how many Ready posts are waiting for this schedule.
• In the form, templates without {{news_posts}} are flagged, and a warning appears if you pick one.

MarbleSend decouples campaign execution from delivery relays with two robust transport models: (1) Bring Your Own (BYO) SMTP for connecting your existing mail servers, and (2) Managed Amazon SES Relay via admin.marblesend.com for instant cloud delivery with zero AWS setup. Supports Option 1 Friendly From (0 DNS configuration) and Option 2 Custom Domain Easy DKIM with dynamic pricing and atomic credit management.

# Check resolution via dig (macOS / Linux):
dig CNAME <token1>._domainkey.yourdomain.com +short

# Check resolution via nslookup (Windows / PowerShell):
nslookup -type=CNAME <token1>._domainkey.yourdomain.com

MarbleSend sends email in the background. A cron job is a timer in your hosting panel that wakes MarbleSend up every minute so it can run schedules and autoresponders, retry failed deliveries, collect bounces and keep a long Campaign going. A Campaign you send starts at once, but everything that has to happen later depends on this timer. If Settings → System shows Cron Not Detected, the timer is missing, is not running every minute, or points to the wrong place. The three steps below fix that.

For technical users

Email compilation, audience query resolution, delivery dispatch, and webhook processing operate asynchronously via a 1-minute background worker. MarbleSend employs a dual-entrypoint architecture (native CLI worker.php or HTTP cron.php) protected by non-blocking file locks to eliminate overlapping executions on resource-constrained shared hosting.

* * * * * php /home/USER/your-folder/worker.php >/dev/null 2>&1

GET https://your-domain.com/cron.php?token=SECURE_TOKEN

MarbleSend is engineered as an internationally accessible self-hosted platform. It ships with 23 complete human-curated native language dictionaries, automatic Right-to-Left layout mirroring for Arabic, persistent tri-state theme customization, and an impenetrable single-tenant security perimeter.

The REST API allows external websites, landing pages, mobile apps, and the official MarbleSend Forms WordPress plugin to securely interact with your contact database and broadcast engine. API keys use cryptographic prefixing, one-way SHA-256 storage, and granular capability scoping.

Webhooks provide real-time HTTP event streaming to external endpoints, allowing downstream CRM syncs, Slack notifications, or custom automation pipelines to react instantly to subscriber opt-ins, campaign broadcasts, unsubscribes, and hard bounces.

Email deliverability determines whether your messages land in the subscriber inbox or get diverted to spam. MarbleSend features a built-in DNS inspection engine that runs four sequential, non-blocking queries directly against authoritative nameservers without third-party API dependencies.

MarbleSend provides a flexible dual-mode AI engine for copywriting, subject line generation, and spam score audits: (1) Bring Your Own Key (BYOK) for connecting directly to major LLM providers with zero markup, and (2) MarbleSend AI Credits for instant, pay-as-you-go access to curated, top-performing models without creating developer accounts or managing API keys.

MarbleSend verifies product authenticity using Ed25519 asymmetric cryptography via PHP's native libsodium extension. A signed License Grant Token is issued upon initial activation and validated locally without constant connection demands.

The plugin calls the MarbleSend REST API over HTTPS, so WordPress and MarbleSend can run on different servers. It has no access to the MarbleSend database.

curl -X POST https://your-domain.com/api/contacts \
  -H "Authorization: Bearer ms_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"email":"visitor@example.com","name":"John Doe","tags":["newsletter","source:wpforms"]}'

A slow or unreachable MarbleSend shouldn't make a visitor's form hang or lose a lead. Submissions from form plugins are queued and sent in the background.

// Non-blocking submission buffer in WordPress
set_transient('marblesend_forms_queue_' . wp_generate_uuid4(), $payload, 3600);
if (!wp_next_scheduled('marblesend_forms_process_queue')) {
    wp_schedule_single_event(time() + 5, 'marblesend_forms_process_queue');
}

The plugin includes a subscribe form, so you don't need a form builder. Add it with a shortcode, a Gutenberg block or a widget. All three run the same code.

[marblesend_form tags="newsletter,inbound" show_name="1" consent="I agree to receive email updates and accept the privacy policy."]

WPForms is one of the most used form builders. The plugin reads the submission once WPForms has validated it, so you need no WPForms add-on.

add_action('wpforms_process_complete', function($fields, $entry, $form_data, $entry_id) {
    $email = $fields[1]['value'] ?? ''; // Numeric Field ID #1
    $name  = $fields[0]['value'] ?? ''; // Numeric Field ID #0
    MarbleSend_Integration_Base::dispatch('wpforms', $form_data['id'], $email, $name);
}, 10, 4);

Contact Form 7 defines its fields as tags in a text template. The plugin hooks in after the form's email has been sent.

add_action('wpcf7_mail_sent', function($contact_form) {
    $submission = WPCF7_Submission::get_instance();
    $data = $submission ? $submission->get_posted_data() : [];
    $email = $data['your-email'] ?? '';
    $name  = $data['your-name'] ?? '';
    MarbleSend_Integration_Base::dispatch('cf7', $contact_form->id(), $email, $name);
}, 10, 1);

The plugin listens to the action Fluent Forms fires after it saves an entry.

add_action('fluentform/submission_inserted', function($entryId, $formData, $form) {
    $email = $formData['email'] ?? '';
    $name  = is_array($formData['names'] ?? null) ? implode(' ', $formData['names']) : ($formData['first_name'] ?? '');
    MarbleSend_Integration_Base::dispatch('fluentforms', $form->id, $email, $name);
}, 10, 3);

The plugin reads the entry right after Formidable Forms saves it.

add_action('frm_after_create_entry', function($entryId, $formId) {
    $entry = FrmEntry::getOne($entryId, true);
    $email = $entry->metas[12] ?? $entry->metas['email-address'] ?? '';
    $name  = $entry->metas[11] ?? $entry->metas['full-name'] ?? '';
    MarbleSend_Integration_Base::dispatch('formidable', $formId, $email, $name);
}, 30, 2);

The plugin listens to the hook Forminator fires while it processes a submission.

add_action('forminator_custom_form_submit_before_set_fields', function($formId, $response, $fieldData) {
    $fields = array_column($fieldData, 'value', 'name');
    $email  = $fields['email-1'] ?? '';
    $name   = $fields['name-1'] ?? '';
    MarbleSend_Integration_Base::dispatch('forminator', $formId, $email, $name);
}, 10, 3);

Capturing an email is the first step. Tags decide what happens to the contact next.

{
  "email": "lead@agency.com",
  "name": "Jane Smith",
  "tags": ["source:wpforms", "ebook-download", "vip-inbound"],
  "consent_source": "api"
}